Programmer's Guide to Servlets in Enterprise Server 4.0

Programmer's Guide to Servlets in Enterprise Server 4.0
Table of Contents | Previous | Next | Index

Programmer's Guide to Servlets in Enterprise Server 4.0

Chapter 1. Using Servlets and JavaServerPages

Enterprise Server 4.0 supports servlets and JavaServer Pages (JSP). This chapter gives a brief overview of servlets and JavaServer Pages and discusses how to enable and configure them in Enterprise Server 4.0.

The sections in this chapter are:

Servlets

Java servlets are server-side Java programs that web servers can run to generate content in response to a client request in much the same way as CGI programs do. Servlets can be thought of as applets that run on the server side without a user interface. Servlets are invoked through URL invocation.

Netscape Enterprise Server 4.0 includes support for JavaSoft's Servlet API at the level of the Java Servlet Development Kit (JSDK) 2.1.

To develop servlets, use Sun Microsystems' Java Servlet API. For information about using the Java Servlet API, see the documentation provided by Sun Microsystems at:

http://www.javasoft.com/products/servlet/index.html

Netscape Enterprise Server 4.0 includes all the files necessary for developing Java Servlets. The servlets.jar file is in the ES4.0 installation directory at:

/bin/https/jar

When compiling servlets, make sure the servlets.jar file is accessible to your Java compiler.

JavaServer Pages

Enterprise Server 4.0 supports JavaServer Pages (JSP) to the level of JSP API 0.92 compliance.

A JavaServer Page (JSP) is a page much like an HTML page, that can be viewed in a web browser. However, as well as containing HTML tags, it can include a set of JSP tags (understood by the server) that extend the ability of the web page designer to incorporate dynamic content in a page. These tags provide functionality such as displaying property values using simple conditionals, and are understood by the server's JSP engine.

One of the main benefits of JavaServer Pages is that, like HTML pages, they do not need to be compiled. The web page designer simply writes a page that uses HTML and JSP tags, and puts it on their web server. The web page designer does not need to learn how to define Java classes or use Java compilers.

JSP pages can access full Java functionality in the following ways:

by embedding Java code directly in scriptlets in the page
by accessing Java beans
by using server-side tags that include Java servlets

Both beans and servlets are Java classes that need to be compiled, but they can be defined and compiled by a Java programmer who then publishes the interface to the bean or the servlet. The web page designer can access a pre-compiled bean or servlet from a JSP page without having to do any compiling themselves.

For information about creating JavaServer Pages, see Sun Microsystem's JavaServer Pages 0.92 spec in the build in the manuals/https/servlets/jsp092 subdirectory.

For information about Java Beans, see Sun Microsystem's JavaBeans web page at:

http://www.javasoft.com/beans/index.html

What Does the Server Need to Run Servlets and JSP?

Enterprise Server 4.0 includes the Java Runtime Environment (JRE) but not the Java Development Kit (JDK). The server can run servlets using the JRE, but it needs the JDK to run JSP. If you want to run JSP, you must tell the Enterprise Server to use a custom JDK.

Enterprise Server 4.0+ requires you to use official versions of JDK, with different platforms requiring different versions. For example, Sun Solaris requires JDK1.2 or higher; HP-UX requires JDK 1.1 (C.01.17.01 or any higher 1.1 version); and Windows NT requires a JDK of 1.2.2 or higher. Check the Installation and Migration Guide and the latest release notes for updates on required JDK versions.

NOTE: On Sun Solaris, the JRE included is the JRE 1.2.2 reference implementation from JavaSoft. For performance, it is recommended to use the latest SunSoft production release of JDK, currently 1.2.1_03.

JDK 1.2 (and other JDK versions) are available from Sun Microsystems at:

http://www.javasoft.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 Enterprise Server 4.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, use the "Configure JRE/JDK Paths" page in the Servlets tab of the Server Manager, 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 folder in which you installed the JDK.

Serving Servlets and JSP

