Programmer's Guide

Chapter 13   Using JavaServer Pages

This chapter describes SilverStream's support for JavaServer Pages (JSP). It gives an overview of JSP integration with SilverStream and explains how to compile JSP files and deploy them to the SilverStream Application Server.

This chapter covers the following topics:

About JSP integration   Top of page

SilverStream provides support for pages that conform to the JavaServer Pages 1.0 specification. JSP 1.0 pages that you've authored outside of SilverStream can run inside a SilverStream Server. SilverStream provides utilities for translating JSP pages into Java source files and for uploading the compiled Java classes to a SilverStream server.

NOTE   Do not confuse JSP pages with SilverStream dynamic pages. Dynamic pages that you author in the SilverStream Page Designer use a very different architecture than JSP. At the present time, the SilverStream Page Designer does not provide tools for authoring JSP pages.

JSP Basics   Top of page

JSP technology can simplify the process of creating dynamic Web content. JSP combines the power of Java with the ease of use of a Web markup language.

With JSP, you can author dynamic Web pages by adding simple markup elements (tags) to a page. Where necessary, you can also extend the capabilities of the page by including calls to JavaBeans components as well as embedded Java code fragments. Because JSP is closely integrated with J2EE, JSP pages can act as a front end to Enterprise JavaBeans components running on an application server such as SilverStream.

JSP 1.0 builds on the Java Servlet 2.1 architecture. To get the most out of JSP, you need to have a good understanding of the Java Servlet 2.1 API.

For complete details on JSP and the Java Servlet API, see your Sun documentation.

Sample JSP page

The following page demonstrates many of the features of JSP:

NOTE   The <jsp:include> action includes content at runtime. JSP also provides a compile-time include mechanism. To include content that should be parsed at compile time, you use the <%@ include > directive.

Here's the source for the date.jsp sample page:

<jsp:useBean id='clock' scope='page' class='util.JspCalendar' type="util.JspCalendar"/>
<jsp:useBean id='sql' scope='request' class='util.JspSQL'/>

<h1> Use the implicit Request object </h1>
<li>Query string: <%= request.getQueryString() %>
<li>Server name: <%= request.getServerName() %>
<li>Server port: <%= request.getServerPort() %>
<li>Remote address: <%= request.getRemoteAddr() %>

<h1> Use a Bean to access date information</h1>
<li>Day of month: is <jsp:getProperty name="clock" property="dayOfMonth"/>
<li>Another form of Day of month: is <%=clock.getDayOfMonth() %>
<li>Year: is <jsp:getProperty name="clock" property="year"/>
<li>Month: is <jsp:getProperty name="clock" property="month"/>
<li>Time: is <jsp:getProperty name="clock" property="time"/>
<li>Date: is <jsp:getProperty name="clock" property="date"/>

<h1> Call a function declared on the JSP page </h1>
<%-- Function declaration --%>
   public String getAString(String x)
   return x + " was passed in";

<li> call getAString: <%= getAString("Hello") %>

<h1> Use a Bean to access a database </h1>
<%= sql.getSQL(request, "Select employeeid as ID, lastname as Name from employees") %>

<h1> Execute a scriptlet that has embedded text </h1>
<% if (java.util.Calendar.getInstance().get(java.util.Calendar.AM_PM) == java.util.Calendar.AM) {%>
Good Morning
<% } else { %>
Good Afternoon
<% } %>

<h1>Include the output of another JSP</h1>
<jsp:include page="include.jsp"/>


As you can see from this example, JSP pages can contain both HTML and Java code. However, interspersing HTML and Java in the same file may not be desirable in many applications. Web page designers don't necessarily know Java, and Java programmers often don't write HTML as well as page designers. Furthermore, by maintaining HTML and Java in the same place, you blur the distinction between static content and dynamic content. For these reasons, you will usually want to keep your Java code separate from your JSP pages. You can do this by maintaining your Java code in JavaBeans components and making calls to these components in your JSP pages.

SilverStream support for JSP   Top of page

SilverStream provides two SilverCmd utilities to help you run JSP pages in a SilverStream Server:

What you need to do to use a JSP page in SilverStream

To use a JSP page in a SilverStream application, you need to:

  1. Write your JSP page.

  2. Run JspCompiler, specifying the JSP page (or XML representation of the page) as input.

  3. Compile the generated Java source files.

  4. Create a JAR file that contains the Java classes.

  5. Write an XML file that contains deployment information.

  6. Run DeployJSP to upload the JAR file to the SilverStream Server.

    An example of using JSP with SilverStream is provided in the SilverStream help. This example includes all of the files you need to deploy a simple JSP application to SilverStream. See Application Techniques>HTML Client Techniques in the help system: Using JavaServer Pages with SilverStream.

