1 General JSP Overview

This chapter reviews standard features and functionality of JavaServer Pages technology, then concludes with a discussion of JSP execution models. For further general information, consult the Sun Microsystems JavaServer Pages Specification.

JSP functionality depends upon servlet functionality. You can also refer to the Sun Microsystems Java Servlet Specification for information.

For an overview of the JSP implementation in Oracle Application Server Containers for J2EE (OC4J), see Chapter 2, "Overview of the Oracle JSP Implementation". Also note that Appendix A, "Servlet and JSP Technical Background", provides related background on standard servlet and JSP technology.

The chapter contains the following sections:

Introduction to JavaServer Pages
Overview of JSP Syntax Elements

JSP Execution

Note:

The Sample Appl ications chapter available in previous releases has been removed. Applications that were listed there are available in the OC4J demos, available from the following location on the Oracle Technology Network (requiring an OTN membership, which is free of charge):

http://www.oracle.com/technology/tech/java/oc4j/demos/

Introduction to JavaServer Pages

JavaServer Pages is a technology specified by Sun Microsystems as a convenient way of generating dynamic content in pages that are output by a Web application (an application running on a Web server).

This technology, which is closely coupled with Java servlet technology, enables you to include Java code snippets and calls to external Java components within the HTML code (or other markup code, such as XML) of your Web pages. JavaServer Pages (JSP) technology works nicely as a front-end for business logic and dynamic functionality in JavaBeans and Enterprise JavaBeans (EJBs).

JSP code is distinct from other Web scripting code, such as JavaScript, in a Web page. Anything that you can include in a normal HTML page can be included in a JSP page as well.

In a typical scenario for a database application, a JSP page will call a component such as a JavaBean or Enterprise JavaBean, and the bean will directly or indirectly access the database, generally through JDBC.

A JSP page is translated into a Java servlet before being executed, and processes HTTP requests and generates responses similarly to any other servlet. JSP technology offers a more convenient way to code the servlet. The translation typically occurs on demand, but sometimes in advance.

Furthermore, JSP pages are fully interoperable with servlets—JSP pages can include output from a servlet or forward to a servlet, and servlets can include output from a JSP page or forward to a JSP page.

What a JSP Page Looks Like

Here is an example of a simple JSP page. For an explanation of JSP syntax elements used here, see "Overview of JSP Syntax Elements".

<HTML>
<HEAD><TITLE>The Welcome User JSP</TITLE></HEAD>
<BODY>
<% String user=request.getParameter("user"); %>
<H3>Welcome <%= (user==null) ? "" : user %>!</H3>
<P><B> Today is <%= new java.util.Date() %>. Have a nice day! :-)</B></P>
<B>Enter name:</B>
<FORM METHOD=get>
<INPUT TYPE="text" NAME="user" SIZE=15>
<INPUT TYPE="submit" VALUE="Submit name">
</FORM>
</BODY>
</HTML>

In a traditional JSP page, Java elements are set off by tags such as <% and %>, as in the preceding example. (JSP XML syntax is different, as described in "Details of JSP XML Documents".) In this example, Java snippets get the user name from an HTTP request object, print the user name, and get the current date.

This JSP page will produce output as shown in Figure 1-1 if the user inputs the name "Amy".

Figure 1-1 Sample Welcome Page

Description of "Figure 1-1 Sample Welcome Page"

Convenience of JSP Coding Versus Servlet Coding

Combining Java code and Java calls into an HTML page is more convenient than using straight Java code in a servlet. JSP syntax gives you a shortcut for coding dynamic Web pages, typically requiring much less code than Java servlet syntax. Following is an example contrasting servlet code and JSP code.

Servlet Code

import javax.servlet.*;
import javax.servlet.http.*;
import java.io.*;

