1 Getting Started with JSP

1.2.1.1 page directive

Use this directive to specify any of a number of page-dependent attributes, such as scripting language, content type, character encoding, class to extend, packages to import, an error page to use, the JSP page output buffer size, and whether to automatically flush the buffer when it is full. For example:

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

Alternatively, to enable auto-flush and set the JSP page output buffer size to 20 KB:

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

This example un-buffers the page:

<%@ page buffer="none" %>

1.2.1.2 include directive

Use this directive to specify a resource that contains text or code to be inserted into the JSP page when it is translated. For example:

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

Specify either a page-relative or context-relative path to the resource. See "Requesting a JSP Page" for discussion of page-relative and context-relative paths.

1.2.1.3 taglib directive

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 includes a pointer to a tag library descriptor file and a prefix to distinguish use of tags from that library. For 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>

JSP tag libraries and tag library descriptor files are introduced later in this chapter, in "Custom Tag Libraries", and discussed in detail in Chapter 7, "Working with Custom Tags".

1.2.2.1 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 f=0.0; %>

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

1.2.2.2 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 semicolon, and is contained within <%=...%> tags. For example:

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

1.2.2.3 Scriptlets

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

A scriptlet, or code fragment, can 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.

The following example assumes the use of a JavaBean instance, pageBean:

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

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

This next example adds more Java code to the scriptlets.:

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

It assumes the use of a JavaBean instance, pageBean, and assumes that some object, empmgr, was previously instantiated and has methods to execute appropriate functionality for a known employee or an unknown employee.

<% double f2=0.0; %>

1.2.2.4 Comments

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

Comments are contained within <%--...--%> syntax. For example:

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

Unlike HTML comments, JSP comments are not visible when users view the page source from their browsers.

1.2.3.1 Explicit Objects

Explicit objects are typically JavaBean instances that are declared and created in jsp:useBean action statements. The jsp:useBean statement and other action statements are described in "Standard JSP Action Tags", but here is an example:

<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 "Object Scopes".

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

1.2.3.2 Implicit Objects

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

The implicit objects listed immediately below are available. For information about methods available with these objects, refer to the Sun Microsystems Javadoc for the noted classes and interfaces.

• page

  This is an instance of the JSP page implementation class and is created when the page is translated. The page implementation class implements the interface javax.servlet.jsp.HttpJspPage. Note that 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, which extends javax.servlet.jsp.JspContext as of JSP 2.0.

  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 a class that implements the javax.servlet.http.HttpSession interface.

• application

  This represents the servlet context for the Web application and is an instance of a class that implements the javax.servlet.ServletContext interface.

  The application object is accessible from any JSP page instance running as part of any instance of the application within a single 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, to which processing is forwarded when an exception is thrown from another JSP page. These error pages must have the page directive isErrorPage attribute set to true.

  The implicit exception object is a java.lang.Throwable instance that represents the uncaught exception that was thrown from another JSP page and that resulted in the current 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 "Processing Runtime Errors".

1.2.3.3 Using an Implicit Object

Any of the implicit objects discussed in the preceding section might 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>

The request object, like the other implicit objects, is available automatically; it is not explicitly instantiated.

1.2.3.4 Object Scopes

Objects in a JSP page, 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, you can explicitly set the scope with the following syntax, as in the example in "Explicit Objects":

scope="scopeValue"

There are four possible scopes:

• scope="page" (default scope): The object is accessible only from within the JSP page where it was created. A page-scope object is stored in the implicit pageContext object. The page scope ends when the page stops executing.

  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. A request-scope object is stored in the implicit request object. The request scope ends at the conclusion of the HTTP request.

• scope="session": The object is accessible from any JSP page that is sharing the same HTTP session as the JSP page that created the object. A session-scope object is stored in the implicit session object. The session scope ends when the HTTP session times out or is invalidated.

• scope="application": The object is accessible from any JSP page that is used in the same Web application as the JSP page that created the object, within any single Java virtual machine. The concept is similar to that of a Java static variable. An application-scope object is stored in the implicit application servlet context object. The application scope ends when the application itself terminates, or when the Web container or servlet container shuts down.

