JSP Page Elements

This section discusses how to use each of the three different JSP page element types:

• Directives

• Scripting elements and implicit objects

• Expressions

JSP Directives

When you construct JSP pages, you can specify certain directives to the JSP container. For example, you can specify an error page that is called if there are problems with your JSP page. Or, you can specify what Java classes you want to include during execution. The way to do this is through a JSP directive.

Directives are specified by tags that use the <%@ and %> characters. An example of a page directive that tells the JSP container to import all the classes in the java.util package is:

<%@ page import= "java.util.*" %>

There are several types of directives for JSP:

• Page directives, which are specific to the current page.

• Include directives, which specify how to include another file in a JSP.

• Tag library directives, which specify how to include and access custom tag libraries. Note that tag libraries enable developers to create custom tags for Web developers to use.

For each of these directives, there are defaults for commonly used values. For example, the default is to have a page be within the scope of an HttpSession. In the following sections, bold text signifies the default values if the tag is not specified. The default values are very convenient because developers don't have to specify every single directive explicitly.

Page Directives

A page directive tag begins with the characters <%@ page and then includes directive types and values in the body of the tag. For example, the following tag is a page directive that tells the JSP container that your JSP page should be activated to work with sessions. As you would expect, sessions for JSP pages are very similar to those for servlets.

<%@ page session ="true" %>

You can include more than one page directive per page directive tag, like this:

<%@ page session ="true"  import="com.girdley.package.*" %>

Other useful page directives include:

• language="language name" enables you to specify the programming language used in the JSP page. The default value for this directive is “Java.” For applications built on WebLogic Server, this tag is not of much use because WebLogic Server only supports the Java language for JSPs. In the future, the JSP standard may allow other languages.

• extends="package.class" enables you to specify that your JSP page (and therefore the resulting servlet class) extends another class. For example, if you want to have your JSP extend a base class called foo.class, include a page directive like this:

<%@ page extends ="foo" %>

You also can create a public class that includes “helper” methods to use in all your JSP pages. You could create this class like this:

public class myBaseClass {

     public String myHelperMethod() {
           // Do work here…
     }
}

Then, if your JSP page included the following directive,

<%@ page extends ="myBaseClass" %>

this would access the method myHelperMethod() from within the Java code in your JSP page. Note that this class must be included in your classpath directly, or indirectly by the include tag in a Web application. Otherwise, you receive a ClassNotFoundException exception.

• import= " { package. class | package .* } , ... " enables you to specify that the container should import Java classes into your JSP page. You will then be able to make calls and instantiate classes that should be imported. For example, if you want to use a cryptographic library in your JSP pages, include the following page directive:

<%@ page import="com.cryptographic.package.*"%>

The following would make one of the utility Java classes, java.util.Hashtable, available in your JSP page:

<%@ page import="java.util.Hashtable"%>

java.lang.*
javax.servlet.*
javax.servlet.jsp.*
javax.servlet.http.*

• session="true |false" enables you to specify whether your JSP page requires that someone visiting it be involved in an HTTP session. In the servlet programming discussion in Chapter 3, we had to check manually to see if a given session existed. The JSP session tag enables you to specify whether a session is required and the container checks automatically for you. We discuss how to access session information later in this chapter. The default value for the session directive is true. So, if you do not specify it as false, the JSP page automatically requires that a client be part of a session.

• buffer=" none| 8KB | size KB" enables you to specify the minimum buffer size for the HTTP response that goes to the client. By default, the response is buffered in 8KB (kilobytes) chunks. You can change the buffer size to suit the needs of your application. If you are returning very large files to the client, you might need to increase the buffer size. In typical Web scenarios, leaving the buffer size at the default value of 8KB is preferable because it allows the Web browser to begin displaying your page before it has been completely downloaded.

• isThreadSafe="true |false" specifies whether the JSP page is threadsafe. Setting this value to true means that multiple threads can execute the code in your JSP page at the same time. Setting this value to “false” means that only one thread can execute the code in your JSP page at a time. The default value of this directive is true if it is not explicitly set.

