1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<meta NAME="Author" CONTENT="Stefano Mazzocchi">
<title>Installation and Configuration</title>
</head>
<body BGCOLOR="#FFFFFF">
<p align="center"><a href="http://java.apache.org/" target="_top"><img SRC="../images/java-apache-project.gif" BORDER="0" WIDTH="609"
HEIGHT="100" ALT="The Java Apache Project"></a></p>
<h1 align="center">How to install servlets</h1>
<h3 align="left">Introduction</h3>
<p align="left">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.</p>
<h3 align="left">Partitioning your servlet environment</h3>
<p align="left">Apache JServ has the ability to divide its execution environment into
separate areas, called <em>servlet zones</em>, 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.</p>
<p align="left">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.</p>
<p align="left">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 <em>production</em>
and the second <em>development</em>. Let us also suppose that you already had the servlet
engine up and running.</p>
<h3 align="left">Creating the servlet zones</h3>
<p align="left">Apache JServ has one main configuration file (usually called <em>jserv.properties</em>)
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 (<em>zone.properties</em>) and, for clarity, we name them <em>production.properties</em>
and <em>development.properties</em>.</p>
<p align="left">Then we edit the jserv.properties file and add these two simple
directives:</p>
<blockquote>
<div align="left"><pre># 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</pre>
</div>
</blockquote>
<p align="left">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.</p>
<h3 align="left">Configuring your servlet zone</h3>
<p align="left">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</p>
<blockquote>
<div align="left"><pre># 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</pre>
</div>
</blockquote>
<p align="left">In this example, the <em>production </em>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.</p>
<h3 align="left">Mapping servlets</h3>
<p align="left">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.</p>
<p align="left">For example, the servlet <em>/servlets/production/project1/Hello.class</em>
belonging to the <em>org.dummy.project1</em> Java package has a fully-qualified Java name
of <em>org.apache.project1.Hello</em>, independently its location.</p>
<p align="left">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 <em>.class</em> extension is always removed to
form the fully qualified name to avoid conflicts with packages named <em>class</em>.</p>
<h3 align="left">Servlet aliases</h3>
<p align="left">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.</p>
<p align="left">For example, to call the class <em>org.dummy.project1.Hello</em> simply by
<em>hello</em> you need to add this line to the proper zone configuration file.</p>
<blockquote>
<div align="left"><pre>servlet.hello.code=org.dummy.project1.Hello</pre>
</div>
</blockquote>
<h3 align="left">Startup servlets</h3>
<p align="left">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.</p>
<p align="left">To do this, simply add the following line to your servlet zone
configuration file:</p>
<blockquote>
<div align="left"><pre>servlets.startup=org.dummy.project1.Hello</pre>
</div>
</blockquote>
<p align="left">Note that both fully-qualified servlet names (as in this case) or servlet
aliases can be used.</p>
<h3 align="left">Servlet initialization arguments (initArgs)</h3>
<p align="left">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 <em>hello </em>may need some initialization arguments such as <em>message</em>
and<em> color</em>. This is done by adding these lines to the servlet zone configuration
file</p>
<blockquote>
<div align="left"><pre>servlet.hello.initArgs=message="Hello world to everyone"
servlet.hello.initArgs=color=red</pre>
</div>
</blockquote>
<h3 align="left">Global initialization arguments (default initArgs)</h3>
<p align="left">Sometimes all the servlets in a servlet zone must share a common
initialization argument. To do this, simply use the <em>default</em> servlet name like
this</p>
<blockquote>
<div align="left"><pre>servlets.default.initArgs=path_to_docs=/usr/local/docs/html</pre>
</div>
</blockquote>
<p align="center"><font SIZE="-1">Copyright (c) 1997-99 <a HREF="http://java.apache.org/"
target="_top">The Java Apache Project</a>.<br>
$Id: howto.servlets.html,v 1.5 1999/06/09 05:21:27 jonbolt Exp $<br>
All rights reserved.</font> </p>
</body>
</html>
|
