Welcome to JSP Corner, Part 4. We'll be adding some more features to our eMusic application, which we started putting together in Part 3 (PBDJ, Vol. 8, issue 12). We looked at the Logon process and built the Logon.jsp, validateLogon.jsp, and LogonError.htm pages.

In Part 4 we complete the Logon process shown in Figure 1 by building our Home.jsp page and all related pages. This page contains the main viewable area, a search form, and a navigation bar that allows the user to move through the application (see Figure 2).

The Home.jsp page will use HTML frames to divide the screen into its three respective parts, as this was how the original Sybase application was written. Another alternative is to use HTML tables or dynamic HTML. The Home.jsp page that defines the frames is shown in Listing 1. Nothing too special here if you?re familiar with frames. As we can see from this listing, we have three JSP pages that need to be written to populate our frames:

• eMusic.jsp
• Search.jsp
• Navigation.jsp

The Search.jsp page uses an HTML form to collect user input and calls a Java servlet to find related CDs in the database. This area could be the topic of a future article, and is similar to both the Logon.jsp and validateLogon.jsp pages (covered in Part 3), as it relies on an HTML form to collect data.

The Home.jsp, Search.jsp, and the eMusic.jsp pages could have just as easily been given an .htm extension, as none of them have any JSP code. In hindsight this should be done to avoid unnecessary compilation of these pages by the container. The Navigation.jsp page, however, does have JSP code, including some new JSP tags, and it?s the main focus of this article.

The Navigation.jsp Page
The purpose of the Navigation.jsp page shown in Listing 3 is to display the correct images that make up the menu for the Web site. Which menu images are shown is based on whether or not the user has logged into the Web application. If a user hasn?t logged in, the navigation page shows a set of images, as shown in the left-hand frame of Figure 2. If a user has logged into the Web site, a different set of images will be displayed in the left-hand frame (see Figure 3). This prevents users from accessing the "view cart" or the "purchase" functionality without a user ID.

Instead of forcing a user to log in each time he or she uses the application, use a cookie that stores the user ID. The application could look for this cookie and use it without requiring the user to log in first. Currently it doesn?t do this.

The checkLogon.jsp Page
The functionality to determine if a user has logged into the application is pretty generic; we?ll probably want to reuse this code in several different places throughout our Web site. Instead of writing this code directly into the Navigation.jsp page, we put it in a separate page named checkLogon.jsp (see Listing 4).

This page uses the session object to see if the user logged in yet. We?ll cover the session object in the next article, so for now accept that fact that it holds data for a particular user across page requests and we?ll get into the how next time. The validateLogon.jsp page is responsible for updating the session data based on whether the user ID and password are valid. The session data stored by the validateLogon.jsp page is used by the checkLogon.jsp page to determine whether there?s a valid user log?ed into the application. The checkLogon.jsp page declares a Boolean variable isValid, which will hold true if the user is logged in and false otherwise.

The Include Directive
The Navigation.jsp page can use the logic in the checkLogon.jsp page by including it in the page using the include directive. The syntax of the directive is:

<%@ include file="checkLogon.jsp">

The file attribute of the directive specifies the name of the file to be included and the location of the file using a URL relative to the location of the JSP page containing the directive. If you remember from Part 1 (Vol. 8, issue 9), directives tell the container what to do before the JSP page is compiled. In this case, the include directive tells the container to include the contents of the specified file as part of the original page before it?s compiled into a servlet. Our Navigation.jsp page will look and act as if the checkLogon.jsp page contents were copied and pasted over the include directive and then the page deployed and compiled.

The include directive allows us to reuse the same code or static text in several pages in our application with a single tag. This not only makes code reuse easy but also allows us to keep the shared code in a single file, making it easier to maintain.

By including a JSP page with a directive, we have access to the variables that are declared on the included page. For example, the isValid variable declared in checkLogon.jsp can be used in the Navigation.jsp page to determine how to set the NavPage String variable that will be used to display the correct menu:

<%
String NavPage = "";
if (isValid) {
NavPage = "NavigationVOK.jsp";
}
else {
NavPage = "NavigationVLogon.jsp";
}
%>

This is possible because the static contents, not the output of the included page (checkLogon.jsp), are placed in the source page (Navigation.jsp) before the source page is compiled.

An important consideration when deciding to use the include directive is how often the contents of the included file changes. If the contents change often enough it might not be a good design choice to use the include directive, because the container recompiles a JSP page only if there was a change made to the requested page. Because the source page (Navigation.jsp) is the page that?s requested, not the included page, the updated contents of the included file aren?t detected and therefore not copied into the source page. The only way to get the updated contents from the included page into the source page is to make a change to the source page, forcing the container to recompile it.

Another important consideration to keep in mind when using the include directive is that because the contents are copied at compile time, the source page can?t change which file is included at runtime.

