Writing the servlet

To write a servlet, you need a Java compiler and the servlet API. You can obtain both from Sun Microsystem's Web site at http://java.sun.com. Download the Java Development Kit (JDK), which includes the compiler and other basic tools, and the Java Servlet Development Kit (JSDK), which includes the servlet API specification, the servlet .JAR file (jsdk.jar), and example servlets. The Sun site also provides links to other servlet resources on the Web.

You can also write servlets using any popular Java development environment. As a convenience, a copy of jsdk.jar is included in the IBMR LotusR Domino(TM) server and IBMR LotusR Domino(TM) Designer installation kits. It is identical to the file supplied in Sun's JSDK.

Note The following changes have been made regarding the location of servlet-related JAR files that will affect where you can find JSDK.JAR for compiling your servlets:

• The old location of the JSDK.JAR was in the notesbinary directory under jvm/lib/ext.
• The new location of the JSDK.JAR is C:\notes\ndext.

Enabling servlet support in Domino

Servlets are loaded and called by the Domino Java Servlet Manager, a part of the HTTP server task. The runtime Java support for servlets is provided by the Domino Java Virtual Machine (JVM). When the HTTP task is started, it can automatically start the servlet manager and load the JVM. The HTTP task will write status messages for these operations to the server console and log file.

The servlet manager is controlled by settings in the Domino Directory Server document. The settings are located on the Internet Protocols - Domino Web Engine tab of the Server document. The settings are as follows:

Setting	Options
Java servlet support	None: (default) The HTTP task does not load the servlet manager or the JVM. Domino Servlet Manager: The HTTP task loads both the JVM and the servlet manager. Third Party Servlet Support: The HTTP task loads the JVM, but not the Domino servlet manager. This allows the use of third-party servlet managers such as the IBM WebSphere Application Server.
Servlet URL path	The path in a URL that signals Domino that the URL refers to a servlet. The default is /servlet.
Class path	A list of one or more paths which the Servlet Manager class loader will search to find servlets and their dependent classes. This setting allows you to add additional paths. You may specify directories, JAR files, and ZIP files. Paths may be absolute or relative to the Domino data directory. The default is domino\servlet. Examples: Relative directory path: domino\servlet Absolute directory path: c:\apps\MyServlets JAR file: c:\javamail\mail.jar ZIP file: domino\servlet\sql.zip
Servlet file extensions	A list of URL file extensions that signal Domino that a URL refers to a servlet. Each extension in the list must be mapped to a single servlet by a directive in the servlets.properties file. The default is no extensions.

The following settings control the Domino Servlet Manager's runtime support of the Java Servlet API HttpSession interface. A servlet that does not use this interface is not affected by these settings.

Note The HttpSession interface support is completely separate from the HTTP session authentication feature in Domino.

Setting	Options
Session state tracking	Enabled: (default) The servlet manager periodically checks the user activity of all HttpSession instances. Sessions that have been idle for a given period of time are automatically terminated. The servlet manager calls the instance's HttpSession.invalidate() method to inform the servlet that the session is being terminated. Disabled: Sessions will not be checked for inactivity.
Idle session timeout	The number of minutes of user inactivity to wait before terminating a session. The default is 30 minutes.
Maximum active sessions	The number of simultaneous active sessions allowed. The default is 1,000 sessions. When this limit is reached, the sessions that have been idle the longest are terminated.
Session persistence	Enabled: When the HTTP task exits, the servlet manager saves session data to a disk file called sessdata.ser in the Domino data directory. The session data will be reloaded when the HTTP task is restarted. Objects that the servlet has bound to sessions will also be saved if the objects implement the java.io.Serializable interface. Disabled: (default) All session data is discarded when the HTTP task exits.

Loading servlet classes with the JVM loader

The Servlet Manager class loader will not load classes that use native code, create custom class loaders, or perform certain other restricted operations. If your servlet requires a class that can't be loaded by the Servlet Manager, you can try loading it with the Domino JVM class loader. The JVM loader is normally responsible for loading classes from the standard Java archives installed with Domino, in particular the java.* and lotus.* packages. You can force a servlet to be loaded by the JVM loader rather than by the Servlet Manager loader by moving the servlet from the Servlet Manager classpath to the JVM classpath. The JVM classpath is specified by the NOTES.INI variable JavaUserClasses.