Although SilverStream 3.0 supports JSP 1.0, not JSP 1.1, it does, nonetheless, take advantage of some of the features of the JSP 1.1 and Java Servlet 2.2. specifications. For example, the JSP JAR file that you deploy to SilverStream is modeled after the Web Application Archive (WAR) file. SilverStream 3.0 requires that you define URL mappings for accessing the JSP pages in the JAR, just as you would for a WAR file. However, SilverStream 3.0 does not support the use of an XML deployment descriptor or the WEB-INF subdirectory.

How SilverStream processes JSP pages

Each JSP JAR that you upload to SilverStream functions as a complete, standalone application. The JAR file must contain all of the JSP pages, servlets, utility classes (JavaBeans components), static HTML pages, images, and sounds used by the application.

Once you've uploaded a JAR file to the SilverStream Server, each JSP page in the JAR behaves like a servlet. The page is associated with a URL. When a Web client or SilverStream object performs an operation on that URL, the SilverStream Server finds the associated servlet, instantiates it, and calls the init() and service() methods associated with the servlet. When the servlet is about to be unloaded, the server calls the destroy() method.

JSP pages running in SilverStream are not persistent. A new instance of a JSP page is created for each HTTP request.

Although SilverStream's support for JSP is founded on the Java Servlet 2.1 architecture, SilverStream uses the Servlet 2.2 API to implement response buffering. SilverStream uses the following methods of the ServletResponse interface to buffer response data:

If a servlet does not specify the length of its content by calling setContentLength(), SilverStream uses HTTP 1.1 chunking to transfer the content as a series of chunks.

Compiling JSP files   Top of page

JspCompiler translates a JSP page into a Java servlet. When you run JspCompiler against a .JSP page, it generates:

You can also specify an XML file that you've defined (by hand or by using XML editor) as input to JspCompiler. The JSP specification provides a set of guidelines for defining an XML file that represents a JSP page. In general, you will find it easier to use the JSP syntax to define your pages rather than XML. However, if you already have an XML file that defines your page, you can use JspCompiler to process this file directly.

Sun provides a DTD called jsp_1_0.dtd that defines the valid element types for the XML representation of a JSP page. You can find this DTD in the SilverStream/DTDs directory.

After you use JspCompiler to translate a JSP page into a Java source file, you need to compile the generated Java source file.

NOTE   Before compiling the generated Java source file for a JSP page, you need to add the servlet.jar and files to your CLASSPATH. These files are located in the lib subdirectory under your SilverStream installation directory. In addition to these files, you may want to include other items in your CLASSPATH to suit the requirements of your application.

Example 1: Specifying a JSP file as input   Top of page

The following example shows how you can run JspCompiler against a JSP file. The -p switch specifies the package for the generated Java servlet.

  silvercmd jspcompiler -p mypackage myjsp.jsp 

Note that the directory hierarchy in the JAR file must match the package hierarchy you specify when you run JspCompiler.

Example 2: Specifying an XML file as input   Top of page

The following command submits an XML file to JspCompiler. The -v switch tells JspCompiler to validate the XML file and report any errors before generating Java code for the servlet:

  silvercmd jspcompiler -p mypackage -v myxml.xml 

Deploying JSP JARs to SilverStream   Top of page

After you use JspCompiler to translate a JSP page into a Java servlet, you need to compile the generated Java source files and make a JAR file that contains the compiled classes and any supporting components (utility classes, images, and so forth). Once you've completed these steps, you're ready to use DeployJSP to upload the JAR file to a SilverStream Server. When you upload a JSP JAR file to SilverStream, the JSP pages in the JAR are automatically available for user requests; you do not need to restart the server.

Writing the input XML file   Top of page

One of the arguments to the DeployJSP utility is the name of an XML file that provides additional information about the contents of the JAR file. The XML file specifies URLs for the JAR file. In addition, it can optionally specify the names of other JAR files used by the JSP pages contained in the JAR. SilverStream provides a DTD called deploy_jsp.dtd that defines the element types for the input XML file. You can find this DTD in the SilverStream/DTDs directory, along with a sample XML file called deploy_jsp_sample.xml.

In the input XML file, you specify:

Sample XML input file

Here's a sample XML input file for DeployJSP. It defines two URLs that can be used to access this JAR file. In addition, it specifies two additional JAR files that contain objects used by the JSP pages in the current JAR file. One of the JAR files is in the target database; the second JAR file is in a different database:

  <?xml version="1.0" encoding="UTF-8"?> 
