November 22, 2014
Hot Topics:

Java Server Pages, The Page Directive

  • June 12, 2000
  • By Richard G. Baldwin
  • Send Email »
  • More Articles »

Java Programming, Lecture Notes # 758.

June 12, 2000


Introduction

What is JSP?

With JSP, fragments of Java code embedded into special HTML tags are presented to a JSP engine. The JSP engine automatically creates, compiles, and executes servlets to implement the behavior of the combined HTML and embedded Java code.

Previous lessons have explained the use of the following syntax elements:

  • Output comments
  • Hidden comments
  • Declarations
  • Expressions
  • Scriptlets
  • The include directive
This lesson will discuss the Page Directive.

What is the Page Directive?

The page directive is used to define attributes that apply to an entire JSP page.

According to Sun,
 
 

The page directive applies to an entire JSP file and any static files it includes with the Include Directive or <jsp:include>, which together are called a translation unit. 

Note that the page directive does not apply to any dynamic included files; see <jsp:include> for more information.

See my earlier lesson on the Include Directive for more information about the difference between static and dynamic files.

How many page directives can you have in a JSP page?

A page directive can be used to establish values for several different attributes that apply to the JSP page.

You can use the page directive more than once in a JSP page (translation unit).  However, (except for the import attribute), you can specify a value for each attribute only once.

The import attribute is similar to the import directive in a Java program, and accordingly you can use it more than once.

Where do I place the page directive?

You may place the page directive anywhere in the translation unit and it will apply to the entire translation unit.  For clarity and ease of understanding, it might be best to place it at the top of the primary JSP file.

What is the syntax of the page directive?

The syntax for a page directive is shown below.  Default values for the different attributes are highlighted in boldface where appropriate.  The [...] indicates that a term is optional.  The vertical bar (|) provides a choice between two values such as true and false.
 

<%@ page 
  [ language="java" ] 
  [ extends="package.class" ] 
  [ import= "{ package.class |
    package.* }, ..." ] 
  [ session="true|false" ] 
  [ buffer="none|8kb|sizekb" ] 
  [ autoFlush="true|false" ] 
  [ isThreadSafe="true|false" ] 
  [ info="text" ] 
  [ errorPage="relativeURL" ] 
  [ contentType="mimeType [
    ;charset=characterSet ]" | 
    "text/html ; charset=ISO-8859-1"
  [ isErrorPage="true|false" ]
%>

Sample Page Directives

Several sample page directives, used in the sample JSP page discussed later in this lesson are shown below.
 
<%@ page import="java.util.Date" %>
<%@ page import="java.awt.*" %>
<%@ page info="Info about the page" %>

I will discuss the behavior of these page directives in conjunction with my discussion of the sample JSP page.

Page Directive Attributes

language="java"

This attribute defines the scripting language used in scriptlets, declarations, and expressions in the JSP file and any included files.  In JSP 1.0, the only allowed value is java.

extends="package.class"

This attribute specifies a fully qualified name of a superclass that will be extended by the Java class in the JSP file.  Sun recommends that you,
 

Use this attribute cautiously, as it can limit the JSP engine's ability to provide a specialized superclass that improves the quality of the compiled file.

import= "{ package.class | package.* }, ..."

This attribute specifies a comma-separated list of one or more packages or classes that the JSP file should import.

The classes in the packages become available to scriptlets, expressions, declarations, and tags within the JSP file.

Multiple import directives are allowed

As might be expected, the import attribute must appear before the tag that refers to the imported class.  To import multiple packages, you can use a comma-separated list, more than one import directive, or a combination of the two.

This attribute is illustrated in the sample JSP page discussed later in this lesson.

session="true|false"

Here is what Sun has to say about this attribute.  If you don't know about sessions, this won't mean much to you at this point and you may need to study my tutorial lessons on servlets before trying to understand it.
 

Whether the client must join an HTTP session in order to use the JSP page. If the value is true, the session object refers to the current or new session. If the value is false, you cannot use the session object in the JSP file. The default value is true.

buffer="none|8kb|sizekb"

This attribute specifies the buffer size in kilobytes that will be used by the out object to handle output sent from the compiled JSP page to the client browser. The default value is 8kb.  According to Sun,
 

If you specify a buffer size, the output is buffered with at least the size you specified.

autoFlush="true|false"

This attribute specifies whether or not the output will be flushed automatically when the buffer is full.  For the default value of true, the buffer will be flushed.  If specified as false, an exception will be raised when the buffer overflows.  According to Sun,
 

you cannot set autoFlush to false when the value of buffer is none.

isThreadSafe="true|false"

This attribute specifies whether thread safety is implemented in the JSP file.  The default value of true means that the JSP engine can send multiple concurrent requests to the page.

If you use the default value, multiple threads can access the JSP page.  Therefore, you must synchronize your methods to provide thread safety.

For false, the JSP engine does not send concurrent requests to the JSP page.  You probably don't want to force this restriction on a high-volume server because it can significantly impair the ability of the server to deliver your JSP page to multiple clients.

If you don't know about thread safety and the synchronized keyword, see my earlier lesson on multithreaded programming.

info="text"

This attribute lets you specify a text string that is incorporated verbatim into the compiled JSP page.