public class Hello extends HttpServlet
{
   public void doGet(HttpServletRequest rq, HttpServletResponse rsp)
   {
      rsp.setContentType("text/html");
      try {
         PrintWriter out = rsp.getWriter();
         out.println("<HTML>");
         out.println("<HEAD><TITLE>Welcome</TITLE></HEAD>");
         out.println("<BODY>");
         out.println("<H3>Welcome!</H3>");
         out.println("<P>Today is "+new java.util.Date()+".</P>");
         out.println("</BODY>");
         out.println("</HTML>");
      } catch (IOException ioe)
      {
        // (error processing) 
      }
   }
}

See "The Servlet Interface" for some background information about the standard HttpServlet abstract class, HttpServletRequest interface, and HttpServletResponse interface.

JSP Code

<HTML>
<HEAD><TITLE>Welcome</TITLE></HEAD>
<BODY>
<H3>Welcome!</H3>
<P>Today is <%= new java.util.Date() %>.</P>
</BODY>
</HTML>

Note how much simpler JSP syntax is. Among other things, it saves Java overhead such as package imports and try...catch blocks.

Note:

The list of packages imported into a JSP page by default changed in the OC4J 9.0.3 implementation. The default list was reduced to follow the JSP specification. See "Default Package Imports" for more information. Therefore, beginning with Oracle9iAS Release 2 (9.0.3), the preceding JSP example requires a configuration setting to import the java.io package.

Additionally, the JSP translator automatically handles a significant amount of servlet coding overhead for you in the .java file that it outputs, such as directly or indirectly implementing the standard javax.servlet.jsp.HttpJspPage interface (covered in "Standard JSP Interfaces and Methods") and adding code to acquire an HTTP session.

Also note that because the HTML of a JSP page is not embedded within Java print statements, as it is in servlet code, you can use HTML authoring tools to create JSP pages.

Separation of Business Logic from Page Presentation: Calling JavaBeans

JSP technology allows separating the development efforts between the HTML code that determines static page presentation, and the Java code that processes business logic and presents dynamic content. It therefore becomes much easier to split maintenance responsibilities between presentation and layout specialists who might be proficient in HTML but not Java, and code specialists who may be proficient in Java but not HTML.

In a typical JSP page, most Java code and business logic will not be within snippets embedded in the JSP page. Instead, it will be in JavaBeans or Enterprise JavaBeans that are invoked from the JSP page.

JSP technology offers the following syntax for defining and creating an instance of a JavaBeans class:

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

This example creates an instance, pageBean, of the mybeans.NameBean class. The scope parameter will be explained later in this chapter.

Later in the page, you can use this bean instance, as in the following example:

Hello <%= pageBean.getNewName() %> !

This prints "Hello Julie !", for example, if the name "Julie" is in the newName attribute of pageBean, which might occur through user input.

The separation of business logic from page presentation allows convenient division of responsibilities between the Java expert who is responsible for the business logic and dynamic content (the person who owns and maintains the code for the NameBean class) and the HTML expert who is responsible for the static presentation and layout of the Web page that the application users see (the person who owns and maintains the code in the .jsp file for this JSP page).

Tags used with JavaBeans—useBean to declare the JavaBean instance and getProperty and setProperty to access bean properties—are further discussed in "Standard Actions: JSP Tags".

JSP Pages and Alternative Markup Languages

JavaServer Pages technology is typically used for dynamic HTML output, but the JSP specification also supports additional types of structured, text-based document output. A JSP translator does not process text outside of JSP elements, so any text that is appropriate for Web pages in general is typically appropriate for a JSP page as well.

A JSP page takes information from an HTTP request and accesses information from a database server (such as through a SQL database query). It combines and processes this information and incorporates it, as appropriate, into an HTTP response with dynamic content. The content can be formatted as HTML, DHTML, XHTML, or XML, for example.

For information about JSP support for XML, refer to Chapter 5, "JSP XML Support" and to the Oracle Application Server Containers for J2EE JSP Tag Libraries and Utilities Reference.

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: These convey information regarding the JSP page as a whole.
Scripting elements: These are Java coding elements such as declarations, expressions, scriptlets, and comments.
Objects and scopes: 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: These 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. There is also discussion of bean property conversions, and an introduction to custom tag libraries (used for custom actions). For more information, see the Sun Microsystems JavaServer Pages Specification.