• errorPage="relativeURL" enables you to specify a relative path to a JSP page that WebLogic Server uses to handle errors thrown from the current page. For example, to specify that error.jsp handle errors that arise in the execution of your JSP page, you include this page directive:

<%@ page errorPage="error.jsp"  %>

• isErrorPage="true| false" enables you to specify that the given JSP page is an error-handling page. As mentioned previously, you want to build JSP pages specifically to handle the errors that arise during execution of your application. This tag indicates for the JSP container that the page being executed is an error page and should be handled differently. Later in this chapter, we cover how to access the error information to handle it appropriately.

• contentType="mimeType [ ; charset =characterSet ] enables you to specify the MIME type and character set that be used on output by your JSP page. The default values are text/html and charset=ISO-8859-1 for the character set. Use this tag to define the character set for languages other than English. The following defines that the JSP should display a Kanji (Japanese) character set:

<%@ page contentType = "text/html"; charset="SJIS"; %>

The following defines that the page should use the default values for English text:

<%@ page contentType = "text/html"; charset="ISO-8859-1"; %>

WebLogic Server inherits its support for internationalized text and content directly from the Java platform. Therefore, WebLogic Server also supports any content type that is supported by the underlying Java platform. More information on locales and types supported by Java can be located on the Java Web site at http://java.sun.com/products/jdk/1.2/docs/guide/internet/index. html.

Page Directives in Use

The following example shows page directives in a simple JSP “hello world” page (hello2.jsp).

<!doctype html public "-//w3c/dtd HTML 4.0//en">
<html>

<!—- A page directive to import a number of classes.  -->
<%@ page import="javax.naming.*, java.util.*,java.sql.*" %>
<!—- A page directive that specifies the page to be called if an
exception is thrown.  -->
<%@ page errorPage="error.jsp"  %>

<!—A page directive that specifies that the page is thread safe.
The container allows multiple threads of execution to service JSP
requests at the same time. -->
<%@ page isThreadSafe="true" %>

<!—A page directive that specifies that the page should have a
session associated with it.  If "true", WebLogic Server creates a
session automatically if one does not exist. If "false", and the
JSP page is not part of a session, the implicit session object is
not available and our JSP page throws an error if we try to
access it. -->
<%@ page session ="false" %>

<!-- Standard HTML -->
<head>
<title>Hello World</title>
</head>

<body bgcolor=#FFFFFF>
<font face="Helvetica">


<h2>
<font color=#DB1260>
Hello World
</font>
</h2>

<!—An expression to print hello world to the out object. -->
<%
out.print("<p><b>Hello World!</b>");
%>

</body>
</html>

The output of this JSP page might look like Figure 4-2.

Note that all the white space included in your JSP page outside of the <% .. %> tag is rendered as well.

Include Directives

The include directive includes any arbitrary text or JSP page code when the JSP is executed. The include directive refers to a file specified by a path relative to the current location of the JSP page. If the included JSP page were in a subdirectory named mysubdirectory and was named foo.jsp, the relative path would be my subdirectory/foo.jsp.

The include directive is delimited by the <%@ and %> characters. For example, if you want to instruct WebLogic Server to include the contents of a text file named todaysweather.txt in the output of your JSP, use the following code:

<%@ include file="todaysweather.txt" %>

If the todaysweather.txt file is located in a subdirectory named secret, specify a relative URL:

<%@ include file="secret/todaysweather.txt" %>

The include directive can also be used to include entire JSP files. WebLogic Server executes JSP files, unlike text files, when their output is included. The following code includes a JSP file named myresponse.jsp:

<jsp:include page="response.jsp">

Remember that JSP files are evaluated from the top down. Output from a given include directive is inserted at that point in the evaluation of the JSP page.

