iPlanet Web Server, Enterprise Edition Programmer's Guide to Servlets: Chapter 4 Using JavaServer Pages

Previous Contents Index DocHome Next

iPlanet Web Server, Enterprise Edition Programmer's Guide to Servlets

Chapter 4 Using JavaServer Pages

This chapter discusses how to enable and configure JavaServer Pages (JSPs) in iPlanet Web Server 6.0. The sections in this chapter are:

What Does the Server Need to Run JSP?

Configuring JRE/JDK Paths

Using the User Interface

Enabling JSPs

Making JSPs Available to Clients

Deleting Cache Version Files

The JSP Command-Line Compiler

JSP Tag Libraries and Standard Portable Tags

What Does the Server Need to Run JSP?

iPlanet Web Server 6.0 includes the Java Runtime Environment (JRE) but not the Java Development Kit (JDK) due to licensing restrictions. The server can run servlets and precompiled JSPs using the JRE, but you need the JDK to develop new JSPs or to deploy uncompiled JSPs. For information about precompiling JSPs, see "The JSP Command-Line Compiler."
iPlanet Web Server 6.0 requires you to use the following recommended versions of JRE/JDK or later versions, with different platforms requiring different versions, as summarized in Table 4-1.

Table 4-1    Supported JRE/JDK Versions by Platform

Platform

JRE/JDK/JVM/JIT Version

Comments

Sun Solaris 2.6, 2.8

Solaris VM (build Solaris_JDK_1.2.2_07, native threads, sunwjit)

Comment out -Xrs flag in jvm12.conf to generate stack traces. For more information, see "Generating a Stack Trace for Debugging."
For JVMPI based profiling (such as hprof) or debugging (say attach Solaris dbx) purposes, use the reference implementation downloadable from:
http://java.sun.com/products/jdk/1.2/jre/

Windows NT 4.0

Java version 1.2.2 Classic VM (build JDK-1.2.2_007, native threads, symcjit)

HPUX

Java version 1.2.2.07 Classic VM (build 1.2.2.07-00/12/08-PA_RISC1.1, native threads, HP)

iPlanet also bundles a variant HotSpot VM (1.0.1fcs, mixed mode, PA2.0 build 1.2.2.07-00/12/08-PA_RISC2.0). This VM is not enabled. For further details on using this version, see:
http://www.unix.hp.com/java/infolibrary/prog_guide/java2/hotspot.html

AIX

Java version 1.2.2 Classic VM (J2RE 1.2.2 IBM build ca122-20001206 (JIT enabled: jitc))

Compaq Tru64

Java version 1.2.2-8 Classic VM (build J2SDK.v.1.2.2:10/31/2000-18:00, native threads, jit_122)

The Compaq version of iPlanet Web Server is available from Compaq.

RedHat Linux 6.2

Java version 1.2.2 Classic VM (build Linux_JDK_1.2.2_FCS, native threads, sunwjit)

This version of the JVM is from blackdown.org.

Check the iPlanet Web Server Installation and Migration Guide and the latest release notes for updates on required JDK versions.
JDK 1.2 (and other JDK versions) are available from Sun Microsystems at:
http://java.sun.com/products/jdk/1.2/
You can specify the path to the JDK in either of the following ways:

You can specify the path during the server installation process.

When you install iPlanet Web Server 6.0, one of the dialog boxes in the installation process asks if you want to use a custom Java Development Kit (JDK), and if so, you can specify the path to it.

You can specify it after the server is installed.

To specify the path to the JDK, switch to the Web Server Administration Server, select the Global Settings tab, and use the Configure JRE/JDK Paths page, as discussed in the section "Configuring JRE/JDK Paths."

Whether you specify the path to the JDK during installation or later, the path is the directory in which you installed the JDK.

Configuring JRE/JDK Paths