Note:

This section describes traditional JSP syntax. For information about JSP XML syntax and JSP XML documents, see Chapter 5, "JSP XML Support".

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 specification supports the following directives:

page
include
taglib

pa ge 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 unbuffers the page:

<%@ page buffer="none" %>

Notes:

The default buffer size is 8 KB.
It is illegal to set autoFlush="true" when buffer="none".
A JSP page using an error page must be buffered. Forwarding to an error page (not outputting it to the browser) clears the buffer.
In the Oracle JSP implementation, "java" is the default language setting. It is good programming practice to set it explicitly, however.
For information about using page directive attributes to set the content type and character set for the JSP page and response object, see "Content Type Settings in the page Directive".

inc lude 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.

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 jsp:include takes effect at request-time instead of translation-time. See "Static Includes Versus Dynamic Includes".
The include directive can be used only between files in the same servlet context (application).
See "JSP File Naming Conventions" for information about naming conventions for included files.

tag lib 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 8, "JSP Tag Libraries".

Scripting Elements

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

Declarations
Expressions
Scriptlets
Comments

Declar ations

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. See "Method Variable Declarations Versus Member Variable Declarations" for a comparison between the two.

Expre ssions

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>

Note:

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

Script lets

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.

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 code, one of which includes a JSP expression (which does not require a semicolon). 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. 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.

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

Comm ents

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.

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.

These topics are discussed in the following sections:

Explicit Objects
Implicit Objects
Using an Implicit Object
Object Scopes

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 Actions: JSP 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.

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 JSP 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 at the following location:

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

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.

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. (The programmer should be aware of the server architecture regarding use of JVMs.)
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, which 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 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 "Runtime Error Processing".

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.

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 JSP 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 Actions: JSP Tags" below.)

Note:

The request, session, and application scopes also apply to servlets.

Standard Actions: JSP Tags

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 can 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

For standard actions, there is a set of tags defined in the JSP specification. Although directives and scripting elements described earlier in this chapter are sufficient to code a JSP page, the standard tags described here provide additional functionality and convenience.

Here is the general tag syntax for JSP standard actions:

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

Alternatively, if there is no body:

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

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

jsp:usebean
jsp:setProperty
jsp:getProperty
jsp:param
jsp:include
jsp:forward
jsp:plugin

js p: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 JSP 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.

Intended use of the class attribute is to specify a class that can be instantiated, if necessary, by the JSP container. The class cannot be abstract and must have a no-argument constructor. Intended use of the type attribute is to specify a type that cannot be instantiated by the JSP 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 JSP 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.

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 JSP container creates the instance by using the instantiate() method of the java.beans.Beans class.

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

js p: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 (defined in the preceding jsp: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" />

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

Important:

Note the following for property="*":

To specify that iteration should continue if an error is encountered, set the setproperty_onerr_continue configuration parameter to true. This parameter is described under "JSP Configuration Parameters".
The JSP specification does not stipulate the order in which properties are set. If order matters, and if you want to ensure that your JSP page is portable, you should use a separate jsp:setProperty statement for each property. Also, if you use separate jsp:setProperty statements, the JSP translator can generate the corresponding setXXX() methods directly. In this case, introspection occurs only during translation. There will be no need to introspect the bean during runtime, which is more costly.

js p: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" />

js p:param tag

You can use jsp:param 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" />

js p: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 JSP container support either a "true" or "false" setting, with "false" being the default. (The JSP 1.1 specification supported only a "true" setting, with flush being a required attribute.)

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

Notes:

The jsp:include tag, 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 tag can be used only between pages in the same servlet context (application).

js p: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>

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 tag can be used only between pages in the same servlet context.
The jsp:forward tag results in the original request object being forwarded to the target page. As an alternative, if you do not want the request object forwarded, you can use the sendRedirect(String) method specified in the standard javax.servlet.http.HttpServletResponse interface. This sends a temporary redirect response to the client using the specified redirect-location URL. You can specify a relative URL; the servlet container will convert the relative URL to an absolute URL.

js p: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. 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 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 necessary when using jsp:param in a jsp:include or jsp:forward action.)

