# Servlets and Jigsaw
Servlet API V2.2

Jigsaw Home / Documentation Overview / Tutorials

Jigsaw is compatible with the Servlet Specification version 2.2. (except .war files)

- What are servlets?
  Short overview of Servlets.

- How do I install a servlet?
  Step by step tutorial. (Automatic installation, servlets.properties, manual installation)

- How can I setup servlet parameters?
  Some servlets require parameters.

- How do I configure a servlet indexer?
  In order to allow automatic setup of servlets.

- How can I setup the servlets properties?
  Log file, sessions...

- How does Jigsaw load local servlet classes?
  The auto-reload feature.

- How can I load remote servlets?
  Servlet can be loaded remotely.

- How can I call a servlet from a SSI command?
  Server Side Include documentation.

- I need to compile Jigsaw with servlets, how should I do?
  If you want to extend Jigsaw.

# What are servlets ?

Servlets are server-side extensions programmed against the Servlet API. This interface is philosophically equivalent to the old CGI interface, but is both more powerful and extremely more efficient. More information is available at jeeves.javasoft.com.

# How do I install a servlet ?

IMPORTANT: Before setting up servlets in Jigsaw, you must get the Servlet Development Kit available at Javasoft and update your CLASSPATH to use those classes (add jsdk.jar in your CLASSPATH).

#### Automatic installation

Since 2.0beta3, by default you just have to put the servlet class file in the `<instdir>/Jigsaw/Jigsaw/WWW/servlet/` directory that is already configured for servlets. For example, if you put SessionServlet.class in `<instdir>/Jigsaw/Jigsaw/WWW/servlet/`, this servlet will be reachable at `http://your-server-host/servlet/SessionServlet`.

