JavaServer Sun Microsystems, Inc

JavaServerTM PagesTM - Specification 0.92

October 7, 1998



This document is an updated draft of the JavaServerTM PagesTM specification. It will be available for review and comment on this site until November 12, 1998, when it will be removed for update.

Comments received will be carefully considered and revisions made to the specification as necessary. We hope to have the revised specification available shortly thereafter.

Please send your comments and questions to:


Legal Notices


Copyright © 1998 Sun Microsystems, Inc.
901 San Antonio Road, Palo Alto, CA 94303 USA

All rights reserved. Copyright in this document is owned by Sun Microsystems, Inc.

Sun Microsystems, Inc. (SUN) hereby grants to you at no charge a nonexclusive, nontransferable, worldwide, limited license (without the right to sublicense) under SUN's intellectual property rights that are essential to use the JavaServer Pages 0.92 Specification ("Specification") for internal evaluation purposes only. Other than this limited license, you acquire no right, title, or interest in or to the Specification and you shall have no right to use the Specification for productive or commercial use.

Restricted Rights Legend

Use, duplication, or disclosure by the U.S. Government is subject to restrictions of FAR 52.227-14(g)(2)(6/87) and FAR 52.227-19(6/87), or DFAR 252.227-7015(b)(6/95) and DFAR 227.7202-1(a).

This software and documentation is the confidential and proprietary information of Sun Microsystems, Inc. ("Confidential Information"). You shall not disclose such Confidential Information and shall use it only in accordance with the terms of the license agreement you entered into with Sun.



Sun, the Sun logo, Sun Microsystems, JavaSoft, JavaBeans, JDK, Java, HotJava, HotJava Views, Visual Java, Solaris, NEO, Joe, Netra, NFS, ONC, ONC+, OpenWindows, PC-NFS, EmbeddedJava, PersonalJava, SNM, SunNet Manager, Solaris sunburst design, Solstice, SunCore, SolarNet, SunWeb, Sun Workstation, The Network Is The Computer, ToolTalk, Ultra, Ultracomputing, Ultraserver, Where The Network Is Going, Sun WorkShop, XView, Java WorkShop, the Java Coffee Cup logo, JavaServer, and JavaServer Pages are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.





Changes Since Release 0.91

  1. Tag and attribute name changes
  2. Supporting API changes

       com.sun.server.http.HttpServiceResponse.callPage(String uri, HttpServletRequest request)
    is now:
      javax.servlet.ServletContext.getRequestDispatcher(String uripath)

      com.sun.server.http.HttpServiceRequest.setAttribute(String key, Object o)
    is now:
      javax.servlet.ServletRequest.setAttribute(String key, Object o)

  3. Hierarchical naming introduced

    The DISPLAY, LOOP, INCLUDEIF, and EXCLUDEIF tags now use hierarchical naming, rather than Java object naming, to describe a Bean property. A hierarchical name would be constructed as:


    The use of colons (:) rather than periods (.) helps distinguish this naming convention from Java syntax.

Deletions to the 0.91 Specification

  1. The following directives have been removed:
  2. In the USEBEAN (previously BEAN) tag:

Additions to the 0.91 Specification

  1. A list of changes made to this specification since Release 0.91 (this section).
  2. An Overview section has been added to the document. It includes:
  3. A Session Tracking section has been added to the document.
  4. The concept of Applications has been added.
  5. Support for NCSA-style Server-side Includes has been added.
  6. The following tags have been added:
    1. For easily displaying Bean properties:
      • Of a single-valued Bean property
        <DISPLAY PROPERTY="[bean+:]property" >
      • Of a multivalued Bean property (that is, int[] foo() )
        <LOOP PROPERTY="[bean+:]property" PROPERTYELEMENT="propertyindex" > </LOOP>
        (used in conjunction with
        <DISPLAY PROPERTY="[bean+:]property" >)
    2. For conditional inclusion of statements :
  7. The following directives have been added:
    <%@ ERRORPAGE="pageURL" %>
  8. In the USEBEAN tag, the LIFESPAN attribute now can be set to application, as well as to page or session. (Page was previously called request.)
  9. The following implicit Beans have been added:

    1. An error Bean called exception, which holds information on the most recent error on a .jsp page request. This Bean can only be accessed from the page designated by the ERRORPAGE directive.
    2. A request environment Bean. You can use this Bean through implicit reference, but not directly by name, within the DISPLAY or INCLUDEIF tags. You can access this Bean by name in Java code, that is, within <% ... %> tags.
  11. A section Communicating About Bean Properties has been added that describes how a Bean developer might give information about Bean properties to a Web designer who is using those properties in a .jsp file.