Use a jsp:fallback start -tag and end-tag to delimit alternative text to execute if the plugin cannot run.

The following example, from the Sun Microsystems JavaServer Pages Specification, Version 1.2, shows the 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 tag as well. Use of these parameters is according to the general HTML specification.

Bean Property Conversions from String Values

As noted earlier, when you use a JavaBean through a jsp:useBean tag in a JSP page, and then use a jsp:setProperty tag to set a bean property, string input can be used to specify the value of a non-string property through conversions that happen behind the scenes. There are two conversion scenarios, covered in the following sections:

Typical Property Conversions
Conversions for Property Types with Property Editors

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.

Table 1-1 Attribute Conversion Methods

Property Type	Conversion
Boolean or boolean	According to `valueOf(String)` method of `Boolean` class
Byte or byte	According to `valueOf(String)` method of `Byte` class
Character or char	According to `charAt(0)` method of `String` class (inputting an index value of 0)
Double or double	According to `valueOf(String)` method of `Double` class
Integer or int	According to `valueOf(String)` method of `Integer` class
Float or float	According to `valueOf(String)` method of `Float` class
Long or long	According to `valueOf(String)` method of `Long` class
Short or short	According to `valueOf(String)` method of `Short` class
Object	As if `String` constructor is called, using literal string input The `String` instance is returned as an `Object` instance.

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 method setAsText(String text) 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.

Custom Tag Libraries

In addition to the standard JSP tags discussed above, the JSP specification lets vendors define their own tag libraries, and lets vendors implement a framework that allows customers to define their own tag libraries as well.

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 when manually coding a JSP page, but they might also be used automatically by Java development tools. A standard 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:

Tag library descriptor files