Note that the directive to include a JSP page is different from the directive that includes text documents. If you use the file include to pull in a JSP page, the source of the JSP page is included and then recompiled, rather than including the possibly already-compiled page. That is, the <%@include file="foo.jsp"%> directive pulls in the text of the included file and compiles it as if it were part of the including file. The <jsp:include page="foo.jsp"> tag compiles the file as a separate JSP file, and embeds a call to it in the compiled JSP.

Why Include Directives?

Include directives are very powerful in the context of a J2EE Web application. They enable you to modularize your JSP pages, making development and maintenance much simpler. For example, to place a navigation bar into every JSP page, create a single page called navigation.jsp. The output of this JSP page would be the navigation bar that you show to every user.

Then, simply add an include directive to every page that you develop for your Web application. The same technique can be extended to page headers and footers as well. Different JSP pages can be added together to create the entire site. And, if you want to change any component of all pages, you simply change the individual navigation.jsp, footer.jsp, and so forth. The WebAuction site uses this technique for the header and for the navigation bar.

Implicit Objects and Scripting Elements

While directives are special JSP tags that enable you to give commands to the WebLogic Server JSP container, scripting elements are a way to specify arbitrary Java code for the container to execute. The major convenience of using JSP instead of arbitrary application code is that JSP contains many predefined implicit objects. This means that you do not need to write code to generate an output stream, instantiate an HTTP response object, and so forth—the container does it all for you.

There are three types of scripting elements for use with JSP. These are:

• A declaration, which enables you to declare methods, variables, and so forth in a JSP page.

• A scriptlet, which is a Java code fragment to be executed when clients request your JSP page.

• An expression, which is a Java code expression that is evaluated, converted to a string, and then shipped to the requesting client.

Before discussing the three types of scripting elements in detail, we'll discuss implicit objects.

Implicit Objects

Implicit objects are objects automatically provided to JSPs by the JSP container. For example, user session information: The JSP container provides an implicit object that you can use in your Java code to get and set the user session information. Other objects are available for different tasks. In general, these objects are very similar to the objects available for servlet development.

The following is a summary of the other available objects:

Implicit Object: out

out is a subclass of the standard Java extension class javax servlet. jsp JspWriter, which enables you to print information to the requester. Whenever you need to send the results of an operation back to the client browser, use the out object that is provided by the JSP container. The simplest way to do this is to call the print method. The following code prints “I play basketball with Nick D.” to the requesting client:

out.print("I play basketball with Nick D.");

The out object has a scope of one page. That means that there is a single instance of the object per JSP page. You can do everything with this out object that you did with the output object you used in your servlets in Chapter 3. This includes modifying HTTP headers, specifying URL rewriting, and so forth.

Remember, the out object is buffered in 8KB chunks. But, you can change the value of this buffering using the page directive buffer described earlier in this chapter. Regardless of the size of the buffer, at the end of the execution of your JSP, WebLogic Server flushes your output buffer and sends the remaining data in your response back to the client.

You can use a number of other methods on the out object:

• public abstract void clear() and public abstract void clearBuffer () enable you to clear the existing buffer for the JSP page. Add the following code if you have data already buffered for output to the client, but decide that you want to clear that buffer:

out.clear();

The difference between the two methods is that clear() throws an exception if data has already been sent to the client when it is called. clearBuffer() does not throw an exception if called after data has already been sent to the client.

• public abstract void flush()causes the current output buffer to be cleared and the data to be sent to the client. This method is automatically called by the JSP container, so you should not use it unless your application explicitly requires you to flush the current buffer output. This method might be useful if you set a very large buffer size in order to streamline transfer of large files. Or, use it as a response to an exception, such as a disk exception.

out.flush();

• public int getBufferSize() returns the size of the buffer in bytes. This is basically the value set using the <%@buffer page directive discussed earlier.

• public abstract int getRemaining() returns the size in bytes of the remaining free space in the output buffer.

Implicit Object: request

