| Previous Contents Index DocHome Next |
| iPlanet Web Server, Enterprise Edition Programmer's Guide to Servlets |
Chapter 8 Legacy Servlet and JSP Configuration
This chapter describes legacy configuration procedures and files, which are provided for backward compatibility with iPlanet Web Server 4.x, in these sections:
The Default Virtual Server
Making JSPs Available to Clients
Configuring Servlets in the Default Virtual Server
Maximizing Legacy Servlet Performance
Note Legacy servlets and JSPs, as described in this chapter, are deprecated. Creating and deploying web applications as described in Chapter 2 "Web Applications," is recommended.
The Default Virtual Server
The default virtual server is the only virtual server in which legacy applications can be run. When you first install iPlanet Web Server, the default virtual server is the only virtual server that exists. For more information about how the default virtual server is defined, see Chapter 8, "Virtual Server Configuration Files," in the NSAPI Programmer's Guide for iPlanet Web Server.
Enabling Servlets and JSP
To enable and disable servlets and JSPs, use the Java>Enable/Disable Servlets/JSP page in the Server Manager interface.By default, regardless of whether servlets are enabled or disabled, the file obj.conf contains objects with names such as servlet, jsp, and ServletByExt. Do not delete these objects. If you delete them, you can no longer activate servlets through the Server Manager.
Making JSPs Available to Clients
No special steps are needed to make JSP pages available to clients other than making sure that servlets and JSP are enabled on the iPlanet Web Server. So long as JSP is enabled, the iPlanet Web Server treats all files with a .jsp extension as JSPs. (Do not put JSP files in a registered servlet directory, since the iPlanet Web Server expects all files in a registered servlet directory to be servlets.)
Configuring Servlets in the Default Virtual Server
There are three ways to make a servlet accessible to clients in the default virtual server. The second two ways are provided for backward compatibility with iPlanet Web Server 4.x.
Include the servlets in web applications and deploy those web applications, as with any other virtual server. How to do this is described in Chapter 2 "Web Applications." This is new in iPlanet Web Server 6.0.
In detail, to serve servlets in the default virtual server as in iPlanet Web Server 4.x, do the following steps:Put the servlet class file in one of the directories that has been registered with the iPlanet Web 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."
Configuring Global Servlet Attributes
Registering Servlet Directories
Registering Individual Servlets if Needed
Specifying Servlet Virtual Paths if Desired
Specifying Servlet Contexts if Desired
Configuring Global Servlet Attributes
You can specify the following optional servlet attributes:
Startup Servlets -- servlets to be loaded when the iPlanet Web Server starts up.
You can set these attributes interactively in the Legacy Servlets>Configure Global Servlet Attributes page in the Server Manager interface. Alternatively, you can edit the configuration files servlets.properties and contexts.properties in the server's config directory.Session Manager -- the session manager for servlets. For more information about the session manager, see Chapter 6 "Session Managers."
Session Manager Args -- the session manager arguments for the servlet engine. For more information about the session manager, see Chapter 6 "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 seconds.
Registering Servlet Directories
One of the ways to make a servlet accessible to clients is to put it into a directory that is registered with the iPlanet Web 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.You can register any number of servlet directories for iPlanet Web Server. Initially, iPlanet Web Server has a single servlet directory, which is server_root/docs/servlet/.
For example, if the SimpleServlet.class servlet is in the servlet subdirectory of the server's document root directory (the default servlet directory), you can invoke the servlet by pointing the web browser to:
http://your_server/servlet/SimpleServlet
iPlanet Web Server expects all files in a registered servlet directory to be servlets. The server treats any files in that directory that have the .class extension as servlets. The iPlanet Web 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/january/products/servlets/.
To register servlet directories and to specify their URL prefixes, use the Legacy Servlets>Servlet Directory page in the Server Manager 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="/products" dir="d:/netscape/server4/docs/january/products/servlets/" name="ServletByExt" You can invoke a servlet in a subdirectory of a registered servlet directory if you include a package directive in the servlet code that corresponds to the path from the registered servlet directory. For example, suppose the servlet is in the following location, and that server_root/docs/servlet/ is a registered servlet directory:
server_root/docs/servlet/HelloWorld/HelloWorldServlet.class
Include the following package directive as the first line in the Java source file:
You can then invoke the servlet by pointing the web browser to:
http://your_server/servlet/HelloWorld.HelloWorldServlet
For information about reloading packaged servlets, see "isModifiedCheckAggressive."
Registering Individual Servlets
The iPlanet Web Server treats any file in a registered servlet directory as a servlet. There is no need to register individual servlets that reside in these directories unless any of the following criteria apply:
The servlet takes input parameters that are not passed through the request URL.
If any of these conditions is true, register the individual servlet by using the Legacy Servlets>Configure Servlet Attributes page in the Server Manager interface. Alternatively, you can edit the file servlets.properties to add an entry for the servlet.You want to set up additional virtual URLs for the servlet.
Your servlets are packaged or in a .jar file. The server does not search .class or .jar files for packaged servlets.
When registering an individual servlet, specify the following attributes:
Servlet Name -- The iPlanet Web 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.)
The following code shows an example of the configuration information for the same servlet in servlets.properties: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. 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.)
Servlet Args -- a comma delimited list of additional arguments for the servlet if required.
- If the servlet classpath is not a registered servlet directory, you must additionally provide a servlet virtual path for it (as discussed in "Specifying Servlet Virtual Paths") to make the servlet accessible to clients.
- iPlanet Web Server supports the specification of multiple directories, jars, zips, and URLs in the servlet classpath.
Note that you can specify multiple values as the servlet classpath if needed.
Specifying Servlet Virtual Paths
If you register a servlet individually instead of putting it in a servlet directory, you must define a servlet virtual path for it. For example, you could specify that the URLhttp://poppy.my_domain.com/plans/plan1
invokes the servlet defined in the directory
server_root/docs/plans/releaseA/planP2Version1A.class
You can set up servlet virtual paths for servlets that reside anywhere in the file system, in or out of a registered servlet directory.
To specify a servlet virtual path, use the Legacy 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.
Before using a servlet virtual path, a servlet identifier (or servlet name) must be added for the servlet in the Legacy Servlets>Configure Servlet Attributes page of the interface (or in the servlets.properties configuration file).
Virtual Servlet Path Example
This example shows how to specify that the logical URLhttp://poppy.my_domain.com/plans/plan1
invokes the servlet defined in
server_root/docs/plans/releaseA/planP2Version1A.class.
Specify the servlet identifier, class file, and class path.
- In the Legacy 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 Classpath 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.)
Specify the virtual path for the servlet.
- Save the changes.
- To make this change programmatically, add the following lines to the configuration file servlets.properties:
servlet.plan1A.classpath=D:/Netscape/server4/docs/servlet/pla ns/releaseA/
servlet.plan1A.code=planP2Version1A
- In the Legacy 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.
- To do this programmatically, add the following line to rules.properties:
- 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.
Specifying Servlet Contexts
Contexts allow multiple servlets to exchange data and access each other's fields. Contexts are useful for defining virtual servers or for code isolation. You define contexts in the servlets.properties and contexts.properties files.
Using the User Interface
For information about using the user interface to specify settings for legacy servlets and 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.These pages are located in the Server Manager on the Legacy Servlets tab.
The Configure Global Servlet Attributes Page
The Configure Servlet Attributes Page
Legacy Configuration Files
This section discusses the purpose and use of the following files:
servlets.properties
All of these files reside in the directory server_id/config.
Note In iPlanet Web Server 6.0, a web-apps.xml file exists for each virtual server, allowing you to configure separate web applications for each virtual server. The servlets.properties, rules.properties, and contexts.properties files apply only to the default virtual server for the server instance; they exist for backward compatibility. Using the web-apps.xml file for all web application configuration is recommended. For more information about the web-apps.xml file, see Chapter 2 "Web Applications."
servlets.properties
The servlets.properties file defines global servlet settings and the list of servlets in the system, for the default virtual server only.An example of a global servlet setting is which servlet to run when the iPlanet Web Server starts up. The servlets.properties file also specifies configuration information for individual servlets. Configuration information includes the class name, the classpath, and any input arguments required by the servlet.
If you want to specify a virtual path translation for a servlet, the servlet must be configured in the servlets.properties file.
You can specify configuration information for servlets either by using the Legacy Servlets>Configure Servlet Attributes page in the Server Manager interface or by editing servlets.properties directly. Whenever you make a change in the Legacy Servlets>Configure Servlet Attributes page in the Server Manager interface, the system automatically updates servlets.properties.
When specifying attributes for a servlet, you specify a name parameter for the servlet. This name does not have to be the name of the class file for the servlet; it is an internal identifier for the servlet. You specify the name of the class file as the value of the code parameter.
Here is a sample servlets.properties file:
# Servlets Properties
# servlets to be loaded at startup
servlets.startup= hello
# the default document root,
# needed so ServletContext.getRealPath will work
servlets.config.docRoot=d:/Netscape/Server4/docs
# tracker servlet
servlet.tracker.code=MyTrackerServlet
servlet.tracker.classpath=d:/Netscape/Server4/docs/servlet
# demo1 servlet
servlet.demo1.code=Demo1Servlet
servlet.demo1.classpath=d:/Netscape/Server4/docs/demos
servlet.demo1.initArgs=a1=0,b1=3456
servlet.demo1.context=context1
rules.properties
The rules.properties file defines servlet virtual path translations, for the default virtual server only. For example, you could set up a mapping so that the URL pointing to /mytest2 invokes the servlet named demo1 in the servlets.properties file. You can specify virtual paths for your servlets either by setting parameters in the Legacy Servlets>Configure Servlet Virtual Path Translation page of the Server Manager interface or by specifying the paths in the rules.properties file.Note that the name associated with the servlet in servlets.properties is used in the file rules.properties -- the class name of the servlet does not show up in rules.properties. For example, the following lines in servlets.properties associate the servlet name demo1 with the servlet class file Demo1Servlet.class in the directory d:/Netscape/Server4/docs/demos.
# in servlets.properties
# demo1 servlet
servlet.demo1.code=Demo1Servlet
servlet.demo1.classpath=d:/Netscape/Server4/docs/demosThe following line in rules.properties defines a servlet virtual path translation such that the URL http://server_id/mytest2 invokes the servlet at d:/Netscape/Server4/docs/demos/Demo1Servlet.class.
Here is an example of rules.properties.
# Servlet rules properties
#
# This file specifies the translation rules for invoking servlets.
# The syntax is:
# <virtual-path>=<servlet-name>
# or
# @regular_expression=<servlet-name> (use double back-slashes)
#
# where <virtual-path> is the virtual path used to invoke the servlet,
# and <servlet-name> is the name of the servlet. Surrounding white space
# is ignored. The ordering of the rules is not important, as the longest
# match will always be used first. Use of regular expression can lead to
# a heavy peformance penalty
#
################################# rules ################################
/mytest1=tracker
/mytest2=demo1
Using Regular Expressions in rules.properties
iPlanet Web Server supports regular expressions in the rules.properties file to run a given servlet when the incoming URL matches with a regular expression. However, the example given in the file header is incorrect:
# Example:
#
# /simple=SimpleServlet\n
# @.*\\.foo=waspThe \\ characters are supposed to escape the (.) extension. The intent is to run the example wasp servlet whenever there is a request for URLs such as /my/xxx.foo. However, iPlanet Web Server replaces / or \ characters with /, subsequently changing the whole semantics. To get around this, specify the regular expression without the / or \ characters:
For another way to direct files of a specific type to a specific servlet, see the description of the servlet-mapping element in the web.xml file, which is described in the Servlet 2.2 API specification:
http://java.sun.com/products/servlet/index.html
For a way to direct files of a specific type to a specific servlet in the obj.conf file, see "Init Directives in magnus.conf."
contexts.properties
The contexts.properties file defines contexts, which allow multiple servlets to exchange data and access each other's fields, for the default virtual server only. Contexts are useful for defining virtual servers or for code isolation. If no contexts are defined, the default global context is used for all servlets.
Note All JSPs belong to the default global context. You cannot define custom contexts for JSPs. However, you can change the properties of the global context to affect JSPs.
If the context for a servlet is not defined, the servlet belongs to the global context. You can use the same servlet in multiple contexts.
Only the name of a context is required. Any other unspecified properties are inherited from the global context. You can also change the properties of the global context. The comments in the contexts.properties file list the default property values of the global context.
Here is an example of contexts.properties.
# @(#)contexts.properties (autogenerated)
#
# Contexts Properties:
#
# context.<context_name>.sessionmgr=session manager (some session managers
# (like MMapSessionManager) can only be instatiated once within the# server
# context.<context_name>.sessionmgr.initArgs=list of (name, value) pairs which
# will represent parameters specific to the session manager
# context.<context_name>.initArgs=list of (name, value) pairs which will be added
# to this context's attributes
# context.<context_name>.respondCookieVersion=(cookie version) tells the server
# whether to respond with specific cookie version
# context.<context_name>.sessionExpireOnClose(true|false) tells the server to
# mark session cookies as directed to expire when the user quits
# the browser
# context.<context_name>.tempDir=path (forward slashes only) - sets up Servlet API
# 2.2 property for the temporary directory
# context.<context_name>.reloadInterval=seconds - time interval within which the
# server checks for jsp and servlet files being modified (global
# context only)
# context.<context_name>.bufferSize=bytes - initial http output stream buffer size
# context.<context_name>.docRoot=path (forward slashes only) - this context
# document root when not specified - web server's document root
# will be used (default)
# context.<context_name>.inputStreamLengthCheck=(true|false) - makes
# ServletInputStream stop reading data when Content-Length bytes
# are read
# context.<context_name>.outputStreamFlushTimer=(seconds|0) - forces the stream
# to flush the data if certain time elapsed since the last flush;
# 0 - ignore it
# context.<context_name>.uri=contex_uri_base - additional URI prefix which
# servces as a context base
# context.<context_name>.authdb=name - authentication database
# context.<context_name>.classpath=name - global classpath for this context
# context.<context_name>.signleClassLoader=(true|false) - tells the servlet
# engine whether to use a single class loader for all servlets in
# the context
# context.<context_name>.serverName=name - server instance name
# context.<context_name>.contentTypeIgnoreFromSSI=(true|false) - ignore
# setContentType when invoked from SSI
# context.<context_name>.parameterEncoding=(utf8,none,auto) - advises the web
# server on how to decode parameters from forms
# context.<context_name>.isModifiedCheckAggressive=(true|false) - determines
# whether to be aggressively checking dependencies for the servlet
# loader to reload modified servlets
#
# <context_name>="global" is reserved for the global context. Every new context
# will inherit initial settings of the global context
#
# Context properties:
# context.global.sessionmgr=com.netscape.server.http.session.SimpleSessionManager
# context.global.sessionmgr.initArgs=
# context.global.initArgs=initial=0
# context.global.respondCookieVersion=0
# context.global.tempDir=/tmp
# context.global.reloadInterval=5
# context.global.bufferSize=4096
# context.global.docRoot=/foo/bar
# context.global.inputStreamLengthCheck=true
# context.global.outputStreamFlushTimer=0
# context.global.uri=/
# context.global.authdb=default
# context.global.classpath=
# context.global.singleClassLoader=false
# context.global.contentTypeIgnoreFromSSI=true
# context.global.parameterEncoding=utf8
# context.global.isModifiedCheckAggressive=false
#
################################# Contexts #############################
context.global.initArgs=docRoot=C:/iPlanet/Servers
context.context1.name=context1The following sections explain a few of the context properties in more detail.
isModifiedCheckAggressive
When you modify a packaged servlet, the new version is not reloaded automatically unless you have done one of the following:
Set the isModifiedCheckAggressive property to true, for example:
context.global.isModifiedCheckAggressive=true
Used the .class extension when invoking the servlet, for example:
http://your_server/servlet/HelloWorld.HelloWorldServlet.class
parameterEncoding
The context.global.parameterEncoding property allows you determine the character encoding of servlet parameters. It has the following options:
Uses the system default encoding. Set this option if the encoding of the servlet parameter data is the same as the system default encoding.
(Default) Tries to figure out the proper encoding from, in order, 1) the charset if it is set in the Content-Type header, 2) the parameterEncoding attribute (see "ServletRequest.setAttribute"), then 3) a hidden form field, such as j_encoding. Otherwise, the system default encoding is used. Set this option to prevent misinterpretation of non-ASCII characters in servlet parameters.
When this property is set to auto, the server has to convert native characters into a java byte array before transforming them into the requested encoding. Therefore, performance is slightly better for none or a specific encoding.
A specific encoding, such as utf8 or Shift_JIS. Set this option if you know the encoding that servlet parameters use. A complete list is available here:
http://java.sun.com/j2se/1.3/docs/guide/intl/encoding.doc.html
Tries to figure out the proper encoding from the response content type if it is available. Otherwise, the system default encoding is used.
If a servlet uses the ServletRequest.getParameter method to retrieve values in form fields having non-UTF-8 characters, the parameterEncoding property must be set to auto (the default) or responseCT in the contexts.properties file. Otherwise, the values extracted by the getParameter method are zeros or are undefined. For more information see "ServletRequest.getParameter."
The parameterEncoding property setting applies to how a servlet processes parameters after the iPlanet Web Server receives a request. The URI that is sent to the server must consist of only the standard ASCII set, especially if the request method is GET. All other characters must be encoded.
For example, to encode a backslash, you would replace the backslash with a % followed by the hexadecimal number corresponding to the backslash in the ASCII character set, 5c. Therefore, vw\xyz becomes vw%5cxyz. For more information about characters that must be encoded, see "parameter-encoding."
singleClassLoader
By default, the singleClassLoader property is false, which means that each servlet is loaded in a different class loader, even if the servlets share a context. This makes it difficult for two servlets to access each other's static class members. To load all servlets within a context in the same class loader, set the singleClassLoader property to true.Servlet reloading (which occurs when .class or .jsp files are changed) does not work when singleClassLoader=true.
If singleClassLoader=true, RequestDispatcher.forward calls to JSPs do not work unless you add the ClassCache directory to the context.global.classpath line in contexts.properties. For example:
context.global.singleClassLoader=true
context.global.classpath=server_root/https-server_id/ClassCache
Legacy Examples
iPlanet Web Server 6.0 comes with a set of legacy example servlets and JSP files. You can find them at the following location:server_root/plugins/servlets/examples/legacy
The legacy subdirectory contains the following directories:
beans.10 -- Contains example Java Bean files for JSP 1.x.
jsp.10 -- Contains subdirectories that each contain an example for JSP 1.x.
jsp.10/hangman -- Contains a JSP application that was an SSJS application in iPlanet Web Server 4.x. For more information about converting SSJS applications to JSPs, see Appendix B "Converting SSJS Applications."
make -- Contains example makefiles for servlets. These are common makefiles containing rules that are included by all other makefiles.
servlets -- Contains subdirectories that each contain Java source files and makefiles for servlet examples.
tools -- Contains the SDKTools.jar file and other utility files.
Maximizing Legacy Servlet Performance
Consider the following guidelines for improving servlet performance:
If you edit your obj.conf file manually, make sure that the servlet NameTrans (NameTrans fn="NSServletNameTrans" name="servlet") is always the first NameTrans directive.
In the default virtual server, servlets defined individually (via the Configure Servlet Attributes page or rules.properties and servlets.properties) are slightly faster than dynamically loaded servlets (in servlet directories).
- This directive uses a highly optimized URI cache for loaded servlets and returns REQ_PROCEED if the match is found, thus eliminating the need of other NameTrans directives to be executed.
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