Oracle JavaServer Pages Developer's Guide and Reference Release 8.1.7 Part Number A83726-01 |
Library | Service | Contents | Index

## Overview of JSP Syntax Elements

You have seen a simple example of JSP syntax in "What a JSP Page Looks Like"; now here is a top-level list of syntax categories and topics:

- directives, which convey information regarding the JSP page as a whole

- scripting elements, which are Java coding elements such as declarations, expressions, scriptlets, and comments

- objects and scopes, where JSP objects can be created either explicitly or implicitly and are accessible within a given scope, such as from anywhere in the JSP page or the session

- actions, which create objects or affect the output stream in the JSP response (or both)

This section introduces each category, including basic syntax and a few examples. For more information, see the Sun Microsystems JavaServer Pages Specification, Version 1.1.

Notes: There are XML-compatible alternatives to the syntax for JSP directives, declarations, expressions, and scriptlets. See "XML-Alternative Syntax".

### Directives

Directives provide instruction to the JSP container regarding the entire JSP page. This information is used in translating or executing the page. The basic syntax is as follows:

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

The JSP 1.1 specification supports the following directives:

- `page`--Use this directive to specify any of a number of page-dependent attributes, such as the scripting language to use, a class to extend, a package to import, an error page to use, or the JSP page output buffer size. For example:

      <%@ page language="java" import="packages.mypackage" errorPage="boof.jsp" %>

  Or, to set the JSP page output buffer size to 20kb (the default is 8kb):

      <%@ page buffer="20kb" %>

  Or, to unbuffer the page:

      <%@ page buffer="none" %>

  Notes: A JSP page using an error page must be buffered. Forwarding to an error page clears the buffer (not outputting it to the browser). In OracleJSP, `java` is the default language setting. It is good programming practice to set it explicitly, however.

- `include`--Use this directive to specify a resource that contains text or code to be inserted into the JSP page when it is translated. Specify the path of the resource relative to the URL specification of the JSP page.

  Example:

      <%@ include file="/jsp/userinfopage.jsp" %>

  The `include` directive can specify either a page-relative or context-relative location (see "Requesting a JSP Page" for related discussion).

  Notes: The `include` directive, referred to as a "static include", is comparable in nature to the `jsp:include` action discussed later in this chapter, but takes effect at JSP translation time instead of request time. See "Static Includes Versus Dynamic Includes". The `include` directive can be used only within the same servlet context.

- `taglib`--Use this directive to specify a library of custom JSP tags that will be used in the JSP page. Vendors can extend JSP functionality with their own sets of tags. This directive indicates the location of a tag library description file and a prefix to distinguish use of tags from that library.

  Example:

      <%@ taglib uri="/oracustomtags" prefix="oracust" %>

  Later in the page, use the `oracust` prefix whenever you want to use one of the tags in the library (presume this library includes a tag `dbaseAccess`):

      <oracust:dbaseAccess>
      ...
      </oracust:dbaseAccess>

  As you can see, this example uses XML-style start-tag and end-tag syntax.

  JSP tag libraries and tag library description files are introduced later in this chapter, in "Tag Libraries", and discussed in detail in Chapter 7, "JSP Tag Libraries and the Oracle JML Tags".

### Scripting Elements

JSP scripting elements include the following categories of snippets of Java code that can appear in a JSP page:

- declarations--These are statements declaring methods or member variables that will be used in the JSP page.

  A JSP declaration uses standard Java syntax within the `<%!...%>` declaration tags to declare a member variable or method. This will result in a corresponding declaration in the generated servlet code. For example:

      <%! double f1=0.0; %>

  This example declares a member variable, `f1`. In the servlet class code generated by the JSP translator, `f1` will be declared at the class top level.

  Note: Method variables, as opposed to member variables, are declared within JSP scriptlets as described below.

- expressions--These are Java expressions that are evaluated, converted into string values as appropriate, and displayed where they are encountered on the page.

  A JSP expression does not end in a semi-colon, and is contained within `<%=...%>` tags.

  Example:

      <P><B> Today is <%= new java.util.Date() %>. Have a nice day! </B></P>

  Note: A JSP expression in a request-time attribute, such as in a `jsp:setProperty` statement, need not be converted to a string value.