Coming Attractions

The features listed below are being considered for Release 1.0 of the JavaServer Pages specification and reference implementation:




[ item ] Brackets surrounding an item indicate that the item is optional.
item + A plus sign following an item indicates that the item may occur one or more times.
item ... Ellipsis points following an item indicates that some elements following the item have not been shown.
item | item | item Vertical bars separating several items indicate that exactly one of those items must occur.
item1 item2 } Braces surrounding a set of items indicates the items appear as a group.


KEYWORD Uppercase characters are used to indicate reserved keywords.
variable This font is used to indicate variables -- placeholders for real values or characters.
bold Bold font is used to indicate characters that a user would type.
filename This typeface is used when referring to commands, files, or directories within a sentence.
code Constant width font is used for source code examples that are displayed separately from regular text.



The JavaServer Pages technology is a simple but powerful way to dynamically generate HTML on the server side.

With JavaServer Pages technology, you can quickly and easily create Web pages with dynamically generated content. When you write JavaServer Pages, you call reusable server components (such as JavaBeans) and automatically created data objects from an HTML file. This allows you to cleanly separate the generation of dynamic content from its presentation.

Not only will you find it faster and simpler to create dynamic Web pages using JavaServer Pages, but in most cases, the responses to client requests will be faster too. Because JavaServer Pages are processed on the server, the Web page can be compiled and stored in memory on the client for faster access. And, because the client receives only plain HTML, client-machine limitations are less of a concern.

Finally, you'll find you have access to a powerful scripting solution -- JavaTM. Because JavaServer Pages technology uses the Java programming language as its default scripting language, scripting on the server side can take full advantage of the powerful set of capabilities offered by the Java programming language.


Why JavaServer Pages?

We built the JavaServer Pages technology to help you write dynamic Web pages as easily and simply as possible, with maximum power and flexibility. As we developed the JavaServer Pages technology, we held your needs firmly in mind as our primary design goals. These needs, as we envisioned them, are:

  1. Allows you to write once, run anywhere.

    The JavaServer Pages technology is entirely platform-independent, both in its dynamic Web pages and its underlying server components. You can write the dynamic Web pages on any platform, run them on any Web server, and access them from any Web browser. You can also build and run the server components, which are JavaBeans or Java Servlets, on any server platform.


  3. Emphasizes components.

    JavaServer Pages emphasizes the use of reusable, cross-platform server components written in Java. This saves you considerable development time while giving you the power and flexibility of JavaBeans and Java Servlets. And because components do much of the processing work, component development is more cleanly separated from Web design, improving the productivity of cross-functional teams.


  5. Acts as the front door to the Java Platform for the Enterprise.

    JavaServer Pages is an integral part of the Java Platform for the Enterprise, which brings Java technology to enterprise computing. You can now develop powerful enterprise-wide or middle-tier server applications, using a JavaServer Pages Web site as a front end. When you want to update your application, you can update the components and dynamic Web pages that reside on the server, and all of your users are updated at once.


  7. Makes dynamic Web sites easy to build.

    JavaServer Pages are HTML files written in a combination of industry-standard HTML, JavaServer Pages HTML tags, and -- if you like -- Java as a scripting language. A JavaServer Pages file has the extension .jsp and calls reusable components that reside on the server. It's as simple as that.

    In this release, the components are JavaBeans or Java Servlets, with support for Enterprise JavaBeans anticipated in a future release.


Typical User Roles

As we designed the JavaServer Pages technology, we tried to describe who the typical users might be. The actual users of JavaServer Pages technology, or their set of skills, may turn out to be slightly different than we anticipated. That's fine. We expect to learn even more about our users -- their skills and their needs -- as the technology continues to evolve.