request is a subclass of javax.servlet.HttpServletRequest that includes all information provided by the request objects. You should use this request object to access the parameters and the respective values included in the request. To do this, you should use the same methods that were used to access the servlet request object as described in Chapter 3.

To get an Enumeration of the parameter names in this request and assign them to variable foo, you would say:

Enumeration foo = request.getParameter();

To get an Enumeration of all parameter names and values, use the getParameterNames and getParameterValues methods, respectively.

getParameterNames() returns an enumeration of string objects containing the names of the parameters contained in this request.

getParameterValues(java.lang.String name) returns an array of string objects containing all values the given request parameter has, or null if the parameter does not exist. For both of these methods, you could use the methods available in the java.utils.Enumeration class to access the values. To print every parameter name to the requester, use the out implicit object described above:

Enumeration foo = request.getParameterNames();
while (foo.hasMoreElements()) {
out.print (e.nextElement());
}

Implicit Object: session

session is an instance of the javax.servlet.http.HttpSession class. It represents the current session information for the user session. The same methods are available that were described in Chapter 3 for user sessions. For more information on using servlet sessions, review the section in Chapter 3 titled “Conventional Methods for Session Tracking Are Difficult.”

Implicit Object: exception

exception is an instance of java.lang.Throwable that encapsulates the error message received if the page you are creating is an error-handling page. Remember, error-handling pages are those that include the page directive isErrorPage=true. To access the error messages, you can use a number of available methods:

• public String getMessage() and public String getLocalizedMessage(), which return the message contained in the exception object and a localized version of the message, respectively. Localized messages are those intended for different languages. To print out the message of your exception to your user, you could use the following code in your JSP:

out.print("exception: " + exception.getMessage());

• public void printStackTrace() prints out a complete stack trace of the error. This is very helpful to see where the error originated and how it propagated through the system. By default, this method outputs the stack trace to the standard error output stream, which is logged in the application server log on most platforms. This makes it very difficult to locate the error. Fortunately, WebLogic Server provides an extra service that prints out JSP error directly to the Web browser. This is extremely helpful during debugging.

exception.printStackTrace();

If you attempt to use these methods in a page that is not an error page, as specified with the page directive isErrorPage=true, your page execution will fail. If you've specified an error page for your JSP, the error page is executed.

Note: The pageContext, application, and config implicit objects are discussed in Chapter 3 in the section titled “The Web Application Package.”

Scripting Elements

Scripting elements are segments of Java code that are embedded in the JSP page. Scripting elements are compiled and then executed.

There are three types of scripting elements:

• Declarations are scripting elements that declare methods, variables, and so forth in a JSP page. They are used to declare functions and variables to be used during the execution of the page.

• Scriptlets are Java code that is executed when the JSP page responds to a request. Scriptlets define the logic for your JSP pages.

• Expressions are scripting elements written in Java that the JSP container evaluates when the JSP page is executed. Expressions are used to quickly embed dynamic values into JSP pages.

In the following sections, we'll describe each of the scripting elements and how to use them.

Declarations

Declarations are scripting elements that declare methods, variables, or both in a JSP page. The special tags that designate declarations begin with <%! and end with %>. So, let's say you want to declare a variable named foo and assign the value of 3 to it. You use the following declaration tag:

<%!  int foo=3;  %>

This variable, like all declarations, has a scope limited to the current page. If you declare a variable myInt in your JSP page xyz.jsp, it can be accessed by any scripting element on your page but is not available by default to any other JSP page. To get around this problem, the JSP and servlet specifications include the notion of a Web application. Web applications are discussed later in this chapter in the section titled “Using Servlets and JSPs Together: Model View Controller.”

It also is possible to declare methods in your JSP declarations. For example, if you want to create a method named inc that increments an integer, you could say:

<%!
private int inc(int x) {
return x++;
}
%>

Scriptlets

Scriptlets are essentially code fragments that exist in the JSP page and are executed by the container to service client requests. In the current JSP specification, the only language that is available for scriptlets is Java. Scriptlets are designated using the <% and %> characters.