- scriptlets--These are portions of Java code intermixed within the markup language of the page.

  A scriptlet, or code fragment, may consist of anything from a partial line to multiple lines of Java code. You can use them within the HTML code of a JSP page to set up conditional branches or a loop, for example.

  A JSP scriptlet is contained within `<%...%>` scriptlet tags, using normal Java syntax.

  Example 1:

      <% if (pageBean.getNewName().equals("")) { %>
         I don't know you.
      <% } else { %>
         Hello <%= pageBean.getNewName() %>.
      <% } %>

  Three one-line JSP scriptlets are intermixed with two lines of HTML (one of which includes a JSP expression, which does not require a semi-colon). Note that JSP syntax allows HTML code to be the code that is conditionally executed within the `if` and `else` branches (inside the Java brackets set out in the scriptlets).

  The preceding example assumes the use of a JavaBean instance, `pageBean`.

  Example 2:

      <% if (pageBean.getNewName().equals("")) { %>
         I don't know you.
         <% empmgr.unknownemployee();
      } else { %>
         Hello <%= pageBean.getNewName() %>.
         <% empmgr.knownemployee();
      } %>

  This example adds more Java code to the scriptlets, assuming the use of a JavaBean instance, `pageBean`, and assuming that some object, `empgr`, was previously instantiated and has methods to execute appropriate functionality for a known employee or an unknown employee.

  Note: Use a JSP scriptlet to declare method variables, as opposed to member variables, as in the following example:
      <% double f2=0.0; %>
  This scriptlet declares a method variable, `f2`. In the servlet class code generated by the JSP translator, `f2` will be declared as a variable within the service method of the servlet. Member variables are declared in JSP declarations as described above. For a comparative discussion, see "Method Variable Declarations Versus Member Variable Declarations".

- comments--These are developer comments embedded within the JSP code, similar to comments embedded within any Java code.

  Comments are contained within `<%--...--%>` tags. Unlike HTML comments, these comments are not visible when a user views the page source.

  Example:

      <%-- Execute the following branch if no user name is entered. --%>

### JSP Objects and Scopes

In this document, the term JSP object refers to a Java class instance declared within or accessible to a JSP page. JSP objects can be either:

- explicit--Explicit objects are declared and created within the code of your JSP page, accessible to that page and other pages according to the `scope` setting you choose.

or:

- implicit--Implicit objects are created by the underlying JSP mechanism and accessible to Java scriptlets or expressions in JSP pages according to the inherent `scope` setting of the particular object type.

Scopes are discussed below, in "Object Scopes".

#### Explicit Objects

Explicit objects are typically JavaBean instances declared and created in `jsp:useBean` action statements. The `jsp:useBean` statement and other action statements are described in "JSP Actions and the <jsp: > Tag Set", but an example is also shown here:

    <jsp:useBean id="pageBean" class="mybeans.NameBean" scope="page" />

This statement defines an instance, `pageBean`, of the `NameBean` class that is in the `mybeans` package. The scope parameter is discussed in the next section, "Object Scopes".

You can also create objects within Java scriptlets or declarations, just as you would create Java class instances in any Java program.

#### Object Scopes

Objects in a JSP, whether explicit or implicit, are accessible within a particular scope. In the case of explicit objects, such as a JavaBean instance created in a `jsp:useBean` action statement, you can explicitly set the scope with the following syntax (as in the example in the preceding section, "Explicit Objects"):

    scope="scopevalue"

There are four possible scopes:

- `scope="page"`--The object is accessible only from within the JSP page where it was created.

  Note that when the user refreshes the page while executing a JSP page, new instances will be created of all page-scope objects.

- `scope="request"`--The object is accessible from any JSP page servicing the same HTTP request that is serviced by the JSP page that created the object.

- `scope="session"`--The object is accessible from any JSP page sharing the same HTTP session as the JSP page that created the object.

- `scope="application"`--The object is accessible from any JSP page used in the same Web application (within any single Java virtual machine) as the JSP page that created the object.

#### Implicit Objects

