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.

---