Enterprise Server 4.0 includes an appropriate version of the Java runtime environment (JRE) for running servlets. For the server to be able to serve JSP, you must specify a path to a Java Development Kit (JDK) as discussed in the section "What Does the Server Need to Run Servlets and JSP?."

For the server to serve servlets and JSP, servlet activation must be enabled. (See the section "Activating Servlets and JSP" for details.)

When the servlet engine is activated, you can make servlets accessible to clients via one of the following two procedures:

Put the servlet class file in a directory that has been registered with the Enterprise Server as a servlet directory. For more information, see "Registering Servlet Directories."

Define a servlet virtual path for the servlet. In this case, the servlet class can be located anywhere in the file system or even reside on a remote machine. For more information, see "Specifying Servlet Virtual Paths."

No special steps are needed to enable JSP pages other than making sure that JSP is activated on the Enterprise Server. So long as JSP activation is enabled, the Enterprise Server treats all files with a .jsp extension as JavaServer Pages. (Do not put JSP files in a registered servlets directory, since the Enterprise Server expects all files in a registered servlet directory to be servlets.)

In detail, to enable the Netscape Enterprise Server to serve servlets and JSP pages, do the following:

Activating Servlets and JSP. (This is the only step needed to enable JSP.)

Configuring General Servlet Properties

Registering Servlet Directories

Registering Individual Servlets if Needed

Specifying Servlet Virtual Paths if Desired

Configuring JVM if Necessary

Using the Server Manager Interface to Specify Servlet Behavior and Attributes

In the Enterprise Server 4.0 Server Manager interface, you can use the Servlets tab to specify settings for servlets. For information about using the interface for working with servlets, see the following subsections in the "Servlets Tab" section of Appendix F, "The Enterprise Server User Interface" in the "Enterprise Server Administration Guide:"

The Enable/Disable Servlets Page
Configure JRE/JDK Page
The Servlet Directory Page
The Configure Global Attributes for Servlets Page
The Configure Servlet Attributes Page
The Configure Servlet Virtual Path Translation Page
The Configure JVM Attributes Page
The Delete Version Files Page

Activating Servlets and JSP

To enable and disabled servlets and JSP in Enterprise Server 4.0, use the Servlets>Enable/Disable Servlets page in the Server Manager interface.

If servlets are enabled, JSP can be enabled or disabled. However, if you disable servlets, JSP is also automatically disabled. In this case, if you enable servlets later, you will need to re-enable JSP also if desired.

To enable servlets programmatically, add the following lines to obj.conf. These directives first load the shared library containing the servlet engine, which is in NSServletPlugin.dll on Windows NT or NSServletPlugin.so on Unix. Then they initialize the servlet engine.

Init shlib="server_root/bin/https/bin/NSServletPlugin.dll/so"
funcs="NSServletEarlyInit,NSServletLateInit,NSServletNameTrans,NSServletService" shlib_flags="(global|now)" fn="load-modules"

Init EarlyInit="yes" fn="NSServletEarlyInit"

Init LateInit="yes" fn="NSServletLateInit"

In the default object in obj.conf, add the following NameTrans directive:

NameTrans fn="NSServletNameTrans" name="servlet"

By default, regardless of whether servlets are enabled or disabled, the file obj.conf contains additional objects with names such as servlet, jsp, and ServletByExt. Do not delete these objects. If you delete them, you will no longer be able to activate servlets through the Server Manager.

Configuring General Servlet Properties

You can specify the following servlet properties:

Startup Servlets -- servlets to load when the Enterprise Server starts up.

Session Manager -- the session manager for servlets, if applicable. For more information about the session manager, see Appendix A, "Session Managers."
Reload Interval -- the time period that the server waits before re-loading servlets and JSPs if they have changed on the server. The default value is 5.

You can set these attributes interactively in the Servlets>Configure General Servlet Properties page in the Server Manager interface. Alternatively, you can edit the configuration file servlet.properties in the server's config directory.

The following code shows an example of the settings in servlet.properties:

# General properties:
servlets.startup=hello 
servlets.config.reloadInterval=5 
servlets.config.docRoot=C:/Netscape/Server4/docs 
servlets.sessionmgr=com.netscape.server.http.session.SimpleSessionManager

Registering Servlet Directories

One of the ways to make a servlet accessible to clients is to put it into a directory registered with the Enterprise Server as a servlet directory. Servlets in registered servlet directories are dynamically loaded when needed. The server monitors the servlet files and automatically reloads them on the fly as they change.

For example, if the SimpleServlet.class servlet is in the servlet subdirectory of the server's document root directory, you can invoke the servlet by pointing the web browser to:

http://your_server/servlet/SimpleServlet

You can register any number of servlet directories for the Enterprise Server. Initially, the Enterprise Server has a single servlet directory, which is server_root/docs/servlet/ (For example, d:/netscape/server4/docs/servlet.)

The Enterprise Server expects all files in a registered servlet directory to be servlets. The server treats every file, in that directory with a .class extension as a servlet. The Enterprise Server does not correctly serve other files, such as HTML files or JSPs, that reside in that directory.

The server can have multiple servlet directories. You can map servlet directories to virtual directories if desired. For example, you could specify that http://poppy.my_domain.com/products/ invokes servlets in the directory server_root/docs/servlet/january/products/servlets/.

To register servlet directories and to specify their URL prefixes, use the Servlets>Servlet Directory page in the interface.

Alternatively, you can register servlet directories by adding appropriate NameTrans directives to the default object in the file obj.conf, such as:

NameTrans fn="pfx2dir" from="/productss" 
dir="d:/netscape/server4/docs/servlet/january/products/servlets/"
name="ServletByExt"

Registering Individual Servlets

The Enterprise Server treats every file in a registered servlet directory as a servlet. There is no need to register individual servlets that reside in these directories unless either of the following criteria apply:

The servlet takes input parameters that are not passed through the request URL.
You want to set up virtual URLs for the servlet.

If either of these conditions is true, register the individual servlet by using the Servlets>Configure Servlet Attributes page in the Server Manager interface. Alternatively you can edit the file servlet.properties to add an entry for the servlet.

When registering an individual servlet, specify the following attributes:

Servlet Name -- The Enterprise Server uses this value as a servlet identifier to internally identify the servlet. (This identifier is not part of the URL that is used to invoke the servlet, unless by coincidence the identifier is the same as the class code name.)

Servlet Code (class name) -- the name of the class file. You do not need to specify the .class extension.

Servlet Classpath -- This is the absolute pathname or URL to the directory or zip/jar file containing the servlet class. The classpath can point anywhere in the file system. The servlet classpath may contain a directory, a .jar or .zip file, or a URL to a directory.(You cannot specify a URL as a classpath for a zip or jar file.)