If you have the variable foo and the inc() declarations in your JSP page and wish to increment the variable foo, use the following code:

<%
foo = inc(int foo);
%>

As with declarations, scriptlets by default have a scope limited to the current page.

Expressions

Expressions are scripting elements that contain valid expressions in Java. At execution time for the JSP page, the expression is evaluated, converted to a string, and then placed in the implicit object out. These expressions can be any valid expression in Java. To designate an expression in your JSP page, use the <%= and %> characters to signify the beginning and end of your expression, respectively.

For example, to output the value of the variable foo as used in the previous sections on scriptlets and declarations, use the following code:

<%= foo %>

Any valid expression can be placed in a JSP expression tag.

Actions

Actions are special JSP tags for use with implicit objects and other server-side objects, and for use in defining new scripting variables. Actions are defined using XML syntax only. They typically take the form of <jsp: action name/>. For example, the following action specifies to the JSP container that you wish to include the output of a JSP page named mypage.jsp in the output of your JSP page:

<jsp:include page="mypage.jsp" />

Why Use Actions?

Use actions for certain types of operations: for example, to include the output of another JSP page in your current JSP page. One instance in which this is helpful is if you have a single JSP page that dynamically generates the copyright information for each page of your Web site. Or, perhaps you would like to make use of the capability to forward a user to another JSP page. Standard action tags enable you to do all these things in only one line of code.

Action Types

Two types of actions are available to JSP developers:

• Standard actions are available, by definition, in every JSP container. To use these, you need not import any special classes or libraries.

• Custom actions are available to be “plugged-in” through the use of a JSP feature (discussed later) called tag libraries.

In this section, we'll discuss how to use each of the standard actions.

Standard Actions

Seven standard actions are required to be included in every JSP 1.1-compliant container. These have varied functions and uses. Let's discuss the first four of the standard actions:

• <jsp:include>

• <jsp:forward>

• <jsp:plugin>

• <jsp:param>

We defer discussion of the final three standard actions to a section later in this chapter titled “Using Java Beans with JSPs”:

• <jsp:useBean>

• <jsp:setProperty>

• <jsp:getProperty>

<jsp:include>

The include standard action provides for the inclusion of static and dynamic resources in the current JSP page. The tag specifies the relative URL of the resource to be included in the following format:

<jsp:include page=" copyright.html" />

Note that the include tag begins with <jsp:include and is completed with />.

The include tag is able to refer to any piece of content including HTML pages, JSP pages, servlets, and so forth. The only requirement is that the relative URL specified with the page attribute must be a valid resource type for your JSP container/Web server and also be located in the same application context.

After the included resource is placed on the output stream by the JSP container, request processing resumes. Note that the page output during the execution of the included pages is buffered and flushed prior to inclusion, just as if the remote client requested the included page. Included pages have access only to the out object and cannot set headers. This means that included pages that try to do things like setCookie() on the output stream throw exceptions. This is because both the included and forward actions cause the current JSP/servlet output to be flushed by calling the flush() method. Once a buffer is flushed, the data written to that buffer cannot be modified, including the HTTP header.

The JSP include functionality is the same as that imposed on users of the Request Dispatcher in servlets.

It is sometimes desirable to include content from other resources, not located inside of the same Web application as a JSP page. To accomplish this inside your JSP pages, create a plain URL connection over a socket to the location of the remote resource. Then, load the resource using an input stream and write it to the implicit output object:

URL url = new URL("http://www.nickdattoma.com/nick.gif");
URLConnection connection = url.openConnection();
BufferedInputStream bis = new BufferedInputStream(connec-
tion.getInputStream());
FileOutputStream file =
BufferedOutputStream out = new BufferedOutputStream(new FileOut-
putStream("newnick.gif"));

int i;
i = in.read();

while (i != -1) {
    out.write(i);
    i = in.read();
}
out.flush;