Last, the included file doesn?t have to be a JSP page, but remember it?s only the static contents of the file, not the dynamic output, that?s placed into the source file.

Changes to the Include Directive
This application was written using Jaguar CTS 3.6.1, which supports the JSP 1.1 specification. Since the JSP 1.2 specification is final, I?ll try to keep track of important changes and note them accordingly. There were no major changes to the include directive in the new JSP specification

NavigationVLogon.jsp and NavigationVOK.jsp
The NavigationVLogon.jsp page is shown in Listing 5 and the NavigationVOK.jsp page in Listing 6. Both of these pages define a static HTML table that contains the correct images and menu options. Neither of these pages contains any JSP code, therefore they can be renamed with an .htm extension to avoid a compile by the container.

The Include Action Tag
The include action tag is used to include the content generated by another server resource as opposed to the include directive, which includes the static content. The syntax of the include action tag is:

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

The include action tag uses an XML syntax and must be properly ended with the /> instead of the typical > used to close an HTML tag.

The page attribute of the tag specifies the name and location of the file to be included. Unlike the include directive, the include action tag is handled at runtime instead of at compile time. Including a page using this action tag involves temporarily transferring control from the source page (Navigation.jsp) to the included page. The included page is executed (if it?s an executable resource like a JSP or servlet) on the server and its generated output is placed into the source page where the include tag was originally located. The source page regains control and continues processing (see Figure 4).

The flush attribute of the tag is required and must be set to true (in JSP 1.1). It tells the container to flush the buffer of its contents before transferring control to the included page. The buffer stores all the generated output and holds it before it?s sent to the client. This allows the JSP page to add HTTP headers and cookies, as well as discard the generated content before it?s sent to the client.

Since the include tag flushes the buffer of the source page before control is transferred to the included page, any generated content written into the buffer by the source page is committed and sent to the client. From a practical perspective this means that the JSP page can?t set any more HTTP headers or add any more cookies, nor can the source page forward the request to another page. These restrictions also apply to the included page.

Because the included file is actually run by the container, any changes made to the page are detected by the container and cause the page to be recompiled. This allows changes to be picked up quickly and easily. Using the include action tag allows us to easily add more menu options without making any changes to the Navigation.jsp page.

The include action tag allows the Navigation.jsp page to dynamically decide, based on different runtime conditions, which JSP page it should include to display the correct menu. In the Navigation.jsp page a String variable, NavPage, is set to the name of the page that should be included based on the results returned by checkLogon.jsp. The value of the String can be used as the input to the page attribute using the JSP expression. The following is the syntax for this:

<jsp:include page="<%= NavPage %>" flush="true" />

Unlike the include directive, the source page can?t use variables defined in the included file using the include action tag. Any data that must be shared between the included file and the source page must be handled using the session object (or some other data source accessible by the source page).

The include action tag allows data to be passed from the source page to the included page. This is done using the param action tag, which allows data to be sent in name/value pairs. The parameters are added to the original request object of the source page, which is sent to the included page. These new values are accessible only from the included page; they?re not stored in the request object when the included page returns control to the source page. The syntax of the include action tag with the param action tag is shown below:

<jsp:include page="url" flush="true" >
<jsp:param name="foo" value="bar" />
<jsp:param name="hello" value="world" />
</jsp:include>

The param action tags are part of the body of the include action tag. There can be as many param tags as needed to send the data. Notice that the include action tag no longer ends with the /> delimiter. It ends with the </jsp:include> tag.

Using the include action tag is the same as using the RequestDispatcher. A reference to the RequestDispatcher object can be acquired using the getRequestDispatcher method on the request object. Once we have a reference to the RequestDispatcher object, we call the include method that passes the request and the response objects to actually transfer control to the target.

<%
request.getRequestDispatcher("NavigationVOK.jsp").include(request, response);
%>

Changes to the Include Action Tag
A false value for the flush attribute wasn?t valid in JSP 1.1, but is now valid and is the default value. If the value of the flush attribute is false, the buffer isn?t flushed, giving more control to the source and included pages.

Wrapping Up
Reusing code in a JSP application is easy using either the include directive or the include tag. Both provide similar functionality, but it?s important to understand the differences so you choose the right option as you design your application.

Here?s a recap of the include directive:

• Static contents are "included" at compile time.
• There?s no transfer of control to another page.
• Using any changes made to an included file requires the source page to be recompiled.
• You can use variables that are defined in the included file
• You can?t change which file is included at runtime.
• The included page is generally a static Web resource (HTML, JSP code).
• It doesn?t flush the buffer or restrict the page from forwarding the request.

• Generated output is "included" at runtime.
• Transfers control temporarily to the specified page.
• Using any changes to the included file doesn?t require a recompile of the source page.
• You can?t use variables that are defined in the included file.
• You can change which file is included at runtime.
• The included page can be any Web resource (static file, CGI, Servlet, JSP).
• It flushes the buffer and restricts the page from forwarding the request.