When you install iPlanet Web Server 6.0, you can choose to install the Java Runtime Environment (JRE) that is shipped with the server, or you can specify a path to your own JRE or the Java Development Kit (JDK).
The server can run servlets using the JRE, but it needs the JDK to run JSPs that are not precompiled. The JDK is not bundled with the iPlanet Web Server, but you can download it for free from Sun Microsystems at:
http://java.sun.com/products/jdk/1.2/
iPlanet Web Server 6.0 requires you to use version of the JDK listed in the section "What Does the Server Need to Run JSP?"
Regardless of whether you choose to install the JRE or specify a path to the JDK during installation, you can tell the iPlanet Web Server to switch to using either the JRE or JDK at any time. Switch to the Web Server Administration Server, select the Global Settings tab, and use the Configure JRE/JDK Paths page. You can also change the path to the JDK in this page.
On the Configure JRE/JDK Paths page, supply values for the following fields if you select the JDK radio button:

JDK Path

Enter the path for the JDK. This is the directory where you installed the JDK.

JDK Runtime Libpath

Enter the runtime library path for the JDK.

JDK Runtime Classpath

The class path includes the paths to the directories and jar files needed to run the servlet engine, the servlet examples, and any other paths needed by servlets that you add. You can add new values to the existing class path, but don't delete the existing value since it includes paths that are essential for servlet operation.

Supply values for the following fields if you select the JRE radio button:

JRE Path

Enter the path for the JRE. This is the directory where you installed the JRE.

JRE Runtime Libpath

Enter the runtime library path for the JRE.

Note If you are not sure of the JDK runtime libpath, the JDK runtime classpath, or the JRE runtime libpath, leave these fields blank to tell the server to use the default paths.

It is easiest to use the Configure JRE/JDK Paths page to switch between the JRE and the JDK, but you can also make the change programmatically, as follows:

On Unix:

Edit the file server_root/https-admserv/start-jvm.

If the server is currently using the JRE, this file has a variable NSES_JRE. To enable the server to use a JDK, add the variable NSES_JDK whose value is the JDK directory. You'll also need to change the value of the NSES_JRE variable.

NSES_JDK should point to the installation directory for the JDK, while NSES_JRE should point to the JRE directory in the installation directory for JDK (that is, jdk_dir/jre).

On Windows NT:

Add the path to the Java libraries to the extrapath setting in magnus.conf.

Edit the NSES_JDK and NSES_JRE variables in the registry HKEY_LOCAL_MACHINE/SOFTWARE/Netscape/Enterprise/6.0/. If the server is enabled to use the JDK, both these variables are needed. If the server is to use the JRE, only the NSES_JRE variable should be set.

NSES_JDK should point to the installation directory for the JDK, while NSES_JRE should point to the JRE directory in the installation directory for JDK (that is, jdk_dir/jre).

Caution
Be very careful when editing these Windows NT registry entries. Incorrect values may require you to reinstall iPlanet Web Server.

Note To activate changes to the JRE/JDK paths, you must restart the server from the On/Off option on the Preferences tab in the Server Manager.

Using the User Interface

For information about using the user interface to specify settings for JSPs, see the following topics in the online help.
This page is located in the Web Server Administration Server on the Global Settings tab.

The Configure JRE/JDK Paths Page
These pages are located in the Server Manager on the Java tab.

The Enable/Disable Servlets/JSP Page

The Configure JVM Attributes Page

The Delete Version Files Page
This page is located on the Virtual Servers tab in the Class Manager. (To open the Class Manager, select the Manage Classes page on the Virtual Server Class tab in the Server Manager, select a class from the list, then select the Manage button.)

The Java Web Apps Settings Page

Enabling JSPs

To enable JSPs, follow these steps:

Enable servlets. Select the Java tab in the Server manager, then select the Enable/Disable Servlets/JSP tab. Check the Enable Java Globally box to enable servlets for the entire server. Check the Enable Java for Class box to enable servlets for a single virtual server class. You cannot enable servlets for a class unless Java is globally enabled. By default, Java is globally enabled and enabled for each virtual server class.

Include the jsp-servlet element with enable="true" in the web-apps.xml file. For more information about the web-apps.xml file, see Chapter 2 "Web Applications."

Add tools.jar to the JVM classpath. For more information, see Appendix C "JVM Configuration."

Making JSPs Available to Clients

You can make JSPs accessible to clients in one of these two ways:

Include the JSPs in web applications and deploy those web applications. How to do this is described in Chapter 2 "Web Applications."

Configure the JSPs in the default virtual server. This is provided for backward compatibility with iPlanet Web Server 4.x. How to do this is described in Chapter 8 "Legacy Servlet and JSP Configuration."

Deleting Cache Version Files

The server uses the following directory to cache information for JavaServer Pages (JSP):
server_root/https-server_id/ClassCache/virtual_server_id/webapp_uri/
You can change the location of the JSP class cache using the scratchdir initialization parameter of the jsp-servlet element in the web-apps.xml file. For more information, see "Other JSP Initialization Parameters."
When the server serves a JSP page, it creates a .java and a .class file associated with the JSP and stores them in the JSP class cache under the ClassCache directory.
The cache has a Version file containing a version number that the server uses to determine the structure of the directories and files in the caches. You can clean out the caches by simply deleting the version file.
When the server starts up, if it does not find the version file, it deletes the directory structures for the corresponding caches and re-creates the version file. Next time the server serves a JSP page, it recreates the JSP class cache.
You can delete the version file simply by deleting it from the ClassCache directory as you would normally delete a file, or you can use the Java>Delete Version Files page in the Server Manager to delete it. After deleting one or both version files, be sure to restart the iPlanet Web Server to force it to clean up the appropriate caches and to recreate the version file before the server serves any JSPs.

The JSP Command-Line Compiler

You can precompile JSPs for faster performance; this is recommended for production servers. A command-line JSP compiler is included with iPlanet Web Server. The JSP compiler is located under server_root/bin/https/bin (make sure this directory is in your path). The IWS_SERVER_HOME environment variable must be set to the server_root directory.
The format of the jspc command is as follows:
jspc [options] jsp_files
The jsp_files can be one of the following:

files

One or more JSP files to be compiled.

-webapp dir

A directory containing a web application. All JSPs in the directory and its subdirectories are compiled. You cannot specify a WAR, JAR, or ZIP file.

The options for the jspc command are:

-q

Enables quiet mode (same as -v0). Only fatal error messages are displayed.

-v[level]

Enables verbose mode. The level is optional; the default is 2. Possible level values are:

0 - fatal error messages only

1 - error messages only

2 - error and warning messages only

3 - error, warning, and informational messages

4 - error, warning, informational, and debugging messages

-d dir

Specifies the output directory for the compiled JSPs. Package directories are automatically generated based on the directories containing the uncompiled JSPs. The default top-level directory is the directory from which jspc is invoked.

-dd dir

Specifies the literal output directory for the compiled JSPs. Package directories are not made. The default is the directory from which jspc is invoked.

-p name

Specifies the name of the target package for all specified JSPs, overriding the default package generation performed by the -d option.

-c name

Specifies the target class name of the first JSP compiled. Subsequent JSPs are unaffected.

-mapped

Generates separate write calls for each HTML line and comments that describe the location of each line in the JSP file. By default, all adjacent write calls are combined and no location comments are generated.

-die[code]

Causes the JVM to exit and generates an error return code if a fatal error occurs. If the code is absent or unparsable it defaults to 1.

-uribase dir

Specifies the URI directory to which compilations are relative. Applies only to explicitly declared JSP files.
This is the location of each JSP file relative to the uriroot. If this cannot be determined, the default is /.

-uriroot dir

Specifies the root directory against which URI files are resolved. Applies only to explicitly declared JSP files.
If this option is not specified, all parent directories of the first JSP page are searched for a WEB-INF subdirectory. The closest directory to the JSP page that has one is used.
If none of the JSP's parent directories have a WEB-INF subdirectory, the directory from which jspc is invoked is used.

-webinc file

Creates partial servlet mappings for the -webapp option, which can be pasted into a web.xml file.

-webxml file

Creates an entire web.xml file for the -webapp option.

-ieplugin class_id

Specifies the Java plugin COM class ID for Internet Explorer. Used by the <jsp:plugin> tags.

-genclass

Generates class files in addition to Java files. The JDK tools.jar file must be in the JVM classpath.