You can do this with text documents as well. In WebLogic Server, you can do the same with SSL security. However, instead of opening a standard URL, you open it using HTTPS. More information on SSL in WebLogic applications is included in 12, Developing Security with WebLogic Server JNDI and JAAS.

<jsp:forward>

The forward action allows for the dispatch of the current JSP request to another resource. The tag specifies the resource to which the request is forwarded using the page attribute. The forward tag begins with <jsp:forward and is completed with />. For example, the following tag forwards the JSP request to the resource named foo.jsp:

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

When using the JSP forward tag, you should use buffered output on the JSP pages. Buffered output is on by default. The buffer is automatically cleared when the forward occurs or when the buffer overflows. If you are using unbuffered pages, any attempt to forward the request after data has been written to the output stream raises an exception.

A JSP forward is different than an HTTP Redirect. With an HTTP Redirect, you send a message back to the Web browser, instructing it to forward to another resource:

response.sendRedirect(myNewURL);

This causes the new URL to display in the Web browser. It also requires another communication between your server and the client browser. On the other hand, the JSP forward is processed on the server. Your JSP forwards handling of the response to another resource.

Using the JSP forward functionality is almost always preferable to sending HTTP redirects—except when you are processing data and concerned if a user clicks Reload on the Web browser, thus resending the data. In those cases, you should use an HTTP Redirect.

<jsp:param>

When the forward or include actions are used, the included page or forwarded page sees the original request object. The original parameters of the request can be augmented with new parameters, as specified by the param tag. The param action provides name/value information pairs to other actions.

The format of the param tag begins with <jsp:param and is completed with />. The following param tag specifies a name/value pair of foo/bar:

<jsp: param name=" foo" value="bar" />

The param element is used in the include, forward, and plugin actions to provide information to other pages in the form of request parameters. These parameters are additive: Each parameter added in the request takes precedence over existing parameters.

When using this tag in conjunction with other actions, the syntax is as follows:

<jsp:forward page=" urlHere"> { <jsp:param .... /> }* </jsp:forward>

Note that two new tags were added in this statement syntax: the parameter and the closing tag </jsp:forward> for the forward action. You can include multiple parameter tags, as indicated by the *, previously. The same syntax applies to the include and plugin actions. An example of using the include action with parameters would be:

<jsp:include page="copyright.jsp">
{ <jsp: param name=" foo" value="bar" /> }
</jsp:include>

<jsp:plugin>

The plugin action instructs the client browser to download the Java plug-in for executing a client-side job. The capability to invoke a plug-in helps the application developer overcome compatibility and versioning issues caused by the wide variety of Web browsers. By using this tag, you can be sure that your applet or JavaBean executes on the appropriate JVM. This ensures a better user experience.

The following example shows the JSP plug-in being used for an applet:

<jsp:plugin type=applet code="Food.class" codebase="/html" >
<jsp:params>
<jsp:param
name="foo"
value="bar"/>
</jsp:params>
<jsp:fallback>
<p> Unable to load the plug-in. Error!</p>
</jsp:fallback>
</jsp:plugin>

The fallback component specifies what the JSP page should do in case the plug-in is unable to be downloaded to the client. The following is the complete syntax for the plug-in action:

<jsp: plugin type=" bean| applet"
code=" classFileName "
codebase=" classFileDirectoryName "
[ name=" instanceName " ]
[ archive=" URIToArchive, ... " ]
[ align=" bottom |top| middle| left| right" ]
[ height=" displayPixels " ]
[ width=" displayPixels " ]
[ hspace=" leftRightPixels " ]
[ vspace=" topBottomPixels "]
[ jreversion=" JREVersionNumber | 1.1 " ]
[ nspluginurl=" URLToPlugin " ]
[ iepluginurl=" URLToPlugin "] >
[ <jsp: params>
[ <jsp: param
name=" parameterName "
value=" parameterValue " /> ]+
</ jsp: params> ]
[ <jsp: fallback> text message for user </ jsp: fallback> ]
</ jsp: plugin>