Note: with some zip tools, the `servlet` directory may have been removed (because it is empty), please check it and (if it's necessary) create it manually before accessing the `http://your-server-host/servlet/` URL.

#### Using servlets.properties

IMPORTANT: The content of servlets.properties will override any other configuration (including JigAdmin configuration).
Since 2.0.4 and 2.1.1, the 'servlets.properties' file (located in `<INSTDIR>/Jigsaw/Jigsaw/config/`) can be used to configure servlets. A servlet configured in servlet.properties will be located at `http://your-server-host:your-port/servlet/`. The syntax is the usual one and the list of configurable properties is:

- startup (it's a general property)
- code
- codebase
- description
- icon
- initArgs

Example:

    # servlets to be loaded at startup ...
    servlets.startup=JSPServlet

    # snoop servlet
    servlet.snoop.code=SnoopServlet
    servlet.snoop.description=Example: Displays request info
    servlet.snoop.icon=burst.gif

    # simple servlet
    servlet.simpleservlet.code=SimpleServlet
    servlet.simpleservlet.description=Example: Simple servlet
    servlet.simpleservlet.icon=burst.gif

    # remote servlet
    servlet.remoteservlet.codebase=http://ender.inria.fr/classes/
    servlet.remoteservlet.code=RemoteServlet
    servlet.remoteservlet.description=Remote servlet
    servlet.remoteservlet.initArgs=param=value

Note: make sure that http-server.props has the following entry

       org.w3c.jigsaw.startup=org.w3c.jigsaw.servlet.ServletPropertiesReader

#### Manual installation

First of all, you have to choose where you want to place your servlets in your file system; this will usually be a single directory, typically something like servlet under your server's WWW directory. Once you have created the file system directory, create a org.w3c.jigsaw.resources.DirectoryResource with a org.w3c.jigsaw.servlet.ServletDirectoryFrame frame to export it (if the directory has already been indexed, you have to remove the existing org.w3c.jigsaw.frames.HTTPFrame). That frame will act as a context for all the servlets under it (Jigsaw can handle multiple servlet contexts within a single server).

Then, you can setup your servlet manually, or use the servlet indexer (`servlet-indexer`). The servlet indexer will automaticaly create the ServletWrapper and configure it. If you decide to use it, set `servlet-indexer` as the indexer of the DirectoryResource `servlet`.

But you still can do it manually. Put your servlet into the `servlet` directory. Each servlet is managed by a org.w3c.jigsaw.servlet.ServletWrapper, to add a servlet you just have to create a ServletWrapper and in the servlet-class field put the class name of the servlet witch must be in the directory relative to the DirectoryResource or in the CLASSPATH.

Example :

You want to install the DateServlet in the WWW/servlet directory:

1. Create the directory servlet under WWW
2. Start the JigAdmin program and unfold all the nodes down to the Root node.
3. Double click on the servlet node, and Add a org.w3c.jigsaw.servlet.ServletDirectoryFrame to the DirectoryResource (and eventually remove the old HTTPFrame).

4. Put the servlet class (ie DateServlet.class) in WWW/servlet (or in the CLASSPATH).
5. Create a ServletWrapper in the DirectoryResource and call it DateServlet for example.

6. Set the servlet-class field of the ServletWrapper to DateServlet
7. Commit your changes

Now DateServlet is reachable at http://your-server-host/servlet/DateServlet.

# How can I setup servlet parameters?

Some servlets needs parameters at initializing time, so we may need to specify those parameters. Here we describe how to setup the `resultsDir` parameter of the Survey servlet. This servlet needs a directory to write some output, this is the `resultsDir.`In this example we take `/tmp` as the `resultsDir`.

1. Select the servlet wrapper of the SurveyServlet and click on the Edit button (Servlet Parameters).
2. Enter the parameter name in the `Key` field and the parameter value in the `Value` field.
3. Click on add (or hit enter). Then click on Ok.
4. Commit your changes and save your configuration.

# How do I configure a servlet indexer? (Since 2.0 beta3).

Now you can setup a special indexer for servlets: `org.w3c.jigsaw.servlet.ServletIndexer`. This indexer perfoms some servlet specific actions before indexing the class file in a ServletWrapper. It verify that the class file is really a servlet class file, then it put the filename (without the "class" extension) as the identifier and the entire filename as the servlet class. So a class file that is not a servlet class file will NOT be indexed by this indexer but it could be indexed (in a FileResource for example) by one of its super indexer.
See the Indexer Configuration documentation for more details on indexers.

Just add a ServletWrapper called "class" in the extensions node of your ServletIndexer, modify the field you want in the ServletDirectoryFrame (ie: Title, Icon), commit and save your modifications. Now you just have to set your indexer as the indexer of your servlet directory and your servlets will automaticaly be indexed.

# How can I setup the servlets properties?

In the last version of Jigsaw, you have many properties to configure.

1. Servlet log file : You can specify the log file to use for servlets. The default log file is `<instdir>/Jigsaw/Jigsaw/logs/servlets`.
2. Sessions max idle time : Amount of time a session is allowed to go unused before it is invalidated. Value is specified in milliseconds.
3. Max sessions : Max number of sessions in memory, if the number of sessions exceeds this number the sessions with the bigest idle time will be invalidated. This is checked each time a session is added.
4. Sessions check delay : Time interval when Jigsaw checks for sessions that have gone unused long enough to be invalidated. Value is an integer, specifying the interval in milliseconds.
5. Session cookie name : The name of the cookie carrying the session ID.
6. Session cookie path : The path of the cookie carrying the session ID. (optionnal)
7. Session cookie domain : The domain field of the cookie carrying the session ID. (optionnal)
8. Session cookie comment : The comment field of the cookie carrying the session ID. (optionnal)
9. Session cookie maxage : The value of the maximum age of the cookie carrying the session ID. Default value is 86400 seconds (24h).
10. Session cookie secure : The secure field of the cookie carrying the session ID.

# How does Jigsaw load local servlet classes ?

Jigsaw use a local ClassLoader to load servlet classes from the servlet Directory. If a servlet class is modified when Jigsaw is running, the ClassLoader load automatically the new class. It's a very useful feature for servlets developers.

In the two first versions of Jigsaw2.0 (beta1 and beta2) this feature can be disabled because in some case the `auto-reload` feature could create some problems. In those versions there is a `auto-reload` flag in ServletWrapper.

Now this problem has been resolved and we don't need the `auto-reload` flag anymore. But the `auto-reload` feature works only for the servlet classes located in the servlet directory. Servlets in the CLASSPATH are loaded by the system ClassLoader and their modified classes are not reloaded while the server is running.

Note: For very good reasons, when a servlet class is reloaded all sessions are invalidated.

# How can I load remote servlets ?

You can use remote servlets by using a RemoteServletWrapper instead of the ServletWrapper.

Example : Add the remote servlet http://www.servlet.com/RemoteServlet.class to jigsaw.

1. Create the RemoteServletWrapper in the ServletDirectory.
2. Set its "servlet-base" field to http://www.servlet.com/
3. Set its "servlet-class" field to "RemoteServlet" (without .class)
4. Commit changes.

Note : the url http://www.servlet.com/RemoteServlet.class must be a Java compliant class file.

# I need to compile Jigsaw with servlets, how should I do?

NOTE: The default version of Jigsaw has been compiled with servlet support, to use it dowload the JSDK available at Javasoft and update your CLASSPATH to use those classes.

Be sure to have a recent version of the servlet classes. Modify the Makefile in src/classes/org/w3c/jigsaw and add the servlet package at the end of the PACKAGES list, like this:

> `tutorials \`
> `zip \`
> `servlet`

Then, uncomment the line 146 of org/w3c/jigsaw/ssi/commands/DefaultCommandRegistry.java like this:

> `new org.w3c.jigsaw.ssi.servlets.ServletCommand()`

and adds the servlets package in the Makefile of the org.w3c.jigsaw.ssi package, like this:

> `PACKAGES = \`
> `commands\`
> `jdbc \`
> `servlets`

Now, you can recompile jigsaw.