You can think of these four scopes as being in the following progression, from narrowest scope to broadest scope:

page < request < session < application

If you want to share an object between different pages in an application, such as when forwarding execution from one page to another, or including content from one page in another, you cannot use page scope for the shared object; in this case, there would be a separate object instance associated with each page. The narrowest scope you can use to share an object between pages is request. (For information about including and forwarding pages, see "Standard JSP Action Tags" below.)

1.2.4.1 jsp:useBean tag

The jsp:useBean tag accesses or creates an instance of a Java type, typically a JavaBean class, and associates the instance with a specified name, or ID. The instance is then available by that ID as a scripting variable of specified scope. Scripting variables are introduced in "Custom Tag Libraries". Scopes are discussed in "JSP Objects and Scopes".

The key attributes are class, type, id, and scope. (There is also a less frequently used beanName attribute, discussed below.)

Use the id attribute to specify the instance name. The Web container will first search for an object by the specified ID, of the specified type, in the specified scope. If it does not exist, the container will attempt to create it.

Use the class attribute to specify a class that can be instantiated, if necessary, by the Web container. The class cannot be abstract and must have a no-argument constructor.

As an alternative to using the class attribute, you can use the beanName attribute. In this case, you have the option of specifying a serializable resource instead of a class name. When you use the beanName attribute, the Web container creates the instance by using the instantiate() method of the java.beans.Beans class.

Use the type attribute to specify a type that cannot be instantiated by the Web container—either an interface, an abstract class, or a class without a no-argument constructor. You would use type in a situation where the instance will already exist, or where an instance of an instantiable class will be assigned to the type. There are three typical scenarios:

• Use type and id to specify an instance that already exists in the target scope.

• Use class and id to specify the name of an instance of the class—either an instance that already exists in the target scope or an instance to be newly created by the Web container.

• Use class, type, and id to specify a class to instantiate and a type to assign the instance to. In this case, the class must be legally assignable to the type.

Use the scope attribute to specify the scope of the instance—either page for the instance to be associated with the page context object, request for it to be associated with the HTTP request object, session for it to be associated with the HTTP session object, or application for it to be associated with the servlet context.

The following example uses a request-scope instance reqobj of type MyIntfc. Because MyIntfc is an interface and cannot be instantiated directly, reqobj would have to already exist.

<jsp:useBean id="reqobj" type="mypkg.MyIntfc" scope="request" />

This next example uses a page-scope instance pageobj of class PageBean, first creating it if necessary:

<jsp:useBean id="pageobj" class="mybeans.PageBean" scope="page" />

The following example creates an instance of class SessionBean and assigns the instance to the variable sessobj of type MyIntfc:

<jsp:useBean id="sessobj" class="mybeans.SessionBean" 
             type="mypkg.MyIntfc scope="session" />

1.2.4.2 jsp:setProperty tag

The jsp:setProperty tag sets one or more bean properties. The bean must have been previously specified in a jsp:useBean tag. 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 according to the value set for a parameter called username in the HTTP request:

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

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="*" />

When you use the jsp:setProperty tag, string input can be used to specify the value of a non-string property through conversions that happen behind the scenes. See "Bean Property Conversions from String Values" for additional information.

1.2.4.3 jsp:getProperty tag

The jsp:getProperty tag 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 tag. 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" />

1.2.4.4 jsp:param tag

You can use jsp:params tags in conjunction with jsp:include, jsp:forward, and jsp:plugin tags (described below).

Used with jsp:forward and jsp:include tags, a jsp:param tag optionally provides name/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" />

1.2.4.5 jsp:include tag

The jsp:include tag 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). For example:

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

A "true" setting of the flush attribute results in the buffer being flushed to the browser when a jsp:include action is executed. The JSP specification and the OC4J Web container support either a "true" or "false" setting, with "false" being the default.

You can also have an action body with jsp:param tags, as shown in the following example:

<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" />

1.2.4.6 jsp:forward tag

The jsp:forward tag 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 to use a jsp:forward tag; you cannot set buffer="none" in a page directive. The action will clear the buffer and not output contents to the browser.

As with jsp:include, you can also have an action body with jsp:param tags, as shown in the second of the following 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>

