Tutorials : Server-Side Web Applications Using Servlets and JSP :
: JavaServer Pages (JSP)

5. JSP Directives

A JSP directive affects the overall structure of the servlet class. It usually has the following form:

<%@ directive attribute="value" %>

However, you can also combine multiple attribute settings for a single directive, as follows:

<%@ directive attribute1="value1" 
              attribute2="value2"
              ...
              attributeN="valueN" %>

There are two main types of directive: page, which lets you do things like import classes, customize the servlet superclass, and the like; and include, which lets you insert a file into the servlet class at the time the JSP file is translated into a servlet. The specification also mentions the taglib directive, which is not supported in JSP version 1.0, but is intended to let JSP authors define their own tags. It is expected that this will be the main new contribution of JSP 1.1.

5.1 The JSP page Directive

The page directive lets you define one or more of the following case-sensitive attributes:

• import="package.class" or import="package.class1,...,package.classN". This lets you specify what packages should be imported. For example:
  <%@ page import="java.util.*" %>
  The import attribute is the only one that is allowed to appear multiple times.
• contentType="MIME-Type" or
  contentType="MIME-Type; charset=Character-Set"
  This specifies the MIME type of the output. The default is text/html. For example, the directive
  <%@ page contentType="text/plain" %>
  has the same effect as the scriptlet
  <% response.setContentType("text/plain"); %>
• isThreadSafe="true|false". A value of true (the default) indicates normal servlet processing, where multiple requests can be processed simultaneously with a single servlet instance, under the assumption that the author synchronized access to instance variables. A value of false indicates that the servlet should implement SingleThreadModel, with requests either delivered serially or with simultaneous requests being given separate servlet instances.
• session="true|false". A value of true (the default) indicates that the predefined variable session (of type HttpSession) should be bound to the existing session if one exists, otherwise a new session should be created and bound to it. A value of false indicates that no sessions will be used, and attempts to access the variable session will result in errors at the time the JSP page is translated into a servlet.
• buffer="sizekb|none". This specifies the buffer size for the JspWriter out. The default is server-specific, but must be at least 8kb.
• autoflush="true|false". A value of true, the default, indicates that the buffer should be flushed when it is full. A value of false, rarely used, indicates that an exception should be thrown when the buffer overflows. A value of false is illegal when also using buffer="none".
• extends="package.class". This indicates the superclass of servlet that will be generated. Use this with extreme caution, since the server may be using a custom superclass already.
• info="message". This defines a string that can be retrieved via the getServletInfo method.
• errorPage="url". This specifies a JSP page that should process any Throwables thrown but not caught in the current page.
• isErrorPage="true|false". This indicates whether or not the current page can act as the error page for another JSP page. The default is false.
• language="java". At some point, this is intended to specify the underlying language being used. For now, don't bother with this since java is both the default and the only legal choice.

The XML syntax for defining directives is

<jsp:directive.directiveType attribute=value />

For example, the XML equivalent of

<%@ page import="java.util.*" %>

is

<jsp:directive.page import="java.util.*" />

5.2 The JSP include Directive

This directive lets you include files at the time the JSP page is translated into a servlet. The directive looks like this:

<%@ include file="relative url" %>

The URL specified is normally interpreted relative to the JSP page that refers to it, but, as with relative URLs in general, you can tell the system to interpret the URL relative to the home directory of the Web server by starting the URL with a forward slash. The contents of the included file are parsed as regular JSP text, and thus can include static HTML, scripting elements, directives, and actions.

For example, many sites include a small navigation bar on each page. Due to problems with HTML frames, this is usually implemented by way of a small table across the top of the page or down the left-hand side, with the HTML repeated for each page in the site. The include directive is a natural way of doing this, saving the developers from the maintenance nightmare of actually copying the HTML into each separate file. Here's some representative code:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<TITLE>Servlet Tutorial: JavaServer Pages (JSP) 1.0</TITLE>
<META NAME="author" CONTENT="webmaster@somesite.com">
<META NAME="keywords" CONTENT="...">
<META NAME="description" CONTENT="...">
<LINK REL=STYLESHEET
      HREF="Site-Styles.css"
      TYPE="text/css">
</HEAD>

<BODY>
<%@ include file="/navbar.html" %>

<!-- Part specific to this page ... -->

</BODY>
</HTML>

Note that since the include directive inserts the files at the time the page is translated, if the navigation bar changes, you need to re-translate all the JSP pages that refer to it. This is a good compromise in a situation like this, since the navigation bar probably changes infrequently, and you want the inclusion process to be as efficient as possible. If, however, the included files changed more often, you could use the jsp:include action instead. This includes the file at the time the JSP page is requested, and is discussed in the tutorial section on JSP actions.

NEXT

How to Add Java Applets to Your Site

New on the Java Boutique:

New Review:

Time Management Made Easy with the Quartz Enterprise Job Scheduler
Why not just use the Java timer API? This open source scheduling API boasts simplicity, ease-of-integration, a well-rounded feature set, and it's free!

New Applet:

Reverse Complement
Reverse Complement is a simple applet that converts DNA or RNA sequences into three useful formats.

Elsewhere on internet.com:

WebDeveloper Java
Lots of Java information on webdeveloper.com

WDVL Java
Thorough Java resource at the Web Developer's Virtual Library.

ScriptSearch Java
Hundreds of free Java code files to download.

jGuru: Your View of the Java Universe
Customizable portal with online training, FAQs, regular news updates, and tutorials.