How to install servlets

Introduction

After the installation of your Apache JServ servlet engine is complete, your servlet environment is empty and waits for you to add some juicy servlets to execute. In this section you will learn how to install, configure and manage your servlets in this particular servlet environment. This is not intended to be a servlet tutorial or an introduction to servlet techniques even if a deep servlet knowledge is not required in order to install and run your first servlets.

Partitioning your servlet environment

Apache JServ has the ability to divide its execution environment into separate areas, called servlet zones, that act as independent virtual servlet engines. Like virtual hosts for web servers. Before you begin, it's a good thing to design your servlet environment to separate servlets depending on the owner, security privileges, generated load, etc... Nevertheless, most configurations don't need such advanced features and use one simple servlet zone for all of their servlets.

Note: Apache JServ is designed in such a way that servlets are handled by the servlet zones, not by the servlet engine itself. For this reason, at least one servlet zone is needed.

Let us suppose that you need two different servlet zones, one for production and one for development. Simply enough we will call the first zone production and the second development. Let us also suppose that you already had the servlet engine up and running.

Creating the servlet zones

Apache JServ has one main configuration file (usually called jserv.properties) that is used for general information and one configuration file for each servlet zone that is managed by the servlet engine. For this reason, we create two copies of the sample zone configuration file (zone.properties) and, for clarity, we name them production.properties and development.properties.

Then we edit the jserv.properties file and add these two simple directives:

# List of servlet zones Apache JServ manages
zones=production,development

# Configuration file for each servlet zone (one per servlet zone)
production.properties=/servlets/production/production.properties
development.properties=/servlets/development/development.properties

When Apache JServ starts up, it reads the list of servlet zones and looks for the specified zone configuration file. We suggest to use absolute paths for these values since broken behavior with relative paths has been reported.

Configuring your servlet zone

Once the servlet engine knows about your servlet zones, you should tell the servlet zones where to look for its servlets. To do this, we simply add these directives to each of your zone configuration file

# The list of servlet repositories controlled by this servlet zone
repositories=/servlets/production/project1/
repositories=/servlets/production/project2.zip
repositories=/servlets/production/shared_servlets.jar

In this example, the production servlet zone had three servlet repositories: a directory (project1) a zip archive (project2.zip) and a java archive (shared_servlets.jar). These directives tell the servlet zone's classloader where to look for the requested servlet.

Mapping servlets

Since servlets are Java classes and each servlet zone has its own classloader, servlets are accessed, mapped and named using their fully-qualified Java name (like in the classpath) using the package name followed by the class name. Note that these mapping rules do not take into account the location on the file system (like web servers do). In fact servlets located in different servlet repositories but sharing the same package are seen in the same directory by the classloader.

For example, the servlet /servlets/production/project1/Hello.class belonging to the org.dummy.project1 Java package has a fully-qualified Java name of org.apache.project1.Hello, independently its location.

This absolute ordering based on package names alone is used to avoid class name collisions inside servlet zones. Note that if two servlet zones share the same servlet repository, collisions are avoided by the use of different classloaders. These create different instances of the same servlets residing in their own address space and remove any collision problem. Note that the .class extension is always removed to form the fully qualified name to avoid conflicts with packages named class.

Servlet aliases

Even if this class addressing is very successful in ordering and avoiding collisions, it generates big and deep names for servlets. For this reason, alias facilities are provided by the servlet zones to simplify the naming process. To avoid big names, aliased servlets may be used instead of the original fully-qualified ones. Note, however, than these two servlets are now seen as two separate things and calling the two names generates two different instances of the same servlet.

For example, to call the class org.dummy.project1.Hello simply by hello you need to add this line to the proper zone configuration file.

servlet.hello.code=org.dummy.project1.Hello

Startup servlets

During normal operation, a servlet is instantiated and initialized when the first request for that particular servlet is made. This guarantees lower memory consumption even if the first request is a little slower than successive requests. To avoid this overhead, or simply to have your servlet running as soon as the servlet engine is started, you should place your servlet in the startup servlets list for your servlet zone.

To do this, simply add the following line to your servlet zone configuration file:

servlets.startup=org.dummy.project1.Hello

Note that both fully-qualified servlet names (as in this case) or servlet aliases can be used.

Servlet initialization arguments (initArgs)

Like any other forms of executable code (application, applets), servlets need some initialization arguments. Every servlet may have an unlimited number of initArgs, placed in the servlet zone configuration file, or in a separate file. For example, our servlet hello may need some initialization arguments such as message and color. This is done by adding these lines to the servlet zone configuration file

servlet.hello.initArgs=message="Hello world to everyone"
servlet.hello.initArgs=color=red

Global initialization arguments (default initArgs)

Sometimes all the servlets in a servlet zone must share a common initialization argument. To do this, simply use the default servlet name like this

servlets.default.initArgs=path_to_docs=/usr/local/docs/html