You can retrieve the string later with the getServletInfo() method of the Servlet class.  This attribute is illustrated in the sample JSP page discussed later in this lesson.

errorPage="relativeURL"

This attribute specifies a pathname to a JSP file that this JSP file sends exceptions to.

According to Sun,
 

If the pathname 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.

If you don't know about exceptions, see my earlier lesson on exception handling in Java.

isErrorPage="true|false"

According to Sun, this attribute specifies,
 

Whether the JSP file displays 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.

If you don't understand all of this, you might want to study my lesson on exception handling in Java for background information on exception handling.

contentType="mimeType [ ;
  charset=characterSet ]" |
  "text/html;charset=ISO-8859-1"

This attribute specifies the MIME type and character encoding the JSP file uses for the response it sends to the client. According to Sun,
 

You can use any MIME type or character set that are valid for the JSP engine. The default MIME type is text/html, and the default character set is ISO-8859-1.

As of 2/14/00, you can find a discussion of MIME types at
mimetype.html

Sample JSP Page

Figure 1 shows a sample JSP file that contains three page directives.  The page directives are near the top of the file, and are highlighted in boldface to make them easy to find.

The import attribute

The first two page directives specify values for the import attribute.  You will recognize the values of these attributes as being very similar to the import directives in a Java program.

The info attribute

The third page directive specifies a value for the info attribute.  At the moment, I can't think of an analogy to the info attribute in a normal Java program, but its value can be accessed later in the JSP page using the getServletInfo() method of the Servlet class (as illustrated near the bottom of the page).

Path not required later

As with import directives in a Java program, the two import attributes make it possible to access the following class files without the requirement to provide a fully qualified path and file name each time the class file is referenced:

  • Date
  • Button
(Actually, because the wildcard (*) notation was used in the second import attribute, there are many other class files in the awt package that can also be referenced without the requirement to specify a full path name.)

References to Date and Button

The references to the Date and Button classes are highlighted in boldface near the middle of the file, and are pretty obvious.

An anonymous object of each of these classes is instantiated in two separate JSP expressions.

The Date object

The instantiation of the anonymous Date object with no constructor parameters causes a String to be inserted into the JSP page output containing the current date and time.

The Button object

The instantiation of the anonymous Button object causes the default String representation of a Button object to be inserted into the JSP page output.  It isn't very pretty, but it does serve to illustrate the use of the import attribute of the page directive.

Info about the page

The third page directive causes the String Info about the page to be associated with the page.

This String is later accessed and inserted into the JSP page output by invoking this.getServletInfo() inside a JSP expression.

The invocation of this method in the JSP page is also highlighted in boldface to make it easy to find (near the bottom of the page).

JSP page output

Figure 2 shows a replica of the output produced by accessing this JSP page using Netscape 4.7.  Accessing the JSP page using IE5.0 produced similar results.

As I mentioned earlier, the default string representation of the Button object near the middle of Figure 2 isn't very pretty, but it does serve to illustrate the use of the import attribute of the page directive.

Review

To review, the import attributes makes it possible to reference the Date and Button classes within the JSP page without the requirement to provide a fully-qualified path and file name for the class.

The info attribute makes it possible to associate an information string with the JSP page that can later be accessed using the getServletInfo() method of the Servlet class.

JSP Syntax Summary

In this and previous lessons, I have discussed the following JSP syntax:

Output comments:
<!-- comment [ <%= expression %> ] -->

Hidden comments:
<%-- hidden comment --%>

Declarations:
<%! declarations %>

Expressions:
<%= expression %>

Scriptlets:
<% code fragment %>

Include Directive:
<%@ include file="relativeURL" %>

Page Directive:
<%@ page
  [ language="java" ]
  [ extends="package.class" ]
  [ import= "{ package.class |
    package.* }, ..." ]
  [ session="true|false" ]
  [ buffer="none|8kb|sizekb" ]
  [ autoFlush="true|false" ]
  [ isThreadSafe="true|false" ]
  [ info="text" ]
  [ errorPage="relativeURL" ]
  [ contentType="mimeType [
    ;charset=characterSet ]" |
    "text/html ; charset=ISO-8859-1" ]
  [ isErrorPage="true|false" ]
%>
 

Copyright 2000, Richard G. Baldwin.  Reproduction in whole or in part in any form or medium without  express written permission from Richard Baldwin is prohibited. 

About the author

Richard Baldwin is a college professor and private consultant whose primary focus is a combination of Java and XML. In addition to the many platform-independent benefits of Java applications, he believes that a combination of Java and XML will become the primary driving force in the delivery of structured information on the Web.

Richard has participated in numerous consulting projects involving Java, XML, or a combination of the two.  He frequently provides onsite Java and/or XML training at the high-tech companies located in and around Austin, Texas.  He is the author of Baldwin's Java Programming Tutorials, which has gained a worldwide following among experienced and aspiring Java programmers. He has also published articles on Java Programming in Java Pro magazine.

Richard holds an MSEE degree from Southern Methodist University and has many years of experience in the application of computer technology to real-world problems.






Comment and Contribute

 


(Maximum characters: 1200). You have characters left.

 

 


Enterprise Development Update

Don't miss an article. Subscribe to our newsletter below.

Sitemap | Contact Us

Rocket Fuel