Here's an initial description of who we expect will be typical users:

  1. Website or webpage designers


  2. Component programmers


  3. Dynamic HTML or browser scripting language writers


  4. Java Servlet writers


Implementation Assumptions

There are many possible implementation choices for the three key elements -- reusable components, scripting language, and compiled-page object -- of the JavaServer Pages technology.

JavaServer Pages presently supports JavaBeans as reusable components and Java as its scripting language. We anticipate third-party support soon for other popular scripting languages. JavaServer Pages are compiled into objects, frequently Java Servlets, although we anticipate third-party implementations using other object technologies.

To anchor this discussion of the JavaServer Pages technology in the concrete, however, it was necessary to select an implementation. For simplicity, we decided upon the following default implementations:

Reusable components:
Scripting language:
Compiled JavaServer Pages object:
Java Servlet

In this specification, we use JavaBeans, Java, and Java Servlets as an example of JavaServer Pages elements, not as a recommendation for your specific implementation.


JavaServer Pages Access Model

You can apply the JavaServer Pages technology in two ways:

Model 1: A request sent to a JavaServer Pages file

The user working in a client Web browser can make a request directly of a JavaServer Pages file.

Request comes directly from Client


After receiving the client request, the JavaServer Pages file requests information from a JavaBean. The JavaBean can in turn request information from an Enterprise JavaBean or a database. Once the JavaBean generates content (perhaps working with an Enterprise JavaBean, a database, or both), the JavaServer Pages file can query and display the Bean's content.

Model 2: A request sent to a Java Servlet

Another way to to use JavaServer Pages is to send a request to a Java Servlet.


Request comes from a Servlet


In this example, the client makes a request that is handled by a Java Servlet. The servlet generates the dynamic content -- in this example, the servlet uses JDBC to communicate with a database to obtain the content. The servlet then wraps the dynamic content into a bean. The JavaServer Pages file accesses the dynamic content from the bean and displays the content in the client web browser.


Common to both access models

In either Model 1 or Model 2, the JavaServer Pages file is identified to the server by a .jsp extension -- this tells the server that special handling is required. The first time a request is made for such a file -- either directly from a client browser or from a servlet -- the .jsp file is compiled into an object. (For that reason, there can be a slight delay on the first request for a .jsp page.) The output from the object is standard HTML which the browser interprets and displays as usual.

Common Page Compile - 2


After compilation, the compiled-page object is stored in memory on the server. On subsequent requests for that page, the server checks to see if the .jsp file has changed. If it has not changed, the server uses the compiled-page object stored in memory to generate the response to the client. (Because the object is stored in memory, the response is very fast.) If the .jsp file has changed, the server automatically recompiles the page file and replaces the object in memory.

Some examples of components that can be called from a JavaServer Pages file are JDBCTM or JavaTM BlendTM components. The results are obtained from the components by the JavaServer Pages, using standard Bean property readers, and are displayed using HTML.


As discussed in previous sections, the JavaServer Pages technology simplifies the creation and management of dynamic content by separating content generation from content presentation. Tags for content access and presentation reside in the webpage. Logic and programming code for content generation reside in reusable components.

This separation of generation from presentation is reflected in the design of the JavaServer Pages syntax. The syntax is component-centric, with the ability to add small sections of code if required. (This is in contrast to some other dynamic-content technologies which focus on scripting languages as the main mechanism, with some ability to include components.)

The syntax of JavaServer Pages can be roughly divided as follows:

For a description of the conventions used in describing syntax and code in this document, see the Conventions section of the Introduction.


Component-centric tags

These tags are simple to use and require no Java or scripting code. Like HTML, tag and attribute names are case-insensitive. Also like HTML, double-quotes around attribute values are recommended but not required.

Their similarity to HTML tags in both look and feel makes these component-centric tags easy to distinguish from the infrequently used scripting-centric tags. Also making them easy to distinguish, one from the other, is their use of a hierarchial naming convention when accessing dynamic content from components. (Scripting-centric tags use the standard variable naming conventions of the chosen scripting language.)

A hierarchical name is constructed as follows:


An example would be:

where the dateBean is a Bean containing a property called month.