If the servlet classpath is not a registered servlet directory, you must additionally provide a servlet virtual path for it to make it accessible to clients (as discussed in"

Specifying Servlet Virtual Paths

Enterprise Server supports the specification of multiple directories, jars, zips, and URLs in the servlet classpath.

Servlet Args -- a comma delimited list of additional arguments for the servlet if required.

For example, in Figure 1.1, the Servlets>Configure Servlet Attributes page of the Server Manager interface shows configuration information for a servlet whose class file buynow1A resides in the directory D:/Netscape/server4/docs/servlet/buy/. (Note that the final / is omitted in the interface.) This servlet is configured under the name BuyNowServlet. It takes additional arguments of arg1=45, arg2=online, arg3="quick shopping".

Figure 1.1 Configuring attributes for an individual servlet

The following code shows an example of the configuration information for the same servlet in servlet.properties:

servlet.BuyNowServlet.classpath=D:/Netscape/server4/docs/servlet/buy
servlet.BuyNowServlet.code=BuyNow1A
servlet.BuyNowServlet.initArgs=arg1=45,arg2=online,arg3="quick shopping"

Note that you can specify multiple values as the servlet classpath if needed.

Specifying Servlet Virtual Paths

One way of making servlets available to clients is to put them in registered servlet directories. Another way is to define servlet virtual paths for individual servlets. For example, you could specify that the URL

http://poppy.my_domain.com/plans/plan1

invokes the servlet defined in the directory

server_root/docs/servlets/plans/releaseA/planP2Version1A.class

You can set up servlet virtual paths for servlets that reside anywhere, be it on a local or remote file system, and be it in or out of a registered servlet directory.

To specify a servlet virtual path, use the Servlets>Configure Servlet Virtual Path Translation page in the Server Manager interface. In this page, specify the virtual path name and the servlet name. You can alternatively manually edit the rules.properties configuration file to add a servlet virtual path. Only servlets for which a virtual path has been set up can use initial arguments (See "GenericServlet.getInitParameter() and getInitParameterNames()" for iinformation about initial arguments.)

Before using a servlet virtual path, a servlet identifier must be added for the servlet in the Servlets>Configure Servlet Attributes page of the interface (or in the servlets.properties configuration file).

Virtual Servlet Path Example

This example discusses how to specify that the logical URL:

http://poppy.my_domain.com/plans/plan1

invokes the servlet defined in

server_root/docs/servlet/plans/releaseA/planP2Version1A.class.

1. Specify the servlet identifier, class file, and class path.

In the Servlets>Configure Servlet Attributes page in the interface, do the following:

in the Servlet Name field, enter an identifier for the servlet, such as plan1A. (Notice that this is not necessarily the same as the class file name).

in the Servlet Code field, enter the name of the class file, which is planP2Version1A. Don't specify any directories. The .class extension is not required.

in the Servlet Class Path field, enter the absolute path name for the directory, jar or zip file where the servlet class file resides, or enter a URL for a directory. In this example, you would enter server_root/docs/servlet/plans/releaseA. (For example: D:/netscape/server4/docs/servlet/plans/releaseA.)

in the Servlet Args field, enter the additional arguments that the servlet needs, if any. (This example does not use extra arguments.)

Figure 1.2 shows the settings in the interface.

Save the changes.

Figure 1.2 Specifying the servlet name, code, and class path

To make this change programmatically, add the following lines to the configuration file servlet.properties:

servlet.plan1A.classpath=D:/Netscape/server4/docs/servlet/plans/releaseA/

servlet.plan1A.code=planP2Version1A

2. Specify the virtual path for the servlet.

In the Servlets>Configure Servlet Virtual Path Translations page, do the following:

In the Virtual Path field, enter the virtual path name. Note that the server name is implied as a prefix, so in this case you would only need to enter /plans/plan1 to specify the virtual path http://poppy.mcom.com/plans/plan1.

In the Servlet field, enter the identifier for the servlet that is invoked by this virtual path. This is the servlet identifier that you specified in the Configure Servlet Attributes page, which in this case is plan1A.

Save the changes.

Figure 1.3 shows the settings in the interface.

Figure 1.3 Adding a virtual path

To do this programmatically, add the following line to rules.properties:

/plans/plan1=plan1A

After this virtual servlet path has been established, if a client sends a request to the server for the URL http://poppy.my_domain.com/plans/plan1, the server sends back the results of invoking the servlet in server_root/docs/servlet/plans/releaseA/plan2PVersion1A.class.

Configuring JRE/JDK Paths

When you install Enterprise Server 4.0, you can choose to install the Java Runtime Environment (JRE) bundled with Netscape Enterprise Server or you can specify a path to the Java Development Kit (JDK).

The server can run servlets using the JRE, but it needs the JDK to run JSP. The JDK is not bundled with the Enterprise Server, but you can download it for free from Sun Microsystems at:

http://www.javasoft.com/products/jdk/1.2/

Enterprise Server 4.0+ requires you to use an official version of JDK1.2 on Solaris and NT. On HP, AIX and IRIX use JDK 1.1.

Regardless of whether you choose to install the JRE or specify a path to the JDK during installation, you can tell the Enterprise Server to switch to using either the JRE or JDK at any time, by using the "Configure JRE/JDK Paths" page in the Servlets tab. You can also change the path to the JDK in this page.

This page has the following fields:

Change JRE or JDK

Select either the JRE or JDK radio button as desired.

Path

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

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. Values are separated by semicolons. 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.

It is easiest to use the Server Manager interface 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-jre.

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.

If you're using JDK 1.2 or greater, 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). For JDK 1.1.x, NSES_JDK and NSES_JRE should both point to the installation directory for the JDK.

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/4.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. If you're using JDK 1.2 or greater, 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). For JDK 1.1.x, NSES_JDK and NSES_JRE should both point to the installation directory for the JDK.

Deleting Version Files

The server uses two directories to cache information for JavaServerPages (JSP) and servlets:

ClassCache

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, in a directory structure under the ClassCache directory.

SessionData

If the server uses the MMapSessionManager session manager, it stores persistent session information in the SessionData directory. (For more information about session managers, see

Appendix A, "Session Managers."

Each 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 files, it deletes the directory structures for the corresponding caches and re-creates the version files. Next time the server serves a JSP page, it recreates the JSP class cache. The next time the server serves a JSP page or servlet while using MMapSessionManager session manager, it recreates the session data cache.

If a future upgrade of the server uses a different format for the caches, the server will check the number in the version file and clean up the caches if the version number is not correct.

You can delete the version files simply by deleting them from the ClassCache or SessionData directories as you would normally delete a file or you can use the Servlets>Delete Version Files page in the Server Manager to delete them. After deleting one or both version files, be sure to restart the Enterprise Server to force it to clean up the appropriate caches and to recreate the version files before the server serves any servlets or JSPs.

Configuring JVM

If necessary, you can configure parameters for JVM either by using the Servlets>Configure JVM Attributes page in the Server Manager interface, or by editing JVM.conf (or JVM11.conf or JVM12.conf, depending on which version of JVM is being used).

The default settings in Enterprise Server for JVM are suitable for running servlets. However, there may be times when you want change the settings. For example, if a servlet or bean file uses a JAR file, add the JAR location to the Classpath variable. To enable the use of a remote profiler, set the OPTITDIR and Profiler variables.

The JVM parameters you can set are:

Option -- You can set any options allowed by the vendor's JVM.
Profiler -- If you are using the Optimizeit! 3.0 profiler from Intuitive Systems, enter the value optimizeit. For more information about this optimizer, see the section Appendix F, "Remote Servlet Profiling."

OPTITDIR -- If you are using the Optimizeit! 3.0 profiler from Intuitive Systems, enter the pathname for the directory where Optimizeit! resides, for example, D:/App/IntuitiveSystems/OptimizeIt30D. For more information about this optimizer, see the section "Appendix F, "Remote Servlet Profiling."."

Minimum Heap Size -- determines the minimum heap size allocated for Java.

Maximum Heap Size -- determines the maximum heap size allocated to Java.

Compiler -- You can specify options to turn on and off JIT (just-in-time compiler). See your JVM documentation for details.

Classpath -- Enter additional classpath values as needed. For example, if a JSP uses a bean that is packaged in a JAR, add the JAR path to the classpath.

The classpath must not include backslashes in directory names. If you use backslashes in the directory path in the interface, the system automatically converts the backslashes to forward slashes. However, if you edit the jmv.conf (or jvm11.conf or jvm12.conf) file, do not use backslashes in directory names.

Enable Class GC -- Specifies whether or not to enable class garbage collection. The default is yes.

Verbose Mode -- Determines whether the JVM logs a commentary on what it is doing, such as loading classes. The commentary appears in the error log.

Enable Debug -- You can enable or disable remote debugging. The default is disabled. For more information about remote debugging, see the section Appendix E, "Remote Servlet Debugging."

Table of Contents | Previous | Next | Index

Last Updated: 08/12/99 12:39:23