Appendix C   Properties Files


This appendix discusses the purpose and use of the files servlets.properties, rules.properties, and contexts.properties, which reside in the directory server_id/config.

servlets.properties

---

The servlets.properties file defines global servlet settings and the list of servlets in the system.

Examples of global servlet settings are which servlet to run when the iPlanet Web Server starts up, the reload interval for servlets, and so on. 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 Servlets>Configure Servlet Attributes page in the Server Manager interface or by editing servlets.properties directly. Whenever you make a change in the 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 reload interval for dynamically-loaded servlets and JSPs
# (default is 10 seconds)
servlets.config.reloadInterval=5
# the default document root,
# needed so ServletContext.getRealPath will work
servlets.config.docRoot=d:/Netscape/Server4/docs
# the session manager
servlets.sessionmgr=com.netscape.server.http.session.SimpleSessionManager
# 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 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 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/demos

The 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.

/mytest2=demo1

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=wasp

The \\ 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 4.1 replaces / or \ characters with /, subsequently changing the whole semantics. To get around this, specify the regular expression without the / or \ characters:

@.*[.]foo$=wasp

For another way to direct files of a specific type to a specific servlet, see "Directives for Enabling Servlets."

contexts.properties

---

The contexts.properties file defines contexts, which allow multiple servlets to exchange data and access each other's fields. 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	You can use only five hardware virtual servers in the FastTrack edition of iPlanet Web Server.

---

---

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 instantiated 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>.realPathFromRequest=(true|false) tells the server
#            whether to calculate getRealPath based on docRoot of the
#            context or try to go through normal NSAPI steps
# 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>.includeTransparency=(true|false) tells the server whether
#            to try to honor setting headers from the included servlet
# 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>.javaBufferSize=bytes (deprecated)
# 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 to 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
#            services as a context base
# context.<context_name>.host=hostname
# context.<context_name>.ip=ip
# 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_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.realPathFromRequest=false
# context.global.respondCookieVersion=0
# context.global.sessionExpireOnClose=false
# context.global.includeTransparency=true
# context.global.tempDir=/tmp
# context.global.reloadInterval=5
# context.global.javaBufferSize=0
# context.global.bufferSize=4096
# context.global.docRoot=/foo/bar
# context.global.inputStreamLengthCheck=true
# context.global.outputStreamFlushTimer=0
# context.global.uri=/
# context.global.host=
# context.global.ip=
# context.global.authdb=default
# context.global.classpath=
# context.global.singleClassLoader=false
# context.global.contentTypeIgnoreFromSSI=true
# context.global.parameterEncoding=utf8
#
################################# Contexts #############################
context.context1.name=context1

The 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:

utf8	Uses UTF-8 encoding, which includes 7-bit ASCII. Set this option if servlet parameters use only UTF-8 characters.
none	Uses the system default encoding. Set this option if the encoding of the servlet parameter data is the same as the system default encoding.
auto	(Default) Tries to figure out the proper encoding from the charset if it is set in the Content-Type header. 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 utf8 or none.

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) in the contexts.properties file. Otherwise, the values extracted by the getParameter method are zeros or are undefined. For more information see "ServletRequest.getParameter."

sessionExpireOnClose

If you set context.global.sessionExpireOnClose=true, the server does not send the expiration time in the Set-Cookie header for the session cookie. If you set this property to false, the expiration time is sent. Neither setting causes a specific performance impact.

Regardless of whether the server sends the expiration time in the session cookie, you set the actual session expiration time in these ways:

• Set the session manager timeout. For more information about session managers, see Appendix A "Session Managers."

• Use the HttpSession.setMaxInactiveInterval method on the session that you get by calling HttpServletRequest.getSession(false). This is optional, and it overrides the session manager timeout. If there is no session, you can create one by calling getSession(true).

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.