# Servlet Zones

## Introduction

> A good understanding of servlet zones and the design ideas behind them are a valuable resource for people willing to take advantage of the full power of Apache JServ. This page introduces you to this strange new world.

## 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

> In future versions of Apache JServ, each servlet zone will have his own security manager and sandbox for servlets, like web browsers do with Java applets. This will allow complete logical separation between servlets executed by the same JVM and would eliminate the need for running multiple virtual machines with different UID/GID.

Copyright (c) 1997-99 The Java Apache Project.
$Id: zones.html,v 1.8 1999/09/19 22:06:02 jonbolt Exp $
All rights reserved.