Servlet Zones

Definitions

Entity	Definition	Web server equivalent
Servlet	a single Java class that implements `javax.servlet.Servlet`	file
Servlet repository	a collection of servlets. It may be a directory, or a class archive (zip or jar files)	directory
Servlet zone	a collection of repositories.	virtual host

A servlet zone is the servlet engine equivalent of a web server virtual host in the sense that all servlet repositories contained by the servlet zone share a common logical context. This gives you the power of isolating servlets from one another both logically (belonging to different hosts or people) and, in the future, securely, mapping every servlet zone to a different security sandbox.

Creating a servlet zone

Servlet zones are very easy to create and configure since each zone has a separate configuration file.

The first step is to take the file /conf/zone.properties and add the servlet repositories that contain the servlets for that zone. Simple enough, to do this you just have to add a property that lists all of your servlet repositories and you're done.

# The list of servlet repositories controlled by this servlet zone
# Syntax: repositories=<repository>,<repository>...
repositories=/usr/local/apache/servlets,/usr/local/java/servlets.jar

Note: On NT systems, one should not include a trailing slash at the end of the repositories lines that end with a directory. For example: repositories=/usr/local/apache/servlets vs. repositories=/usr/local/apache/servlets/.

As good practice, rename the file to [zone name].properties (but a specific name is not required) and place it in a directory accessible by Apache JServ. Note that servlet initialization arguments and specific zone configurations (class autoreloading, session timeouts) are all stored in that file. For this reason you may want to make this file accessible to the owner of the servlet zone to allow him/her to configure their servlet zone transparently.

Including a servlet zone

Once you have created your servlet zones, you must tell Apache JServ about them. This is done by adding a few lines to your jserv.properties file.

# List of servlet zones JServ manages
# Syntax: zones=<servlet zone>,<servlet zone>...
zones=bob,alice

# Configuration file for each servlet zone
# Syntax: <zone name>.properties=<full path to configFile>
bob.properties=/home/bob/servlets/servlets.properties
alice.properties=/home/alice/servlets/servlets.properties

At startup, Apache JServ will setup every servlet zone using the specified zone configuration files. For this reason, make sure your Apache JServ has the access privileges at least to read the zone configuration file and its repositories.

Mounting a servlet zone

Now that Apache JServ and its zones are configured, you need to "mount" these servlet zones into your web server file space. This is as easy as adding a configuration line to your web server configuration file. Let's suppose you have Apache JServ running on jserv.yourDomain.com listening on port 9009 handling the zones defined above.

You want to logically separate the two zones by "mounting" them to a particular web server URI like you would do for a disk on a UNIX file system. To do this you use the ApJServMount directive

ApJServMount /bob/servlets ajpv11://jserv.yourDomain.com:9009/bob
ApJServMount /alice/servlets ajpv11://jserv.yourDomain.com:9009/alice

Now, both Bob and his web clients connect to his servlets with the URL http://www.yourDomain.com/bob/servlets and the same is for Alice.

The possibility to mount both local and remote servlet zones (note that jserv.yourDomain.com may reside on another machine as much as different zones may be hosted on different machines) is the real power of Apache JServ and its major difference compared to other servlet engines. In fact, the web server module acts as an "AJP Browser" rather then a glue between a native process and a Java process (like many other servlet engines do)

This allows you to create a full three-tier network environment and gives a web server the power to concentrate on its URI space all its network resources if encapsulated with Apache JServ and with Java servlets. Specific JNI servlets may even be used to web-enable application and resources that were not designed to be network-aware (like fax machines, local databases and even toasters and microwaves ;-)

Future directions