1.2.4.7 jsp:plugin tag

The jsp:plugin tag 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 code base, using jsp:plugin attributes. You can specify attribute nspluginurl="url" (for a Netscape browser) or iepluginurl="url" (for an Internet Explorer browser).

Use nested jsp:param tags between the jsp:params start-tag and end-tag to specify parameters to the applet or JavaBean. (Note that the jsp:params start-tag and end-tag are not included when using jsp:param in a jsp:include or jsp:forward action.)

Note the use of the jsp:fallback tag to delimit alternative text to execute if the plugin cannot run.

The following example shows the use of an applet plugin:

<jsp:plugin type=applet code="Sample.class" codebase="/html" >
   <jsp:params>
      <jsp:param name="sample" value="samples/sample01" />
   </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 tag as well. Use of these parameters is according to the general HTML specification.

1.2.5.1 Typical Property Conversions

For a bean property that does not have an associated property editor, Table 1-1 shows how conversion is accomplished when using a string value to set the property.

1.2.5.2 Conversions for Property Types with Property Editors

A bean property can have an associated property editor, which is a class that implements the java.beans.PropertyEditor interface. Such classes can provide support for GUIs used in editing properties. Generally speaking, there are standard property editors for standard Java types, and there can be user-defined property editors for user-defined types. In the OC4J JSP implementation, however, only user-defined property editors are searched for. Default property editors of the sun.beans.editors package are not taken into account.

For information about property editors and how to associate a property editor with a type, you can refer to the Sun Microsystems JavaBeans API Specification.

You can still use a string value to set a property that has an associated property editor, as specified in the JavaBeans specification. In this situation, the setAsText(String text) method specified in the PropertyEditor interface is used in converting from string input to a value of the appropriate type. If the setAsText() method throws an IllegalArgumentException, the conversion will fail.

1.3.1.1 JSP Expression Language Syntax

The expression language has its own syntax, partially based on JavaScript syntax. The following list offers a brief summary of key syntax features of the JSP expression language. This is followed by a few simple examples.

• Invocation

  The expression language is invoked through ${expression} syntax. The most basic semantic is that invocation of a named variable ${foo} yields the same result as the method call PageContext.findAttribute(foo).

• Data structure access

  To access named properties within JavaBeans and within collections such as lists, maps, and arrays, the expression language supports the "." and "[]" operators.

  The "." construct allows access to properties whose names are standard Java identifiers. For example, employee.phones.cell is equivalent to employee.getPhones().getCell() in Java syntax.

  The "[]" construct is for more generalized access, such as for accessing arrays or lists. However, for valid Java identifiers it is equivalent to the "." construct. For example, the expressions employee.phoneNumbers and employee["phoneNumbers"] yield the same result.

• Relational operators

  The expression language supports the relational operators == (or eq), != (or ne), < (or lt), > (or gt), <= (or le), >= (or ge).

• Arithmetic operators

  The expression language supports the arithmetic operators +, -, *, / (or div), % (or mod, for remainder or modulo).

• Logical operators

  The expression language supports the logical operators && (or and), || (or or), ! (or not), empty.

Basic Example

The following example shows a basic invocation of the expression language, including the relational "<=" (less than or equal to) operator.

<c:if test="${auto.price <= customer.priceLimit}">
   The <c:out value="${auto.makemodel}"/> is in your price range.
</c:if>

Accessing Collections Example

The following example shows use of the "." and "[]" constructs. Here, catalogue is a Map object containing the description of products, while preferences is a Map object containing a particular user's preferences.

Item:
<c:out value="${catalogue[productId]}"/>
   Delivery preference:
<c:out value="${user.preferences['delivery']}"/>

1.3.1.2 Expression Language Implicit Objects

The expression language provides the following implicit objects:

• pageScope: Allows access to page-scope variables.

• requestScope: Allows access to request-scope variables.

• sessionScope: Allows access to session-scope variables.

• applicationScope: Allows access to application-scope variables.

• pageContext: Allows access to all properties of the page context of a JSP page.

• param: A Java Map object containing request parameters typically accessed using the request.getParameter() method. The expression ${param["foo"]} or the equivalent ${param.foo} both return the first string value associated with the request parameter foo.