JSP technology makes available to any JSP page a set of implicit objects. These are Java class instances that are created automatically by the JSP mechanism and that allow interaction with the underlying servlet environment.

The following implicit objects are available. For information about methods available with these objects, refer to the Sun Microsystems Javadoc for the noted classes and interfaces at the following location:

    http://java.sun.com/products/servlet/2.2/javadoc/index.html

- `page`

  This is an instance of the JSP page implementation class that was created when the page was translated; `page` is synonymous with `this` within a JSP page.

- `request`

  This represents an HTTP request and is an instance of a class that implements the `javax.servlet.http.HttpServletRequest` interface, which extends the `javax.servlet.ServletRequest` interface.

- `response`

  This represents an HTTP response and is an instance of a class that implements the `javax.servlet.http.HttpServletResponse` interface, which extends the `javax.servlet.ServletResponse` interface.

  The `response` and `request` objects for a particular request are associated with each other.

- `pageContext`

  This represents the page context of a JSP page, which is provided for storage and access of all `page` scope objects of a JSP page instance. A `pageContext` object is an instance of the `javax.servlet.jsp.PageContext` class.

  The `pageContext` object has `page` scope, making it accessible only to the JSP page instance with which it is associated.

- `session`

  This represents an HTTP session and is an instance of the `javax.servlet.http.HttpSession` class.

- `application`

  This represents the servlet context for the Web application and is an instance of the `javax.servlet.ServletContext` class.

  The `application` object is accessible from any JSP page instance running as part of any instance of the application within a single JVM. (The programmer should be aware of the server architecture regarding use of JVMs. For example, in the Oracle Servlet Engine architecture, each user runs in his or her own JVM.)

- `out`

  This is an object that is used to write content to the output stream of a JSP page instance. It is an instance of the `javax.servlet.jsp.JspWriter` class, which extends the `java.io.Writer` class.

  The `out` object is associated with the `response` object for a particular request.

- `config`

  This represents the servlet configuration for a JSP page and is an instance of a class that implements the `javax.servlet.ServletConfig` interface. (Generally speaking, servlet containers use `ServletConfig` instances to provide information to servlets during initialization. Part of this information is the appropriate `ServletContext` instance.)

- `exception` (JSP error pages only)

  This implicit object applies only to JSP error pages--these are pages to which processing is forwarded when an exception is thrown from another JSP page; they must have the `page` directive `isErrorPage` attribute set to `true`.

  The implicit `exception` object is a `java.lang.Exception` instance that represents the uncaught exception that was thrown from another JSP page and that resulted in this error page being invoked.

  The `exception` object is accessible only from the JSP error page instance to which processing was forwarded when the exception was encountered.

  For an example of JSP error processing and use of the `exception` object, see "JSP Runtime Error Processing".

#### Using an Implicit Object

Any of the implicit objects discussed in the preceding section may be useful. The following example uses the `request` object to retrieve and display the value of the `username` parameter from the HTTP request:

    <H3> Welcome <%= request.getParameter("username") %> ! <H3>

### JSP Actions and the <jsp: > Tag Set

JSP action elements result in some sort of action occurring while the JSP page is being executed, such as instantiating a Java object and making it available to the page. Such actions may include the following:

- creating a JavaBean instance and accessing its properties

- forwarding execution to another HTML page, JSP page, or servlet

- including an external resource in the JSP page

Action elements use a set of standard JSP tags that begin with `<jsp:` syntax. Although the tags described earlier in this chapter that begin with `<%` syntax are sufficient to code a JSP page, the `<jsp:` tags provide additional functionality and convenience.

Action elements also use syntax similar to that of XML statements, with similar "begin" and "end" tags such as in the following example:

    <jsp:sampletag attr1="value1" attr2="value2" ... attrN="valueN">
    ...body...
    </jsp:sampletag>

Or, where there is no body, the action statement is terminated with an empty tag:

    <jsp:sampletag attr1="value1", ..., attrN="valueN" />

The JSP specification includes the following standard action tags, which are introduced and briefly discussed here:

