This document describes how to configure servlets. The conventions used are the same as those defined in Sections 10 & 13 of the Servlet 2.2 Specification ("Mapping Requests to Servlets" & "Deployment Descriptor").

The server looks for a configuration file specified by the servlet.propsFile property. (In the Servlet properties section of the server configuration file.)

It should be stated first that there is only one servlet context, and that all the servlets defined here are within this scope. This means two things. First, that each servlet shares the same context initialization parameters and attributes, and second, that each servlet is known to all others via a named request dispatcher.

There are five subsections:

• Specifying a Mapping
• Servlet Code
• Initialization Parameters
• Servlet Creation
• Configuring the Default Servlet

Specifying a Mapping

Specifying a mapping is as simple as declaring:

<servlet name>.mapping=<path>

where <path> is the URL path used to access the servlet and <servlet name> is an internal pointer to the servlet object. The name can be anything you like, and does not have to match the servlet's classname. Note that servlets can be accessed by their name from a "named request dispatcher".

All the rules for finding a particular servlet based on the requested URI follow those outlined in Section 10 "Mapping Requests to Servlets" in the specification. Additionally, there is a default servlet provided for those paths that do not map to any servlet.

All servlets must have a mapping, even if it is blank. Those that don't are ignored by the servlet container. Blank mappings make the servlet only accessible to a RequestDispatcher, from inside another servlet.

For example, say you want to access MyUsefulServlet via "http://device_address/servlet/useful". The proper mapping would be:

MyUsefulServlet.mapping=/servlet/useful

[Top]

Servlet Code

Specify the classname for a servlet with this line:

<servlet name>.class=<classname>

where <classname> is the full classname of a class that implements the javax.servlet.Servlet interface. (Note that by subclassing javax.servlet.http.HttpServlet, you are still meeting this condition.)

It is possible for more than one servlet to share the same class. If the same class is being used by more than one servlet, then a new instance will be created for each.

For example, the class for MyUsefulServlet may be:

MyUsefulServlet.class=com.something.servlet.TaskServlet

Aliases

There is a second way to specify that a servlet uses the same class as another. Using the .aliasFor tag specifies that the servlet share the same instance of the class used by the aliased servlet.

The syntax for this property is:

<servlet name>.aliasFor=<aliased servlet name>

where <aliased servlet name> is the servlet whose class instance is shared by <servlet name>.

[Top]

Initialization Parameters

Use the .initParams tag to specify any initialization parameters for the servlet. Each parameter is of the form <name>=<value>, and separated by commas:

<servlet name>.initParams=<name1>=<value1>,<name2>=<value2>,...

For example:

MyUsefulServlet.initParams=color=blue,rotate=left

These parameters are accessed in the usual manner from a servlet's ServletConfig object. Please consult the servlet documentation for more details.

[Top]

Servlet Creation

Servlets are normally loaded and initialized when they are first used. To load and initialize a servlet when the server starts, however, simply specify a value of true for the .loadOnStartup tag:

<servlet name>.loadOnStartup=true

Loading a servlet on server startup is useful when certain tasks need to be executed at this time. For example, perhaps a PPP connection over a modem needs to be established to connect the device to the network. Or, perhaps a servlet takes a while to initialize; it may be best to load it when the server starts to avoid any delays when accessing it for the first time.

[Top]

Configuring the Default Servlet

The "default servlet" is the servlet that gets called when no other servlet can be found that matches the requested resource. For example, if no servlet mapping has been specified for /my/requested/resource, then a request for this is passed to the default servlet.

The default servlet that is included in Tynamo™ has one configuration option that allows directory listings to be viewed. In order to set this option, the servlet must be included in the servlet properties file like this:

default.mapping=/
default.class=com.qindesign.servlet.DefaultServlet
default.initParams=canBrowseDirs=true
default.loadOnStartup=true

A few notes of explanation are worthwhile:

• The name of the servlet is "default" in the above configuration, but can be anything you like. The servlet container knows this is the default servlet because of a mapping value of '/', not because of the name.
• The directory browsing option is configured with the "canBrowseDirs" init. parameter.
• The "loadOnStartup" option is not required, and will default to a value of false. It is often the case that a web server will be used at least once for loading a file (eg. HTML), so loading this servlet on startup will speed up the first access.
• It is possible to use another class for the default servlet, but it may not recognize the same configuration options.

canBrowseDirs

The default is false.

[Top]