Tip You can also load classes in the NOTES.INI file when a class your servlet requires conflicts with classes in the Domino-supplied LotusXSL.jar file. If you load and run a servlet and get a "Verify Error" message, try moving the JAR files for the servlet from the Servlet Manager classpath to the JavaUserClasses statement in the NOTES.INI file.

Setting properties for servlets

Special properties for individual servlets can be specified in a text file called servlets.properties located in the Domino data directory. The following properties can be specified:

• Alias
• Initialization arguments
• URL extension mapping
• Load at Servlet Manager startup

servlet(s).<name>.<property>=<value(s)>

Directives are case-sensitive. The servlets.properties file can also contain blank lines and comment lines starting with the "#" character. The servlets.properties file is optional. The default properties for servlets are: no alias, no initialization arguments, no extension mapping, and load servlets on demand.

Servlet aliases

The alias directive has this syntax:

servlet.<alias-name>.code=<class-name>

For example:

servlet.SQLQuery.code=sql.database.query.Servlet

As a security measure, Domino does not allow servlet names containing periods to be used in a servlet URL. This prevents malicious users from trying to load arbitrary Java package classes through the Servlet Manager. If your servlet has a package name, you must assign an alias to it. The above example allows the servlet sql.database.query.Servlet to be invoked by a URL such as http://acme.com/servlet/SQLQuery?month=june. Aliases are also useful for hiding the actual names of servlets from users.

You can assign more than one alias to a servlet. The servlet manager will create a new instance of the servlet on receiving the first URL that refers to each alias. The servlet manager will call the servlet's init() method when a new instance is created. Since the alias name can be used in other directives in the properties file, the instances can be given different properties. For example, you could specify a separate initialization argument directive for each alias. Also, because the servlet classes are only loaded once even if multiple instances are created, the instances of the servlet can share data by using static class variables.

As a security feature, if you give a servlet an alias, the servlet cannot be directly referenced in a URL by its class name. This allows you to hide the actual name of a servlet.

Initialization arguments

You can specify initial data for a servlet in the properties file. The servlet can access the data by using the method ServletConfig.getInitParameter. The initialization directive has this syntax:

servlet.<alias or class name>.initArgs=<name1=value1>,<name2=value2>,...

Multiple arguments can be specified, separated by commas. For example:

servlet.SQLQuery.initArgs=target=db2,user=Domino,cacheSize=30

URL extension mapping

The URL extension mapping directive has this syntax:

servlet.<alias or class name>.extension=<extension> <extension> ...

You can assign more than one extension to a servlet, separating each from the next by a space. All extensions must also be included in the "Servlet file extensions" setting in the Server record. For example, to cause Domino to call the SQLQuery servlet whenever a URL specifies the extension "sql" or "sq," add "sql,sq" to the server setting and add this directive to the properties file:

servlet.SQLQuery.extension=sql sq

This allows a user to invoke the servlet with a URL like this:

http://acme.com/query.sql?month=june

Load on startup

By default, the servlet manager loads a servlet's class files into memory the first time a URL is received that refers to the servlet. However, you can specify that one or more servlets should be loaded immediately when the servlet manager is started. This prevents users from experiencing delays when servlets are first requested from URLs.

The startup directive has this syntax:

servlets.startup=<alias or class> <alias or class> ...

Note that "servlets" is plural and that the servlet names must be separated by spaces.

If you have given a servlet one or more aliases, you can include the aliases in the startup directive. This will cause the servlet manager to load the servlet classes and then create an instance for each alias.

After the servlet manager loads a servlet's classes, they stay in memory until the Domino HTTP task is stopped by the console command "tell http quit" or restarted by the console command "tell http restart." Before unloading a servlet, the servlet manager calls the destroy() method for each instance of the servlet, to give it a chance to clean up resources.

A class that has been loaded by the JVM class loader remains loaded until the HTTP task is stopped. The "tell http restart" command will not unload the class.

Example properties file

Here is an example of a servlets.properties file:

# Properties for the sql servlet
servlet.SQLQuery.code=sql.database.query.Servlet
servlet.SQLQuery.initArgs=cache=30
servlet.SQLQuery.extension=sql
# Properties for the mail servlet
servlet.MailServlet.initArgs=mime=enabled,smime=disabled

# Both servlets should be loaded at startup
servlets.startup=SQLQuery MailServlet
# end of file

Example
See Also

Including Java servlets in Web applications
Comparing agents, servlets, and CGI programs

Glossary