<?AgMetaXML 1.0?>
<!DOCTYPE obj_DeployJSP SYSTEM "deploy_jsp.dtd">

   <URLs type="StringArray"> <!-- The list of URLs -->
   <JARs type="StringArray"> <!-- The list of dependency JARs -->

Running DeployJSP   Top of page

The following command deploys the jsptest.jar file to a database called myDatabase on the local machine. The -f switch specifies the input XML file. The -o switch package tells DeployJSP to overwrite the JAR if it already exists on the server.

  silvercmd deployjsp -f jsptest.xml -o localhost myDatabase jsptest.jar 

Using a batch file to deploy the JAR file   Top of page

You can use a batch file to deploy a JSP JAR file to the SilverStream Server. In fact, to simplify the development process, you can perform all steps required to process your JSP page(s) in the same batch file. Then, any time you make a change to any JSP page or other resource in the JAR, you can simply execute the batch file to update the server.

The source for a sample batch file called build_jsp.bat is shown below. The file runs JspCompiler, compiles the generated Java source files, creates the JAR file, and runs DeployJSP, which deploys the JAR to the SilverStream server. It processes two JSP files, date.jsp and include.jsp, and two JavaBeans components, and All of these files are stored in the c:\jsptests\date directory. The batch file is stored in c:\jsptests:

  cd date 

\SilverStream35\bin\silvercmd JspCompiler -p date date.jsp include.jsp

set classpath=c:\SilverStream35\jre\lib\rt.jar;c:\SilverStream35\lib\;c:\SilverStream35\lib\servlet.jar;c:\jsptests;c:\SilverStream35\jre\lib\ext\jndi.jar;c:\SilverStream35\lib\

cd util
cd date
del datetest.jar
jar cvf datetest.jar date/*.class util/*.class
jar tvf datetest.jar

\SilverStream35\bin\silvercmd deployjsp -f date\datejsp.xml -o localhost myDatabase datetest.jar

JSP runtime considerations   Top of page

Each JSP JAR file that you upload to SilverStream functions as a complete, standalone application. The servlet context for any JSP page (or servlet) within the JAR is the JAR itself. Therefore, a JSP page or servlet cannot forward to (or include) a JSP page or servlet that resides in a different JAR, since the JAR defines the boundaries of the application. In addition, a JSP page cannot forward to (or include) a SilverStream dynamic page.

How URLs are processed   Top of page

When a Web client or SilverStream object requests a resource in a JSP JAR, the SilverStream Server breaks the request URL down into several components:

The following example shows the components of the URL:


In this example, the context path is /db/path/to/jar, the servlet path is /mypkg/foo.jsp, and the pathinfo is /pathinfo/for/jsp.

Dispatching requests within a JAR   Top of page

A JSP page or servlet can forward to (or include) any other JSP page or servlet that resides in the same JAR. The target URL can specify a .jsp or .class extension, or have no extension at all.

If you use the <jsp:forward> or <jsp:include> action, the target URL can be context-relative or page-relative. A context-relative URL begins with a slash (/) and is interpreted relative to the JAR. A page-relative URL does not begin with a slash and is interpreted relative to the current page.

If you use the getRequestDispatcher() method of the ServletContext object to specify the target URL, the URL is context-relative. It must begin with a slash and is interpreted relative to the JAR. Suppose the complete URL for a JSP page is http://localhost/myDatabase/jsptests/jspurl1/mypackage/test.jsp, and the URL you give to the JAR is jsptests/jspurl1. In this case, you can forward a request to the page by embedding the following code in a servlet (or other JSP page) in the same JAR:

  ServletConfig sconfig = getServletConfig(); 
ServletContext sc = sconfig.getServletContext();
RequestDispatcher rd =
rd.forward(req, res);

In this example, the forward() method call passes the implicit request and response objects as arguments.

Dispatching requests to a JAR from a page or business object   Top of page

Although each JSP JAR defines a standalone application, SilverStream will allow you to forward to a JSP page (or servlet) in a JAR from a SilverStream dynamic page or business object running on the same server. In this case, the URL you specify is server-relative. The URL must begin with a slash followed by the name of the target database. For example, in the pageRequestBegin event for a page, you could add this code to redirect the request to a JSP page:

  ServletConfig sconfig = getServletConfig(); 
ServletContext sc = sconfig.getServletContext();
RequestDispatcher rd = sc.getRequestDispatcher
rd.forward(req, res);

Copyright © 2000, SilverStream Software, Inc. All rights reserved.