A directive gives further information to the JSP Container that applies to how the page is compiled. An example of this is to reference Java packages in a manner similar to the import statement.
<%@ directive attribute1="value1" %>
There are two main types of directive: page which lets you import packages or define an error page and include which lets you insert a file into the servlet class at the time the JSP file is compiled into a servlet. A third directive was introduced in JSP 1.1: taglib which defines a custom tag library to be used by the page.
<%@ page import = "package1.*, package2,*,..." %>
The page import directive includes a comma separated list of one
or more packages that the JSP file should import. The packages (and their classes)
are available to scriptlets, expressions, declarations, and tags within the JSP file.
An alternative to using a comma separated list is to use more than one page import
directive.
By default JSPs automatically import the following packages,
<%@ include file="URL" %>
The include directive inserts a file of text or more often code in a JSP file at translation time, when the JSP file is compiled. The include directive is effectively a cut and paste of the file into the JSP. Once the content is inserted into the JSP the result is then compiled. Note, the page is recompiled only when either the source file or the included file is modified.
Sequence diagram for the include directive.
The included file can pretty much be anything that you could have in an JSP, such as HTML, JSP code, plain text or indeed client side JavaScript.
The URL specified is normally interpreted relative to the JSP page but you can also tell the system to interpret the URL relative to the home directory by starting the URL with a forward slash.
For example, many web sites include a navigation bar on each page. Due to the problems with HTML frames this is usually implemented with the same HTML repeated for each page in the site. The include directive is an easy way of achieving this and also makes maintenance quicker.
The following is an example of the include directive where the first file, "main.jsp" embeds the output of the "date.jsp"
File 1: "main.jsp:" <html> <head><title>An Include Test</title></head> <body> <p> The current date and time is <%@ include file="date.jsp" %> </p> </body> </html>
File 2: "date.jsp:" <%@ page import="java.util.*" %> <%= (new java.util.Date() ).toLocaleString() %>
The resultant display in the browser is :
The current date and time is Aug 30, 1999 2:38:40
<%@ page errorPage="relativeURL" %>
The page errorPage directive takes a valid relative URL to a JSP file that
this JSP file will send any exceptions to. Typically error pages are used to
provide a more user friendly error message. If the URL begins with a /, the path
is relative to the JSP application's document root directory and is resolved by
the Web server. If not, the pathname is relative to the current JSP file.
<%@ page isErrorPage="true|false" %>
Works in tandem with the page errorPage directive and specifies that this JSP is an error page. If true, you can use the exception object, which contains a reference to the thrown exception, in the JSP file. If false (the default value), means that you cannot use the exception object in the JSP file.
There are other directives which are less common and details of these can be found in the JSP Specification.
<%@ page buffer="none|8kb|sizekb" %>
The page buffer directive controls the use of buffered output for a
JSP. Buffered output is where the HTML for a page is sent to the client
in chunks or packets of data. The default packet size is 8kb.
To turn off buffered output the value should be none otherwise you can
specify a size for the packet. This setting is rarley required however you may need to
use this directive when working with the JSP forward action which is discussed
later.
This topic looked at Declarations and Directives.
The following workshop looks at using JSP Directives.