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 IBM® Lotus® Domino(TM) server and IBM® Lotus® Domino(TM) Designer installation kits. It is identical to the file supplied in Sun's JSDK.

Sun periodically updates the JDK and JSDK. Lotus Domino Designer Release 6 supports JDK 1.3 and JSDK 2.0. Domino quarterly maintenance releases (QMRs) often incorporate Sun's upgrades, so you should check the QMR Release Notes to verify the supported JDK and JSDK versions.

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:

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

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