The -webinc and -webxml options may not be useful for JSPs in iPlanet Web Server.
For example, this command (all on one line) compiles the JSPs in the HelloWorld web application:
jspc -d dir -genclass -webapp server_root/plugins/servlets/examples/web-apps/HelloWorld
The compiled JSPs are written under dir/_jsps/. You can then put these class files in a .JAR file.
Additional documentation for the JSP compiler is on the Jakarta site:
http://jakarta.apache.org/
Jasper and iPlanet Web Server 6.0 are not tightly integrated, so you might need to edit the JVM Classpath (in the Configure JVM Attributes page of the Server Manager or in the jvm12.conf file) when deploying JSPs using tag libraries, beans, and so on. For more information about JVM settings, see Appendix C "JVM Configuration."

Package Names Generated by the JSP Compiler

When a JSP is compiled, a package is created for it. The package name starts with _jsps and has each pathname component of the JSP prefixed with an underscore. For example, the generated package name for /myjsps/hello.jsp is _jsps._myjsps.
Because of the implicit package name associated with a generated servlet, you need an explicit import directive when you use a bean in a JSP, especially if the bean doesn't have a package name. For example:
<%@page import="MyBean" %>
<jsp:useBean id="myBean" class="MyBean" />

Specifying that JSPs Are Precompiled

The jsp-servlet element in the web-apps.xml file allows you to tell iPlanet Web Server that JSPs in a virtual server are precompiled. Include the following tags inside a vs element:
<jsp-servlet enable="true">
   <init-param>
      <param-name>use-precompiled</param-name>
      <param-value>true</param-value>
   </init-param>
</jsp-servlet>
For more information about the web-apps.xml file, see Chapter 2 "Web Applications."
You do not need to install the JDK to run precompiled JSPs. However, you need the JDK to develop new JSPs. For information about installing the JDK, see "What Does the Server Need to Run JSP?"

Other JSP Initialization Parameters

You can include the following initialization parameters under the jsp-servlet element in your web-apps.xml file. The JSP compiler uses the default values for parameters that are not included in the file.

keepgenerated

If set to true (the default), keeps the generated Java files. If false, deletes the Java files.

largeFile

If set to true, static HTML is stored is a separate data file. This is useful when a JSP is very large. The default is false.

scratchdir

The working directory created for storing all the generated code. If this parameter is not specified, the default location is server_root/https-server_id/ClassCache/virtual_server_id/webapp_uri/.

mappedfile

If set to true, generates separate write calls for each HTML line and comments that describe the location of each line in the JSP file. By default, all adjacent write calls are combined and no location comments are generated.

ieClassId

The Java plugin COM class ID for Internet Explorer. Used by the <jsp:plugin> tags.

use-precompiled

If set to true, specifies that the JSPs in a virtual server are precompiled and do not need to be compiled at runtime. The default is false.
If set to true, changes to JSPs are not automatically reloaded.
You can compile JSPs using the command line JSP compiler, put the classes in a JAR file, and put the JAR file in the WEB_INF/lib directory of your web application.

JSP Tag Libraries and Standard Portable Tags

iPlanet Web Server supports tag libraries and standard portable tags. For more information about tag libraries, see the JSP 1.1 specification at:
http://java.sun.com/products/jsp/download.html

Platform	JRE/JDK/JVM/JIT Version	Comments
Sun Solaris 2.6, 2.8	Solaris VM (build Solaris_JDK_1.2.2_07, native threads, sunwjit)	Comment out -Xrs flag in jvm12.conf to generate stack traces. For more information, see "Generating a Stack Trace for Debugging." For JVMPI based profiling (such as hprof) or debugging (say attach Solaris dbx) purposes, use the reference implementation downloadable from: http://java.sun.com/products/jdk/1.2/jre/
Windows NT 4.0	Java version 1.2.2 Classic VM (build JDK-1.2.2_007, native threads, symcjit)
HPUX	Java version 1.2.2.07 Classic VM (build 1.2.2.07-00/12/08-PA_RISC1.1, native threads, HP)	iPlanet also bundles a variant HotSpot VM (1.0.1fcs, mixed mode, PA2.0 build 1.2.2.07-00/12/08-PA_RISC2.0). This VM is not enabled. For further details on using this version, see: http://www.unix.hp.com/java/infolibrary/prog_guide/java2/hotspot.html
AIX	Java version 1.2.2 Classic VM (J2RE 1.2.2 IBM build ca122-20001206 (JIT enabled: jitc))
Compaq Tru64	Java version 1.2.2-8 Classic VM (build J2SDK.v.1.2.2:10/31/2000-18:00, native threads, jit_122)	The Compaq version of iPlanet Web Server is available from Compaq.
RedHat Linux 6.2	Java version 1.2.2 Classic VM (build Linux_JDK_1.2.2_FCS, native threads, sunwjit)	This version of the JVM is from blackdown.org.