• paramValues: Use paramValues["foo"], for example, to return an array of all string values associated with request parameter foo.

• header: As with param, you can use this object to access the first string value associated with a request header.

• headerValues: Similarly to using paramValues, you can use this to access all string values associated with a request header.

• initParam: Allows access to context initialization parameters.

• cookie: Allows access to cookies received in the request.

1.3.1.3 Additional Features of the Expression Language

The expression language also offers the following features:

• It can provide default values where failure to evaluate an expression is considered to be recoverable.

• Where application data might not exactly match the type expected by a tag attribute or expression language operator, there are rules to convert the type of the resulting value to the expected type.

1.3.3.1 Disabling EL in All JSPs in a Web Application

To disable EL for all JSPs in an application, add the following <jsp-property-group> to the application's web.xml Web application descriptor file.

<jsp-property-group>
  <url-patter>*.jsp</url-pattern>
  <el-ignored>true</el-ignored>
</jsp-property-group>

1.3.3.2 Disabling EL in a JSP

To disable EL evaluation in a JSP page, set the isELIgnored attribute of the page directive to true in the JSP.

1.3.3.3 Disabling EL in a Tag File

To disable EL evaluation in a tag file, set the isELIgnored attribute of the tag directive to true in the tag file.

1.4.1.1 On-Demand Translation Model

It is typical to run JSP pages in an on-demand translation scenario. When a JSP page is requested from a Web server that incorporates the Web container, a front-end servlet is instantiated and invoked, assuming proper Web server configuration. This servlet can be thought of as the front-end of the Web container. In OC4J, it is oracle.jsp.runtimev2.JspServlet.

JspServlet locates the JSP page, translates and compiles it if necessary (if the translated class does not exist or has an earlier timestamp than the JSP page source), and triggers its execution.

Note that the Web server must be properly configured to map the *.jsp file name extension (in a URL) to JspServlet.

1.4.1.2 Pretranslation Model

As an alternative to the typical on-demand scenario, developers might want to pretranslate their JSP pages before deploying them. This can offer the following advantages, for example:

• It can save time for the users when they first request a JSP page, because translation at execution time is not necessary.

• It is useful if you want to deploy binary files only, perhaps because the software is proprietary or you have security concerns and you do not want to expose the code.

Oracle supplies the ojspc command-line utility for pretranslating JSP pages. This utility has options that allow you to set an appropriate base directory for the output files, depending on how you want to deploy the application. The ojspc utility is documented in Chapter 4, "Precompiling JSPs with ojspc".

1.4.3.1 Directly Requesting a JSP Page

As with a servlet or HTML page, the user can request a JSP page directly by URL. For example, suppose you have a HelloWorld JSP page that is located under a myapp directory, as follows, where myapp is mapped to the myapproot context path in the Web server:

myapp/dir/HelloWorld.jsp

You can request it with a URL such as the following:

http://host:port/myapproot/dir/HelloWorld.jsp

The first time the user requests HelloWorld.jsp, the Web container triggers both translation and execution of the page. With subsequent requests, the Web container triggers page execution only; the translation step is no longer necessary.

1.4.3.2 Indirectly Requesting a JSP Page

JSP pages, like servlets, can also be executed indirectly—linked from a regular HTML page or referenced from another JSP page or from a servlet.

When invoking one JSP page from a JSP statement in another JSP page, the path can be either relative to the application root—known as context-relative or application-relative—or relative to the invoking page—known as page-relative. An application-relative path starts with "/"; a page-relative path does not.

Be aware that, typically, neither of these paths is the same path as used in a URL or HTML link. Continuing the example in the preceding section, the path in an HTML link is the same as in the direct URL request, as follows:

<a href="/myapp/dir/HelloWorld.jsp" /a>

The application-relative path in a JSP statement is:

<jsp:include page="/dir/HelloWorld.jsp" flush="true" />

The page-relative path to invoke HelloWorld.jsp from a JSP page in the same directory is:

<jsp:forward page="HelloWorld.jsp" />

("Standard JSP Action Tags" discusses the jsp:include and jsp:forward statements.)