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
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
|
<HTML>
<HEAD>
<TITLE>GNU JSP Installation Guide</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<BLOCKQUOTE>
<H2>GNU JSP Installation Guide</H2>
<FONT SIZE="-2">$Id: install.html,v 1.8 1999/10/17 22:16:54 wes Exp $</FONT>
<H3>Prerequisites</H3>
Before you start installing GNUJSP make sure you have the following:
<UL>
<LI>JDK or JRE 1.1 or higher.</LI>
<LI>A java compiler (one is included with the full JDK, but you can specify others).</LI>
<LI>
A web server that supports the servlet API, either directly or
through a servlet engine.
</LI>
<LI>An implementation of the javax.servlet.jsp packages. GNUJSP comes
with a drop-in replacement for the servlet and JSP interfaces,
copyrighted by the Free Software Foundation (in the lib directory of
the distribution), or you can use the implementation included with
Sun's JSWDK 1.0 download; see <A HREF="http://java.sun.com/products/servlet/">http://java.sun.com/products/servlet/</A>. See the specific installation details for more information.
</LI>
</UL>
<H3>Upgrading from 0.9.x</H3>
<P>
If you are upgrading from an older version of GNU JSP, please note
that 90 percent of the code has changed, and that GNU JSP no longer
supports the JSP 0.91 syntax. If you are queasy about making this
change, you can map files with the .jsp10 extension to
org.gjt.jsp.JspServlet and leave your 0.9 mappings intact. This
way you can test out the new spec without compromising your legacy jsp
files. However, it is recommended that you do not mix and match files
for both 0.9 and 1.0 specs if you use session-related features.
</P>
<H3>Support for the JSP Specification</H3>
<P>
GNU JSP supports most features of the JSP 1.0 specification, with the
following exceptions:
</P>
<UL>
<LI>The <code>taglib</code> directive. Taglib is an optional, unspecified feature of JSP 1.0; GNUJSP plans to implement full tag extension support as illustrated by the JSP 1.1 specification, currently in public release.</LI>
<LI>The <code>jsp:plugin</code> directive</LI>
</UL>
</P>
<P>
The testsuite which comes with GNU JSP demonstrates and tests most
features of the JSP syntax.
</P>
<P>
JSP 0.91 and JSP 0.92 are not supported. If you need a version of GNUJSP that supports JSP 0.91, please check the archive section for version 0.9.10 and refer to the documentation that comes with 0.9.10.
</P>
<P>
GNU JSP supports the precompilation protocol specified
in the JSP 1.1 specification. If a request is received for a JSP page
with the parameter <code>jsp_precompile</code> set to any non-null value,
GNU JSP will ensure that the page is compiled, but will not process the
request.
</P>
<H3>Support for JSDK 2.1 Features</H3>
<P>
A great deal of work has been spent on providing wrapper classes to allow
servlet engines that implement only JSDK 2.0 (Apache JServ is probably the most popular of these) to use the JSP features that
require JSDK 2.1. If you have a JSDK 2.1 compliant server, these wrappers
aren't used. Every effort has been made to make GNU JSP function just as
well under JSDK 2.0 as JSDK 2.1, but there are a few caveats. If you run under JSDK 2.0, you should be aware that although GNU JSP
makes things like <code>jsp:forward</code> and
<code>jsp:include</code> possible, it doesn't remove the corresponding
limitation from your servlets that aren't processed by GNU JSP.
</P>
<H3>Configuration</H3>
<P>
Because GNUJSP can be used with such a large number of webservers and
servlet engines, it is impossible to provide a detailed installation
guide for each. You should consult the documentation that comes with
your webserver or servlet engine for details.
</P>
<P>
Detailed instructions are currently provided for the following engines:
<UL>
<LI>Apache JServ: see <code>INSTALL.apache</code></LI>
<LI>Jigsaw 2.0.x: see <code>INSTALL.jigsaw</code></LI>
<LI>vqServer 1.9.17: see <code>INSTALL.vqserver</code></LI>
</UL>
If your web server and servlet engine aren't specifically mentioned, here
are some general guidelines.
</P>
<OL>
<LI>
Add the <code>lib/gnujsp10.jar</code> file to the CLASSPATH used by the web server.
</LI>
<LI>
Create a directory to store the generated java and class files. Make sure
the webserver and/or the servlet engine have write permissions to this
directory.
</LI>
<LI>
<P>
Configure the GNUJSP servlet. The servlet alias should be "gnujsp" and the
class name should be "org.gjt.jsp.JspServlet" (note that this has changed from version 0.9.x). The init parameter
"scratchdir" is required, and should contain the name of the directory
created in the previous step.
</P>
<P>For a lot of servlet engines this means adding the following
lines to a file called "servlets.properties":
</P>
<CODE>
servlet.gnujsp.code=org.gjt.jsp.JspServlet<BR>
servlet.gnujsp.initArgs=scratchdir=[directory created in step two]<BR>
</CODE>
<P>
See <A HREF="#params">Initialization Parameters</A> for all options.
</P>
</LI>
<LI>
Associate the extension ".jsp" with the GNUJSP servlet.
</LI>
<LI>
To test your setup, copy the JSP files in the examples directory and try
accessing them via the webserver.
</LI>
</OL>
<H3>Troubleshooting</H3>
<P>
Most troubleshooting can be done by investigating the log files generated
by your servlet engine or webserver. Because configuration details vary,
we cannot provide detailed troubleshooting instructions, but you are welcome
to post your problems on the GNU JSP mailing list (see <A HREF="#bugs">Reporting Bugs</A>).
</P>
<H3>Developing on GNU JSP</H3>
<P>
GNUJSP automatically detects changes to a JSP file (and the JSP files it
includes), and recompiles the JSP file if necessary. When a change (or
a new file) is detected, the JSP file is translated to a java file, and
javac is run. If javac reports any errors, GNUJSP does its best to translate
the java line numbers to JSP line numbers and reports the errors in the
browser window.
</P>
<P>
When you use beans from JSP pages, you can put them in one of two places:
<OL>
<LI>
in the servlet repository; if GNUJSP has been installed in the servlet
repository, it calls the servlet class loader to load the beans from the
servlet repository. If the servlet engine automatically reloads servlets
when the bean changes, GNUJSP will also be reloaded and therefore reload
the bean as well.
</LI>
<LI>
in the system classpath; this always works, but the bean will
<STRONG>not</STRONG> be automatically reloaded when it is changed.
</LI>
</OL>
Some experimentation may be necessary to get this to work.
</P>
<H3>Deploying on GNU JSP</H3>
<P>
In a deployment or production environment, you'll generally want to
scrutinize the init parameters. Typically you will enable
<code>checkclass</code> and turn off <code>debug</code>. You can
probably also gain a little performance by turning off
<code>checkdependencies</code> if you're certain you don't need it.
</P>
<A NAME="params"><H3>Initialization Parameters</H3></A>
<P>
The full list of available init parameters is:
<P>
<DL>
<DT><STRONG>scratchdir</STRONG></DT>
<DD>
This required init parameter specifies the JSP repository; the directory
where GNUJSP writes the generated java and class files.
(0.9 used 'repository', but this conflicted with Apache JServ's
notion of a repository. 'scratchdir' is used by Sun's reference
implementation.)
</DD>
<DT><STRONG>compiler</STRONG></DT>
<DD>
This init parameter specifies the command line used to compile the
generated java files into class files. A number of special values can
be used:
<UL>
<LI>
When the command is "builtin-javac" the builtin java compiler
of the JDK is used (this requires tools.jar on JDK 1.2).
</LI>
<LI>
The string %classpath% is replaced with the system classpath.
</LI>
<LI>
The string %scratchdir% is replaced with the full pathname of
the JSP repository as defined by the scratchdir init parameter.
</LI>
<LI>
The string %source% is replaced with the name of the java file to
compile
</LI>
<LI>
The string %encoding% is replaced with the specified character
encoding of the JSP page being compiled.
</LI>
<LI>
The string %% is replaced with a single percentage sign.
</LI>
<LI>
All other occurences of %<param>% are replaced by the value
of the init parameter <param>, e.g. %beanspath% is replaced
by the value of the init parameter beanspath.
</LI>
</UL>
The default value of the compiler init parameter is:<BR>
<CODE>builtin-javac -classpath %classpath%:%scratchdir% -d %scratchdir% -deprecation %source%</CODE><BR>
where the colon between %classpath% and %scratchdir% is replaced
with the platform dependent path separator (: on Unix, ; on Windows).
<P>
On Windows systems, the Runtime.exec(String[]) method seems to reparse
the parameters, so make sure there are no spaces in the classpath or
scratchdir when you are not using the builtin java compiler.
</P>
<P>
You can use IBM's open source <A HREF="http://www10.software.ibm.com/developerworks/opensource/jikes/project/">jikes</A> compiler with GNUJSP; remember to add
<code>[JDK_HOME]/jre/lib/rt.jar</code> to the servlet engine's
classpath.
</P>
<P>
Using external compilers with the Blackdown JDK 1.2 prereleases for
GNU/Linux requires the use of the <code>-green</code> option for the JVM.
</P>
<DT><STRONG>checkclass</STRONG></DT>
<DD>
Default: false. If this property is false, GNU JSP will recompile all JSP
pages each time it starts up. This can be useful for development when
pages depend on beans that are simultaneously being developed. It can
be a bottleneck, however, in a production environment, so you may wish to
enable this option when deploying. Note that this operates independently of
<code>checkdependencies</code>; it merely means that if a .class file
already exists for a JSP page, it should be loaded instead of regenerated
on the first request.
</DD>
<DT><STRONG>checkdependencies</STRONG></DT>
<DD>
Default: <code>true</code>.
Set this init parameter to "false" to prevent GNUJSP from
checking the file dates of the source JSP file (and the files
included by it) when running the generated class file.
</DD>
<DT><STRONG>country</STRONG> and <STRONG>language</STRONG></DT>
<DD>
Default: the default country and language of the Java virtual machine.
Specify these properties to select a particular locale to internationalize
GNU JSP's error messages, if available.
</DD>
<DT><STRONG>debug</STRONG></DT>
<DD>
Default: <code>false</code>.
Set this init parameter to "true" to make GNUJSP generate
some debug output (in the servlet log).
</DD>
<DT><STRONG>denyuri</STRONG></DT>
<DD>
In many web servers, JSP pages can be called either as
"/secure/file.jsp" or as "/servlet/gnujsp/secure/file.jsp". This
is a security hole when authentication is required to access the
directory "/secure", but not for "/servlet". If the optional
denyuri init parameter is set, GNUJSP will not accept requests
that start with the same string as denyuri (in this example, you
would set denyuri to "/servlet/gnujsp"). This is a hack to
solve a problem that should really be solved by the servlet
engine. This parameter replaces the checkuri parameter in GNU
JSP 0.9.
</DD>
<DT><STRONG>
pagebase
</STRONG></DT>
<DD>
Default: not set.
When determining the JSP file to compile, GNUJSP calls
ServletContext.getRealPath(request.getServletPath()). If that fails to
return a valid filename, GNUJSP tries getRequestURI() instead. If that
also fails, GNUJSP finally tries request.getPathTranslated(). The
optional pagebase init parameter can be set to prefix the result of
getPathTranslated() with a constant string. This can be useful
when the servlet engine runs on a different server than the webserver.
</DD>
<DT><STRONG>
usepackages
</STRONG></DT>
<DD>
Default: false.<br> Set to true means that GNUJSP should generate
subdirectories and packages for java source and class
files. This is a must on MacOS platforms due to the maximum
filename length of 30 characters.
</DD>
<DT><STRONG>
jserv
</STRONG></DT>
<DD>
Set to anything means that you are using Apache with JServ.
It is needed for a JServ-specific workaround.
If you are not using Apache with JServ, do not set this property.
</DD>
</DL>
<H3>Using GNU JSP with Java 2</H3>
<P>
In general, GNU JSP behaves exactly the same under a Java 2 virtual
machine (JDK 1.2, for example) as it does when running under JDK 1.1.
However, if you want to use the built-in compiler (javac), you'll want
to add "<code>[JDK_HOME]/lib/tools.jar</code>" to the classpath setting.
</P>
<A NAME="bugs"><H3>Reporting Bugs</H3></A>
<P>
If you think you've found a bug or have a question, comment, or
contribution, check the mailing list at <A
HREF="http://www.gjt.org/servlets/MailingLists/ListInfo.html/gnujsp">http://www.gjt.org/servlets/MailingLists/ListInfo.html/gnujsp</A>.
</P>
</BLOCKQUOTE>
</BODY>
</HTML>
|