A tag library descriptor (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.
Tag handlers

A tag handler specifies the action of a custom tag and is an instance of a Java class that implements either the Tag, IterationTag, or BodyTag interface in the standard javax.servlet.jsp.tagext package. Which interface to implement depends on whether the tag has a body and whether the tag handler requires access to the body content.
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 are specified in the TLD file or in a subclass of the TagExtraInfo abstract class (in package javax.servlet.jsp.tagext). This document refers to a subclass of TagExtraInfo as a tag-extra-info class. The JSP container uses instances of these classes during translation.
Tag-library-validators

A tag-library-validator class has logic to validate any JSP page that uses the tag library, according to specified constraints.
Event listeners

You can use servlet 2.3 event listeners with a tag library. This functionality is offered as a convenient alternative to declaring listeners in the application web.xml file.
Use of web.xml for tag libraries

The Sun Microsystems Java Servlet Specification 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 descriptor 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 Chapter 8, "JSP Tag Libraries". For further information, see the Sun Microsystems JavaServer Pages Specification.

For complete information about the tag libraries provided with OC4J, see the Oracle Application Server Containers for J2EE JSP Tag Libraries and Utilities Reference.

JSP Execution

This section provides a top-level look at how a JSP page is run, including on-demand translation (the first time a JSP page is run), the role of the JSP container and the servlet container, and error processing.

Note:

The term JSP container first appeared in the Sun Microsystems JavaServer Pages Specification, Version 1.1, replacing the term JSP engine that was used in earlier specifications. The two terms are synonymous.

JSP Containers in a Nutshell

A JSP container is an entity that translates, executes, and processes JSP pages and delivers requests to them.

The exact make-up of a JSP container varies from implementation to implementation, but it will consist of a servlet or collection of servlets. The JSP container, therefore, is executed by a servlet container. Servlet containers are summarized in "Servlet Containers".

A JSP container can be incorporated into a Web server if the Web server is written in Java, or the container can be otherwise associated with and used by the Web server.

JSP Execution Models

There are two distinct execution models for JSP pages:

In most implementations and situations, the JSP container translates pages on demand before triggering their execution; that is, at the time they are requested by the user.
In some scenarios, however, the developer might want to translate the pages in advance and deploy them as working servlets. Command-line tools are available to translate the pages, load them, and publish them to make them available for execution. You can have the translation occur either on the client or in the server. When the user requests the JSP page, it is executed directly, with no translation necessary.

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 JSP 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 JSP 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. This is handled automatically during OC4J installation, as discussed in "JSP Container Setup".

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.

For more information, see "JSP Pretranslation" and "Deployment of Binary Files Only".

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 "The ojspc Pretranslation Utility".

JSP Pag es and On-Demand Translation

Presuming the typical on-demand translation scenario, a JSP page is usually executed as follows:

The user requests the JSP page through a URL ending with a .jsp file name.
Upon noting the .jsp file name extension in the URL, the servlet container of the Web server invokes the JSP container.
The JSP container locates the JSP page and translates it if this is the first time it has been requested. Translation includes producing servlet code in a .java file and then compiling the .java file to produce a servlet .class file.

The servlet class generated by the JSP translator extends a class (provided by the JSP container) that implements the javax.servlet.jsp.HttpJspPage interface (described in "Standard JSP Interfaces and Methods"). The servlet class is referred to as the page implementation class. This document will refer to instances of page implementation classes as JSP page instances.

Translating a JSP page into a servlet automatically incorporates standard servlet programming overhead into the generated servlet code, such as implementing the HttpJspPage interface and generating code for its service method.
The JSP container triggers instantiation and execution of the page implementation class.

The JSP page instance will then process the HTTP request, generate an HTTP response, and pass the response back to the client.

Note:

The preceding steps are loosely described for purposes of this discussion. As mentioned earlier, each vendor decides how to implement its JSP container, but it will consist of a servlet or collection of servlets. For example, there might be a front-end servlet that locates the JSP page, a translation servlet that handles translation and compilation, and a wrapper servlet class that is extended by each page implementation class (because a translated page is not actually a pure servlet and cannot be run directly by the servlet container). A servlet container is required to run each of these components.

Requesting a JSP Page

A JSP page can be requested either directly through a URL or indirectly through another Web page or servlet.

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/dir1/HelloWorld.jsp

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

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

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

Note:

General servlet and JSP invocation are discussed in the Oracle Application Server Containers for J2EE Servlet Developer's Guide.

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/dir1/HelloWorld.jsp" /a>

The application-relative path in a JSP statement is:

<jsp:include page="/dir1/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 Actions: JSP Tags" discusses the jsp:include and jsp:forward statements.)

1 General JSP Overview

Introduction to JavaServer Pages

What a JSP Page Looks Like

Convenience of JSP Coding Versus Servlet Coding

Servlet Code

JSP Code

Separation of Business Logic from Page Presentation: Calling JavaBeans

JSP Pages and Alternative Markup Languages

Overview of JSP Syntax Elements

Directives

page directive

include directive

taglib directive

Scripting Elements

Declarations

Expressions

Scriptlets

Comments

JSP Objects and Scopes

Explicit Objects

Implicit Objects

Using an Implicit Object

Object Scopes

Standard Actions: JSP Tags

jsp:useBean tag

jsp:setProperty tag

jsp:getProperty tag

jsp:param tag

jsp:include tag

jsp:forward tag

jsp:plugin tag

Bean Property Conversions from String Values

Typical Property Conversions

Conversions for Property Types with Property Editors

Custom Tag Libraries

JSP Execution

JSP Containers in a Nutshell

JSP Execution Models

On-Demand Translation Model

Pretranslation Model

JSP Pages and On-Demand Translation

Requesting a JSP Page

Directly Requesting a JSP Page

Indirectly Requesting a JSP Page

pa ge directive

inc lude directive

tag lib directive

Declar ations

Expre ssions

Script lets

Comm ents

js p:useBean tag

js p:setProperty tag

js p:getProperty tag

js p:param tag

js p:include tag

js p:forward tag

js p:plugin tag

JSP Pag es and On-Demand Translation