Section 4.1. JSP Basics

4.1. JSP Basics

The JSP specification is part of the full J2EE specification, and JSP engines are included with most major servlet engines. The Tomcat 5.5 server from the Apache project is the reference implementation for both the Servlet 2.4 and JSP 2.0 specifications, and is freely available. For information on downloading and installing Tomcat, see http://jakarta.apache.org/tomcat. The rest of this chapter assumes some familiarity with the concept of a web application and servlets. Chapter 3 covers servlets and web applications in more detail. For now, it is enough to know that a servlet is a compiled Java class that responds to a web request, and a web application is a collection of servlets and other resources.

Since the JSP architecture is based on the servlet architecture, JSP support within a web server provides a translation layer. Individual JSPs are text files stored on the web server and accessed via their real path. For example, if a JSP named index.jsp resides at the root of the "enterprise" web application, it would be accessed by a request to http://localhost:8080/enterprise/index.jsp, assuming that the web server is running on port 8080 of localhost. When the JSP is first requested, the JSP engine uses the JSP file to generate the source code for a servlet. The generated source is then compiled, installed into the servlet engine, and used to service the request. Once the JSP has been compiled, the compiled version is saved and used to service additional requests according to the standard servlet lifecycle. Figure 4-2 shows the process in more detail.

When the JSP file is modified, the server detects the change and rebuilds the corresponding servlet. The compilation phase imposes a slight delay the first time the page is retrieved. If necessary, many servers allow precompilation of JSPs to get around this problem.

Now is a good time to look at a simple JSP, so here's an example that displays the current date:

 <html> <body>  Hello, visitor. It is now <%= new java.util.Date(  ).toString(  ) %> </body> </html>

Figure 4-2. JSP lifecycle

This looks easy enough. The only part of the example that is not regular HTML is the % tag. JSP elements come in two forms: the simple <% %> entity, used for directly embedding Java code and issuing JSP specific directives, and XML style "action tags," which we'll see a little later. The <%= %> tag is an expression tag, which inserts the value of a single Java expression into the page's output. For space reasons, we're not going to include the Java code produced by the system, but if you want to look at it, you can find it in the web server's working areas. For Tomcat 5, the path is /<tomcat_path>/work/Catalina/<servername>/<webappname>. Figure 4-3 shows the output sent to the client browser.

Figure 4-3. Output from date display JSP

Now, let's try something a little more complicated. The <% %> element can insert regular Java code, which can control the flow of the page. The following example checks whether it's before or after noon (we'll count nighttime as the afternoon for the purpose of this sample) and displays an appropriate greeting:

 <html> <body> <% java.util.Date theDate = new java.util.Date(  ); %> <% if (theDate.getHours(  ) < 12) { %> Good morning, <% } else { %> Good afternoon, <% } %>  visitor. It is now <%= theDate.toString(  ) %> </body> </html>

Two things should be noted about this example. The first is the declaration of a local variable in the first pair of <% %> tags. Unlike the %= tags, nothing is displayed. The next JSP element includes a Java if statement that operates on the variable. Note that we don't finish the if statement in the JSP tag, but return to template text. This text will be displayed if the if clause evaluates to true. The next JSP element closes the if and begins an else. It is followed by the text to be displayed in the else case, and a final JSP element to close the else. The rest of the file is the same as in the first example, except we use the Date object created earlier rather than instantiating a new one.

When viewed in the afternoon, the JSP-generated servlet produces HTML that looks like this:

 <html> <body>   Good afternoon,    visitor. It is now Mon Dec 24 14:50:39 EST 2007 </body> </html>

Note that there is some whitespace where some of the JSP tags were. This is because we placed whitespace around them in the source JSP file. The JSP processor removes the tags themselves, but has no way of determining whether it should also remove the carriage returns that follow them. This is not a problem for HTML, since the web browser compresses all whitespace characters into a single space character, but you should be aware of this behavior when debugging or producing plain-text output.

4.1.1. Directives and Declarations

JSP also allows the insertion of JSP directives , which control behavior for the entire page. Directive tags begin with <%@ rather than <%. There are three directives. The first, include, simply includes a static file into the page output. So to include a copyright notice at the bottom of each JSP, you can just add the tag:

 <%@ include file="copyright.html"%>

The second directive, page, is more flexible. It defines parameters that relate to the current JSP and is valid across all invocations of that page. Table 4-1 displays the possible attributes of the page directive.

Table 4-1. JSP page directive values
Name	Description
autoFlush	Set to `true` or `false`, identifying whether the page buffer should be flushed when full. The default is `true`.
buffer	Set the buffer size, in kilobytes. The default is `8kb`, and values must be in the format of `number` `kb` or `none`.
contentType	Set the MIME type or MIME type and charset. The default is `text/html`.
errorPage	An optional path to a custom error-handling page.
extends	An optional fully qualified class name of a class implementing `javax.servlet.jsp.JspPage` or `javax.servlet.jsp.HttpJspPage`.
import	A comma-separated list of Java classes or packages to import.
info	Text describing this JSP. The text entered here can be used by a server administration tool.
isErrorPage	Identifies this page as an error page, making the exception object (see next section) available to script elements.
isThreadSafe	Set to `true` or `false`, indicating whether this JSP should implement the servlet `SingleThreadModel`.
language	The scripting language for this page. The default is `java`, and the JSP specification doesn't require support for any other language, although some application servers support JavaScript.
session	Set to `true` or `false` depending on whether the page should participate in user sessions. The default is `TRue`.

The final directive, taglib, is discussed later in this chapter.

JSP supports another tag sequence that globally affects all instances of a page. This is the declaration element, which begins with <%! and declares a global variable within the JSP. Unlike variables declared in a standard <% %> tag pair, variables declared with <%! will be available for all invocations of the JSP. For example:

 <%! int globalHitCounts = 0; %> This page has been accessed <%= ++globalHitCounts %> times.

However, use of declarations introduces thread safety and lifecycle issues. For example, there is no guarantee that the JSP will not be rebuilt and reloaded. If this happens, the hit count will return to 0. Therefore, for most applications, you should use other approaches for maintaining global data.

4.1.2. Built-in Objects

In addition to objects declared within a JSP file itself, Java code running within a JSP has access to a set of classes provided by the web server. These classes allow for communication between JSPs, interaction with the JSP container, and support for sessions and elaborate output. In servlets, for instance, request parameters are retrieved from the browser via the getParameter( ) method of an HttpServletRequest object. JSPs can do the same thing. The following JSP fragment uses the built-in request object (which maps to HttpServletRequest) and the out object (which provides a PrintWriter) to echo the form parameters submitted by the client):

 <ul> <%  java.util.Enumeration e = request.getParameterNames(  );  while(e.hasMoreElements(  )) {     String name = (String)e.nextElement(  );     out.println("<li>" + name + ":" +     request.getParameter(name));  } %> </li>