Previous Contents Index DocHome Next
Copyright © 2001 Sun Microsystems, Inc. Some preexisting portions Copyright © 2001 Netscape Communications Corp. All rights reserved.

Last Updated May 02, 2001

files	One or more JSP files to be compiled.
-webapp dir	A directory containing a web application. All JSPs in the directory and its subdirectories are compiled. You cannot specify a WAR, JAR, or ZIP file.

-q	Enables quiet mode (same as -v0). Only fatal error messages are displayed.
-v[level]	Enables verbose mode. The level is optional; the default is 2. Possible level values are: 0 - fatal error messages only 1 - error messages only 2 - error and warning messages only 3 - error, warning, and informational messages 4 - error, warning, informational, and debugging messages
-d dir	Specifies the output directory for the compiled JSPs. Package directories are automatically generated based on the directories containing the uncompiled JSPs. The default top-level directory is the directory from which jspc is invoked.
-dd dir	Specifies the literal output directory for the compiled JSPs. Package directories are not made. The default is the directory from which jspc is invoked.
-p name	Specifies the name of the target package for all specified JSPs, overriding the default package generation performed by the -d option.
-c name	Specifies the target class name of the first JSP compiled. Subsequent JSPs are unaffected.
-mapped	Generates separate write calls for each HTML line and comments that describe the location of each line in the JSP file. By default, all adjacent write calls are combined and no location comments are generated.
-die[code]	Causes the JVM to exit and generates an error return code if a fatal error occurs. If the code is absent or unparsable it defaults to 1.
-uribase dir	Specifies the URI directory to which compilations are relative. Applies only to explicitly declared JSP files. This is the location of each JSP file relative to the uriroot. If this cannot be determined, the default is /.
-uriroot dir	Specifies the root directory against which URI files are resolved. Applies only to explicitly declared JSP files. If this option is not specified, all parent directories of the first JSP page are searched for a WEB-INF subdirectory. The closest directory to the JSP page that has one is used. If none of the JSP's parent directories have a WEB-INF subdirectory, the directory from which jspc is invoked is used.
-webinc file	Creates partial servlet mappings for the -webapp option, which can be pasted into a web.xml file.
-webxml file	Creates an entire web.xml file for the -webapp option.
-ieplugin class_id	Specifies the Java plugin COM class ID for Internet Explorer. Used by the <jsp:plugin> tags.
-genclass	Generates class files in addition to Java files. The JDK tools.jar file must be in the JVM classpath.

keepgenerated	If set to true (the default), keeps the generated Java files. If false, deletes the Java files.
largeFile	If set to true, static HTML is stored is a separate data file. This is useful when a JSP is very large. The default is false.
scratchdir	The working directory created for storing all the generated code. If this parameter is not specified, the default location is server_root/https-server_id/ClassCache/virtual_server_id/webapp_uri/.
mappedfile	If set to true, generates separate write calls for each HTML line and comments that describe the location of each line in the JSP file. By default, all adjacent write calls are combined and no location comments are generated.
ieClassId	The Java plugin COM class ID for Internet Explorer. Used by the <jsp:plugin> tags.
use-precompiled	If set to true, specifies that the JSPs in a virtual server are precompiled and do not need to be compiled at runtime. The default is false. If set to true, changes to JSPs are not automatically reloaded. You can compile JSPs using the command line JSP compiler, put the classes in a JAR file, and put the JAR file in the WEB_INF/lib directory of your web application.