The use of colons (:) rather than periods (.) also helps distinguish this naming convention from Java syntax. (Note that a property may, itself, be a Bean containing further properties. Such a situation is discussed in further detail in the Nested Properties section.)

Note: The one place hierarchical naming is not used in the component-centric tags is in the USEBEAN tag -- NAME and TYPE both use the Java variable naming convention.


Scripting-centric Tags

Syntax Notes:

  1. None of the above tags is required in a JavaServer Pages file. However, if a tag is used it may have a dependancy on other tags.
  2. In some cases, the order in which tags are used in the file is important. In no case is the order of attributes within a tag important.
  3. All tags may be used more than once but, within a tag, attributes are valid only once.
  4. Attribute values do not require double quotes around them unless they contain spaces, but double quotes are recommended.
  5. Tag and attribute names are case in-sensitive. However, attribute values (such as the values of the TYPE and NAME attributes in the USEBEAN tag) are case sensitive unless otherwise noted.

Dependancies, order, and the treatment of multiple instances of a tag are indicated in the tag descriptions which follow.

JavaServer Pages Beans


The syntax to refer to a Bean inside a .jsp file is defined by the USEBEAN tag. Any non-implicit Bean must first be declared this way before it and its properties can be accessed later in the .jsp file. The occurrence of a USEBEAN tag in the .jsp file triggers the start of the lifecycle for that Bean.

The general form of a JavaServer Pages USEBEAN tag is:

<USEBEAN NAME="nameofbeaninstance"
LIFESPAN="page|session|application" >



All the attributes of the USEBEAN tag are required but they need not appear in any particular order. The attributes are defined this way:

An opening <USEBEAN...> and closing </USEBEAN> tag pair may enclose nothing. Optionally, the pair may enclose one of the following:

The USEBEAN tags for any given Bean, with the exception an Implicit Bean, must appear before any property of the Bean can be accessed by any other JavaServer Pages tags.

An example of the USEBEAN tag is:

<USEBEAN NAME="clock" TYPE="calendar.JspCalendar" LIFESPAN="page">

The possible errors are:


Lifecycle of a JavaServer Pages Bean
The lifecycle of a (non-implicit) JavaServer Pages Bean is as follows:

  1. The lifecycle is triggered by the occurrence of a USEBEAN tag in the .jsp file.
  2. The named Bean is then located
  3. If the optional SETFROMREQUEST tag is present, the Bean property (or properties) named in the tag will be set to the values of the request parameters named in the tag . Otherwise, no request parameter values are set in the Bean.
  4. The Bean is introspected to determine if a processRequest method exists. If such a method does exist, it is called. The processRequest method typically performs the dynamic content generation which may then be accessed from the JavaServer Pages file. The signature of this method is:
    public void processRequest(HttpServletRequest req);
  5. The Bean is used in the JavaServer Pages file.
  6. The Bean ceases to exist when the lifespan it is registered for ends. (For instance, a Bean with a session lifespan goes away when the session is ended.)

Bean Lifecycle

Using the Bean
Typically, the purpose of a Bean is to compute some set of results. The results are then stored as properties of the Bean.

For a JavaServer Pages file to be able to access a Bean's properties, the Bean must first be registered by name for the appropriate lifespan (previous step). Then the JavaServer Pages file can display the Bean's properties using the property-display tags. The property-display tags are

Deleting the Bean
Once the lifespan (scope) becomes invalid, all JavaServer Pages objects with that lifespan become invalid as well. The invalid objects, termed garbage, are then subject to Java's normal garbage-collection mechanism which automatically detects when an object is no longer needed and deletes it.

Currently, three lifespans are possible in the JavaServer Pages Technology:

Page lifespan:
This is the lifespan that is valid for the duration of one client-request. When the request ends (typically with a response), the JavaBeans objects in the page lifespan are destroyed.
Session lifespan:
This is the lifespan that is valid for the duration of the HTTP session. When the server ends a session, the JavaBeans objects in the session lifespan are destroyed.
Application lifespan:
This is the lifespan that is valid for the duration of the application. When the server unloads the application, the JavaBeans objects in the application lifespan are destroyed.

