← Back to branch summary

~ubuntu-branches/ubuntu/intrepid/tomcat5.5/intrepid

« back to all changes in this revision

Viewing changes to jasper/doc/jspc.html

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2006-09-27 11:19:17 UTC
  • mfrom: (1.1.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20060927111917-wov6fmkz3x6rsl68
Tags: 5.5.17-1ubuntu1
(Build-) depend on libmx4j-java (>= 3.0).

Show diffs side-by-side

added added

removed removed

Lines of Context:
jasper/doc/jspc.html
 
1
<html>
 
2
<head>
 
3
<title>&lt;jspc&gt;</title>
 
4
</head>
 
5
<body>
 
6
<H1> JspC -- A Command Line JSP Compilation Tool </H1>
 
7
<H3>$Id: jspc.html 373928 2006-01-31 22:19:27Z markt $</H3>
 
8
 
 
9
<H2>OVERVIEW </H2>
 
10
 
 
11
Even thought the primary focus of JSP is as a container run environment,
 
12
sometimes it is useful to create a pure servlet out of the JSP page.
 
13
JspC encapsulates the core JSP to servlet translation into a program
 
14
that has no dependencies on a containing servlet engine and allows you
 
15
to translate JSP pages into an equivalent Java servlet.
 
16
 
 
17
<H2>GENERAL USE </H2>
 
18
 
 
19
The most basic use of JspC is to compile a JSP page in place with the
 
20
jsp page(s) as the arguments.  This will compile the page with the
 
21
resulting java files placed in the directory JspC was called from.  The
 
22
package will be determined from the directories that the JSP page lives
 
23
in.  This will be relative to the web-app it live in (if it exists or is
 
24
specified) or the default package.  The class name will be the name of
 
25
the JSP page without the extension.
 
26
 
 
27
<P>To override these default values you can use the <tt>-c</tt> and 
 
28
<tt>-p</tt> options.  <tt>-c &lt;class name&gt;</tt> changes the name of 
 
29
the class of the first compiled JSP page to the class specified.
 
30
Subsequent JSP pages will not be affected by this option.  The 
 
31
<tt>-p &lt;package name&gt;</tt> option sets the package name of all JSP 
 
32
pages compiled by that invocation.  Web-Apps specified for translation 
 
33
will not be affected by either of these options.</P>
 
34
 
 
35
<P>The directory that the resulting java files will go into is specified by
 
36
the <TT>-d &lt;dir&gt;</TT> and <tt>-dd &lt;dir&gt;</tt> options.  Both
 
37
of these specify a directory that files will be written into.  When
 
38
using <tt>-d</tt> the java files will be placed in package appropriate
 
39
sub directories while with <tt>-dd</tt> all of the java files will be
 
40
placed literally into the specified directory (without any subdirectory
 
41
structure).</P>
 
42
 
 
43
<P>The amount of command line output can be throttled by the <tt>-q</tt> and 
 
44
the <tt>-v&lt;#&gt;</tt> options.  <tt>-q</tt> has the same effect as
 
45
<tt>-v0</tt>, which is to turn off all but fatal error messages.  
 
46
<tt>-v1</tt> builds on <tt>-v0</tt> and it will print out error messages, 
 
47
<tt>-v2</tt> adds warnings, <tt>-v3</tt> adds informational messages
 
48
that have no operational impact, and <tt>-v4</tt> adds various messages
 
49
used in debugging JspC itself.</P>
 
50
 
 
51
<P><tt>-ieplugin</tt> is used by the <tt>&lt;jsp:plugin&gt;</tt> tags.
 
52
If the Java Plug-in COM Class-ID you want to use changes then it can be
 
53
specified here.  This should not need to be altered.</P>
 
54
 
 
55
<P>As an aid to makefiles, the <tt>-die[#]</tt> option will cause the
 
56
JVM to exit with an error code if a fatal error occurs during the
 
57
translation.   This can be caused by such things as an invalid JSP 
 
58
or an unwritable destination.  There is an optional number that can be 
 
59
specified to specify the specific exit code, but it defaults to 
 
60
<tt>1</tt> if it is not specified or cannot be deciphered.</P>
 
61
 
 
62
<P>The <tt>-mapped</tt> option will split the JSP text content into a
 
63
one line per call format.  There are comments above and below the mapped
 
64
write calls to localize where in the JSP file each line of text comes
 
65
from.  This can lead to a minor performance degradation (but it is bound 
 
66
by a linear complexity).  Without this options all adjacent writes are
 
67
concatenated into a single write.</P>
 
68
 
 
69
<H2>WEB-APP INTEGRATION</H2>
 
70
<P>JspC is web-app aware.  The package names and all relative uri
 
71
references in JSP elements are rooted to a web-app base that is either
 
72
heuristically determined or specified by the user.<P>
 
73
 
 
74
<P><tt>-uriroot &lt;dir&gt;</tt> specifies the root of the web 
 
75
application.  This is where all absolute uris will be resolved from.  
 
76
If it is not specified then the first JSP page will be used to derive 
 
77
it.  To derive it each parent directory of the first JSP page is 
 
78
searched for a <tt>WEB-INF</tt> directory, and the directory closest to 
 
79
the JSP page that has one will be used.  If none can be found then the 
 
80
directory JspC was called from will be used.  This only affects pages 
 
81
translated from an explicitly declared JSP file.</P>
 
82
 
 
83
<P><tt>-uribase &lt;uri&gt;</tt> is used to establish the uri context of
 
84
relative URI references in the JSP pages.  If it does not exist then it
 
85
is derived from the location of the file relative to the declared or 
 
86
derived value of <tt>-uriroot</tt>.    This only affects pages 
 
87
translated from an explicitly declared JSP file.</P>
 
88
 
 
89
<P> The jsp files option of <tt>-webapp &lt;dir&gt;</tt> is used to
 
90
specify that an entire web-app's JSP files are to be translated.  The
 
91
value of <tt>-uriroot</tt> for that directory becomes the specified
 
92
directory, and all relative uris are resolved against their position in
 
93
the web app.  Currently specifying a war, jar, or zip file is not
 
94
supported.  Each directory is recursively searched and any file with a 
 
95
<tt>.jsp</tt> extension is parsed as though it is a JSP page.  These
 
96
pages obey the <tt>-d</tt>, <tt>-dd</tt>, and <tt>-p</tt> options.
 
97
 
 
98
<P>Appropriate entries for the <tt>web.xml</tt> file can be created via
 
99
the <tt>-webinc &lt;file&gt;</tt> and <tt>-webxml &lt;file&gt;</tt>
 
100
options.  All JSP files and web-apps parsed by the single invocation
 
101
will have appropriate <tt>servlet</tt> and <tt>servlet-mapping</tt> 
 
102
elements created for them.  The <tt>webinc</tt> creates only an XML
 
103
fragment suitable for inclusion into an existing <tt>web.xml</tt> file,
 
104
while the <tt>webxml</tt> option creates an entire file with the 
 
105
appropriate headers and root elements suitable for use as a 
 
106
<tt>web.xml</tt> file.</P>
 
107
 
 
108
<H2>COMMAND LINE SUMMARY</H2>
 
109
<pre>
 
110
Usage: jspc &lt;options&gt; [--] &lt;jsp files&gt;
 
111
where jsp files is any number of:
 
112
    &lt;file&gt;         A file to be parsed as a jsp page
 
113
    -webapp &lt;dir&gt;  A directory containing a web-app, all jsp pages
 
114
                   will recursively be parsed
 
115
where options include:
 
116
    -q          Quite mode (same as -v0)
 
117
    -v[#]       Verbose mode (optional number is level, default is 2)
 
118
    -d &lt;dir&gt;    Output Directory
 
119
    -dd &lt;dir&gt;   Literal Output Directory.  (package dirs will not be made)
 
120
    -p &lt;name&gt;         Name of target package
 
121
    -c &lt;name&gt;         Name of target class name
 
122
                (only applies to first JSP page)
 
123
    -mapped     Generate separate write() calls for each HTML line in the JSP
 
124
    -die[#]     Generate an error return code (#) on fatal errors.
 
125
                If the number is absent or unparsable it defaults to 1.
 
126
    -uribase &lt;dir&gt;  The uri directory compilations should be relative to
 
127
                    (Default is "/")
 
128
    -uriroot &lt;dir&gt;  The root directory that uri files should be resolved
 
129
                    against, (Default is the directory jspc is invoked from)
 
130
    -webinc &lt;file&gt;  Creates partial servlet mappings for the -webapp option
 
131
    -webxml &lt;file&gt;  Creates a complete web.xml when using the -webapp option.
 
132
    -ieplugin &lt;clsid&gt;  Java Plugin classid for Internet Explorer
 
133
    -sax2 &lt;driverclassname&gt; Driver class name for the SAX 2.0 parser to be used
 
134
</pre>
 
135
 
 
136
</body>
 
137
</html>