- `jsp:useBean`

  The `jsp:useBean` action creates an instance of a specified JavaBean class, gives the instance a specified name, and defines the scope within which it is accessible (such as from anywhere within the current JSP page instance).

  Example:

      <jsp:useBean id="pageBean" class="mybeans.NameBean" scope="page" />

  This example creates a page-scoped instance `pageBean` of the `mybeans.NameBean` class. This instance is accessible only from the JSP page instance that creates it.

- `jsp:setProperty`

  The `jsp:setProperty` action sets one or more bean properties. (The bean must have been previously specified in a `useBean` action.) You can directly specify a value for a specified property, or take the value for a specified property from an associated HTTP request parameter, or iterate through a series of properties and values from the HTTP request parameters.

  The following example sets the `user` property of the `pageBean` instance (defined in the preceding `useBean` example) to a value of "Smith":

      <jsp:setProperty name="pageBean" property="user" value="Smith" />

  The following example sets the `user` property of the `pageBean` instance according to the value set for a parameter called `username` in the HTTP request:

      <jsp:setProperty name="pageBean" property="user" param="username" />

  Or, if the bean property and request parameter have the same name (`user`), you can simply set the property as follows:

      <jsp:setProperty name="pageBean" property="user" />

  The following example results in iteration over the HTTP request parameters, matching bean property names with request parameter names and setting bean property values according to the corresponding request parameter values:

      <jsp:setProperty name="pageBean" property="*" />

- `jsp:getProperty`

  The `jsp:getProperty` action reads a bean property value, converts it to a Java string, and places the string value into the implicit `out` object so that it can be displayed as output. (The bean must have been previously specified in a `jsp:useBean` action.) For the string conversion, primitive types are converted directly and object types are converted using the `toString()` method specified in the `java.lang.Object` class.

  The following example puts the value of the `user` property of the `pageBean` bean into the `out` object:

      <jsp:getProperty name="pageBean" property="user" />

- `jsp:param`

  You can use the `jsp:param` action in conjunction with `jsp:include`, `jsp:forward`, or `jsp:plugin` actions (described below).

  For `jsp:forward` and `jsp:include` statements, a `jsp:param` action optionally provides key/value pairs for parameter values in the HTTP request object. New parameters and values specified with this action are added to the request object, with new values taking precedence over old.

  The following example sets the request object parameter `username` to a value of `Smith`:

      <jsp:param name="username" value="Smith" />

  Note: The `jsp:param` tag is not supported for `jsp:include` or `jsp:forward` in the JSP 1.0 specification.

- `jsp:include`

  The `jsp:include` action inserts additional static or dynamic resources into the page at request time as the page is displayed. Specify the resource with a relative URL (either page-relative or application-relative).

  As of the Sun Microsystems JavaServer Pages Specification, Version 1.1, you must set `flush` to `true`, which results in the buffer being flushed to the browser when a `jsp:include` action is executed. (The `flush` attribute is mandatory, but a setting of `false` is currently invalid.)

  You can also have an action body with `jsp:param` settings, as shown in the second example.

  Examples:

      <jsp:include page="/templates/userinfopage.jsp" flush="true" />

  or:

      <jsp:include page="/templates/userinfopage.jsp" flush="true" >
         <jsp:param name="username" value="Smith" />
         <jsp:param name="userempno" value="9876" />
      </jsp:include>

  Note that the following syntax would work as an alternative to the preceding example:

      <jsp:include page="/templates/userinfopage.jsp?username=Smith&userempno=9876" flush="true" />

  Notes: The `jsp:include` action, known as a "dynamic include", is similar in nature to the `include` directive discussed earlier in this chapter, but takes effect at request time instead of translation time. See "Static Includes Versus Dynamic Includes". The `jsp:include` action can be used only within the same servlet context.

- `jsp:forward`

  The `jsp:forward` action effectively terminates execution of the current page, discards its output, and dispatches a new page--either an HTML page, a JSP page, or a servlet.

  The JSP page must be buffered (you cannot set `buffer="none"`) to use a `jsp:forward` action. The action will clear the buffer (not outputting contents to the browser).

  As with `jsp:include`, you can also have an action body with `jsp:param` settings, as shown in the second example.

  Examples:

      <jsp:forward page="/templates/userinfopage.jsp" />

  or:

      <jsp:forward page="/templates/userinfopage.jsp" >
         <jsp:param name="username" value="Smith" />
         <jsp:param name="userempno" value="9876" />
      </jsp:forward>

  Notes: The difference between the `jsp:forward` examples here and the `jsp:include` examples earlier is that the `jsp:include` examples insert `userinfopage.jsp` within the output of the current page; the `jsp:forward` examples stop executing the current page and display `userinfopage.jsp` instead. The `jsp:forward` action can be used only within the same servlet context.