Resolving Bean Names
You should always provide uniques names for your Beans. In some cases, Bean names must be unique (otherwise a JavaServer Pages error is generated). In other cases, Bean names are recommended to be unique (because the results of the JavaServer Pages Bean name resolution mechanism might be different than you intended). Avoid errors and unintentional behavior by choosing a unique name for each Bean.

The following chart indicates how Bean names are handled in JavaServer Pages:
  Within a page Across pages
Across lifespans Bean name must be unique.

Otherwise, an error is generated.
Bean name should be unique.

Otherwise, the Bean accessed from a given page will be the Bean explicitly registered on the current page.  References to Beans with differing lifespans from previous pages are lost.
Within the same lifespan Bean name must be unique.

Otherwise, an error is generated.
Bean name must be unique.

Otherwise, an error is generated.



The SETONCREATE tag defines a value for a property which will automatically be set once for each Bean (through JavaBeans introspection) when the Bean is created. The property value can be a string, integer, or float.

When the SETFROMREQUEST tag is present, all request parameters (query or form based) are examined. The appropriate property setter methods from the Bean's BeanInfo are called for each property depending on the attribute specified.

The syntax for the SETONCREATE tag is as follows:

<SETONCREATE BEANPROPERTY="propertyname" VALUE="propertyvalue" >

The attributes for the SETONCREATE tags are:

A SETONCREATE tag can appear only between the opening <USEBEAN ...> and closing </USEBEAN> tags. More than one SETONCREATE tag may appear in that position. SETONCREATE tags are not valid anywhere else in the file.

An example of a USEBEAN tag with enclosed SETONCREATE tag is:

<USEBEAN NAME="foobar" TYPE="FooClass" LIFESPAN="page">

Similarly, the syntax for the SETFROMREQUEST tag is as follows:


Note that this general syntax results in the following 3 cases: 


    When the wildcard character * is used, BEANPROPERTY matches any property name.  In this case, all request parameters are copied into the Bean, matching parameter names in the request to property names in the Bean -- the   PARAMNAME attribute, if present, is ignored.


    When a specific BEANPROPERTY value is provided but a PARAMNAME value is not, the PARAMNAME value is assumed to be equivalent to the BEANPROPERTY value.

    For example

    would be read as if it said:


    This is the fully qualified case.  In this form, the tag says to copy into the Bean property named  propertyname, the value of the request parameter named name.

The attributes for the SETFROMREQUEST tags are:

Like SETONCREATE, a SETFROMREQUEST tag can appear only between the opening <USEBEAN ...> and closing </USEBEAN> tags. More than one SETFROMREQUEST tag may appear in that position. SETFROMREQUEST tags are not valid anywhere else in the file.

So, what happens in the following situation:

<USEBEAN NAME="foobar" TYPE="FooClass" LIFESPAN="page">
<SETFROMREQUEST BEANPROPERTY="foobarProperty" PARAMNAME="employmentStatus">
<SETONCREATE BEANPROPERTY="foobarProperty" VALUE="Salaried">

The tagging indicates two possible values for the foobar Bean's foobarProperty -- "Salaried" and the value of the employmentStatus parameter.  It obviously cannot hold both values simultaenously so how is the conflict resolved?

As noted earlier, SETFROMREQUEST and SETONCREATE tags can only appear between the opening <USEBEAN ...> and closing </USEBEAN> tags.  Within a given USEBEAN pair of tags, all SETONCREATE tags are processed first (in their order of appearance) and then all SETFROMREQUEST tags are processed (in their order of appearance).   Therefore, in the case above, the value of the BEANPROPERTY foobarProperty would first be assigned "Salaried" and then be assigned the value associated with the request parameter employmentStatus.

Once a Bean is declared, it can be accessed later in the file. For example, using the expression syntax discussed earlier, you can access the Bean declared in the example above inside that same JavaServer Pages file as follows:

<p>The name of the row is <%= foobar.getRowName() %>. </p>

The possible errors are:


Tags for Displaying Bean Properties

Reviewer Note: For discussion