Table 4-2 lists the objects available to a JSP.

Table 4-2. Objects available in JSPs
Name	Type	Description
application	javax.servlet.ServletContext	The servlet context for this web application.
config	javax.servlet.ServletConfig	The `ServletConfig` object associated with this page.
exception	java.lang.Throwable	For error pages only, the exception that triggered the error.
out	javax.servlet.jsp.JspWriter	A `PrintWriter` subclass that writes to the page's output stream.
page	java.lang.Object	The implementation class instance currently processing the request. When Java is the scripting language, `page` is synonymous to `this`.
pageContext	javax.servlet.jsp.PageContext	The page context for this JSP.
request	`javax.servlet.ServletRequest` or `javax.servlet.http.HttpServletRequest`	The protocol-specific request object for this request.
response	`javax.servlet.ServletResponse` or `javax.servlet.http.HttpServletResponse`	The protocol-specific response object for this request.
session	javax.servlet.http.HttpSession	For pages retrieved over HTTP, the current user's `HttpSession` object.

4.1.3. Sharing Data Between JSPs, Other JSPs, and Servlets

HTTP is a stateless protocol, and by extension, the Web is inherently a stateless environment. If a client makes a series of connections to a web server, there is no built-in foolproof mechanism for the web server to associate the sequential requests with the same user. Similarly, a JSP or servlet will treat each request individually, regardless of whether the user has made other requests in the recent past.

The simplest form of communication between JSPs is a hyperlink. A JSP produces an HTML-formatted link, which the user can then click on to request another JSP. HTTP allows name=value parameters to be associated with an HTTP request. So, for example, if JSP 1 needs to inform JSP 2 of the user's language, it might use a JSP fragment like this one to produce a link:

 <a href="page2.jsp?language=<%= userLanguage %>">Go to page 2</a>

This HTML fragment includes a JSP expression that passes a variable called userLanguage as a request parameter to page2.jsp, which can then retrieve it from the session.

This is a clumsy approach, however, for all but the simplest applications. For one thing, as soon as the user accesses a page that doesn't pass the language parameter on, such as a static HTML page or a link off-site, the information is gone and must somehow be retrieved again. A better place to store this information is the user's session, accessible via the session object made available to all JSPs served over HTTP. For more on the session object, see Chapter 5. Information that is global to the entire application can be stored in the ServletContext object, which is accessible via the application object.

All information loaded into the session and application contexts will be available to any JSP that participates in the session or is part of the application. Servlets within the application will also be able to access the data. In the next section, we'll look at some other ways of using these mechanisms to share data across JSPs.