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
Copyright (c) 1997-99 The
Java Apache Project.
$Id: howto.servlets.html,v 1.5 1999/06/09 05:21:27 jonbolt
Exp $
All rights reserved.