- `jsp:plugin`

  The `jsp:plugin` action results in the execution of a specified applet or JavaBean in the client browser, preceded by a download of Java plugin software if necessary.

  Specify configuration information, such as the applet to run and the codebase, using `jsp:plugin` attributes. The JSP container might provide a default URL for the download, but you can also specify attribute `nspluginurl="``url``"` (for a Netscape browser) or `iepluginurl="``url``"` (for an Internet Explorer browser).

  Use nested `jsp:param` actions within `<jsp:params>` and `</jsp:params>` start and end tags to specify parameters to the applet or JavaBean. (Note that these `jsp:params` start and end tags are not necessary when using `jsp:param` in a `jsp:include` or `jsp:forward` action.)

  Use `<jsp:fallback>` and `</jsp:fallback>` start and end tags to delimit alternative text to execute if the plugin cannot run.

  The following example, from the Sun Microsystems JavaServer Pages Specification, Version 1.1, shows use of an applet plugin:

      <jsp:plugin type=applet code="Molecule.class" codebase="/html" >
         <jsp:params>
            <jsp:param name="molecule" value="molecules/benzene.mol" />
         </jsp:params>
         <jsp:fallback>
            <p> Unable to start the plugin. </p>
         </jsp:fallback>
      </jsp:plugin>

  Many additional parameters--such as `ARCHIVE`, `HEIGHT`, `NAME`, `TITLE`, and `WIDTH`--are allowed in the `jsp:plugin` action statement as well. Use of these parameters is according to the general HTML specification.

### Tag Libraries

In addition to the standard JSP tags discussed previously in this section, the JSP specification lets vendors define their own tag libraries and also lets vendors implement a framework allowing customers to define their own tag libraries.

A tag library defines a collection of custom tags and can be thought of as a JSP sub-language. Developers can use tag libraries directly, in manually coding a JSP page, but they might also be used automatically by Java development tools. A tag library must be portable between different JSP container implementations.

Import a tag library into a JSP page using the `taglib` directive, introduced in "Directives".

Key concepts of standard JavaServer Pages support for JSP tag libraries include the following topics:

- tag handlers

  A tag handler describes the semantics of the action that results from use of a custom tag. A tag handler is an instance of a Java class that implements either the `Tag` or `BodyTag` interface (depending on whether the tag uses a body between a start tag and an end tag) in the standard `javax.servlet.jsp.tagext` package.

- scripting variables

  Custom tag actions can create server-side objects available for use by the tag itself or by other scripting elements such as scriptlets. This is accomplished by creating or updating scripting variables.

  Details regarding scripting variables that a custom tag defines must be specified in a subclass of the standard `javax.servlet.jsp.tagext.TagExtraInfo` abstract class. This document refers to such a subclass as a tag-extra-info class. The JSP container uses instances of these classes during translation.

- tag library description files

  A tag library description (TLD) file is an XML document that contains information about a tag library and about individual tags of the library. The file name of a TLD has the `.tld` extension.

  A JSP container uses the TLD file in determining what action to take when it encounters a tag from the library.

- use of `web.xml` for tag libraries

  The Sun Microsystems Java Servlet Specification, Version 2.2 describes a standard deployment descriptor for servlets--the `web.xml` file. JSP applications can use this file in specifying the location of a JSP tag library description file.

  For JSP tag libraries, the `web.xml` file can include a `taglib` element and two subelements: `taglib-uri` and `taglib-location`.

For information about these topics, see "Standard Tag Library Framework".

For information about the sample tag library provided with OracleJSP, see "Overview of the JSP Markup Language (JML) Sample Tag Library"

For further information, see the Sun Microsystems JavaServer Pages Specification, Version 1.1.

| Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index