The JavaServer Pages syntax that allows for the display of Bean properties is new and tentative. For single-valued properties, the DISPLAY tag provides webpage designers a quick and easy way to access a property value for display within HTML presentation code. For multi-valued (indexed) properties, the addition of the LOOP tag enables the webpage designer, for each element in the array, to access the property value for display.

We are interested in your thoughts on the proposed syntax -- how well you think it works or how you believe it might be be improved. Your comments are welcome.

As mentioned earlier, the JavaServer Pages model enables the separation of content presentation from content generation. That separation is made possible through the use of reusable components (for content generation) and a small set of HTML-like tags designed to access the content of those components (for presentation purposes). This section of the JavaServer Pages specification discusses those tags.

There are two kinds of Bean properties you might wish to display:

And there exists a variation on each of the above:

To display a single-valued Bean property

The simplest Bean property to display is one in which there is a one-to-one mapping of property to property value -- this is called a single-valued Bean property. An example would be a Bean property called favouriteColor that can hold only a single choice. Such a single-valued property value can be accessed for presentation in a .jsp file through the use of the DISPLAY tag.

To use the Bean-property display tags for any Bean other than an implicit Bean, you must provide a USEBEAN tag for that Bean earlier in the JavaServer Pages file. Requiring the earlier USEBEAN tag helps ensure that the Bean exists (is instantiated) and is accessible (registered for the lifespan of the specified file).

The general syntax for the DISPLAY tag is:

<DISPLAY PROPERTY="[beanname:+]property"   PLACEHOLDER="substitutevalue">

The attributes for the DISPLAY tag are:

The value of the PROPERTY attribute is case-sensitive, while the value of the PLACEHOLDER attribute is not. As always, the tag and attribute names themselves are case-insensitive.

For properties that return Java native types, DISPLAY will show the property value automatically converted to String. For all other Objects, the toString method will be called.

An example of the DISPLAY tag would be:

<DISPLAY PROPERTY="preference:someProperty"
PLACEHOLDER="<H1>Not Available</H1>">

Another example would be:

<img src="<DISPLAY PROPERTY=productA:imageURL>">

The following sample file shows the required early USEBEAN tag and then the tags for displaying single-valued properties of the Bean:

<USEBEAN NAME=bar TYPE=jsp.beans.LunchSpecial LIFESPAN=page >
  <SETONCREATE BEANPROPERTY="soup" VALUE="clam chowder">
  <SETONCREATE BEANPROPERTY="dessert" VALUE="lemon meringue pie">
<h1>Welcome to Jake's Emporium!</h1>
<h2>Today's Lunch Special is:</h2>
   <li>Hot and tasty <DISPLAY PROPERTY="bar:soup" PLACEHOLDER="tomato"> soup</li>
   <li>Hearty <DISPLAY PROPERTY="bar:sandwich" PLACEHOLDER="cheese" > sandwich</li>
   <li>Homemade <DISPLAY PROPERTY="bar:dessert" PLACEHOLDER="apple" ></li>

The output from that page would look like:

Welcome to Jake's Emporium!
Today's Lunch Special is:

Note that Bean-property display tags essentially have the effect of printing the value to the page -- they have no intrinsic value. You can manipulate their presentation, but not the values themselves. For instance, if the property values had been "99", "20", and "16" respectively, you would not have been able to add or otherwise arithmetically alter them using the display tags.

The possible errors are:

To Display a Multi-valued Property

A Bean property that contains more than one value, a one-to-many relationship, is called a multi-valued or indexed property. An example would be a Bean property called favouriteFoods that contains an array of chosen items.

As mentioned in the previous section, to use the Bean-property display tags for any Bean other than an implicit Bean, you must provide a USEBEAN tag for that Bean earlier in the JavaServer Pages file.

The syntax for the simplest combination of LOOP and DISPLAY tags is shown below. Note that a LOOP tag can only contain either a DISPLAY tag or another LOOP tag (which encloses a DISPLAY tag).

<LOOP PROPERTY="beanname:indexedproperty" PROPERTYELEMENT="x" >
<DISPLAY PROPERTY= "x"  PLACEHOLDER="substitutevalue">

The attributes for the LOOP tag are:

Notes for Component Programmers

From a programmer's point of view, multiple-valued (indexed) properties can take one of the following forms: