Sun Java System Web Server 6.1 SP7 Programmer's Guide to Web Applications

Compiling JSPs: The Command-Line Compiler

Sun Java System Web Server provides the following ways of compiling JSP 1.2-compliant source files into servlets:

JSPs are automatically compiled at runtime.
The jspc command-line tool, described in this section, allows you to precompile JSPs at the command line.

To allow the JSP container to pick up the precompiled JSPs from a JAR file, you must disable dynamic reloading of JSPs. To do this, set the reload-interval property to -1 in the jsp-config element of the sun-web.xml file. For more information, see JSP Elements

The jspc command-line tool is located under install_dir/bin/https/bin (make sure this directory is in your path). The format of the jspc command is as follows:

jspc [options] file_specifier

The following table shows what file_specifier can be in the jspc command. The left column lists file specifiers, and the right column lists descriptions of those file specifiers.

Table 3–1 File Specifiers for the jspc Command


File Specifier	Description
files	One or more JSP files to be compiled.
`-webapp` dir	A directory containing a web application. All JSPs in the directory and its subdirectories are compiled. You cannot specify a WAR, JAR, or ZIP file; you must first extract it to an open directory structure.

The following table shows the basic options for the jspc command. The left column lists the option, and the right column describes what the option does.

Table 3–2 Basic jspc Options


Option	Description
`-q`	Enables quiet mode (same as `-v0`). Only fatal error messages are displayed.
`-d` `dir`	Specifies the output directory for the compiled JSPs. Package directories are automatically generated based on the directories containing the uncompiled JSPs. The default top-level directory is the directory from which `jspc` is invoked.
`-p` `name`	Specifies the name of the target package for all specified JSPs, overriding the default package generation performed by the `-d` option.
`-c` `name`	Specifies the target class name of the first JSP compiled. Subsequent JSPs are unaffected.
`-uribase` `dir`	Specifies the URI directory to which compilations are relative. Applies only to explicitly declared JSP files. This is the location of each JSP file relative to the `uriroot`. If this cannot be determined, the default is `/`.
`-uriroot` `dir`	Specifies the root directory against which URI files are resolved. Applies only to explicitly declared JSP files. If this option is not specified, all parent directories of the first JSP page are searched for a `WEB-INF` subdirectory. The closest directory to the JSP page that has one is used. If none of the JSP’s parent directories have a `WEB-INF` subdirectory, the directory from which `jspc` is invoked is used.
`-genclass`	Generates class files in addition to Java files.

The following table shows the advanced options for the jspc command. The left column lists the option, and the right column describes what the option does.

Table 3–3 Advanced jspc Options


Option	Description
`-v[level]`	Enables verbose mode. The `level` is optional; the default is `2`. Possible `level` values are: `0` - fatal error messages only `1` - error messages only `2` - error and warning messages only `3` - error, warning, and informational messages `4` - error, warning, informational, and debugging messages
`-mapped`	Generates separate `write` calls for each HTML line and comments that describe the location of each line in the JSP file. By default, all adjacent `write` calls are combined and no location comments are generated.
`-die[code]`	Causes the JVM to exit and generates an error return `code` if a fatal error occurs. If the `code` is absent or unparsable it defaults to `1`.
`-webinc` `file`	Creates partial servlet mappings for the `-webapp` option, which can be pasted into a `web.xml` file.
`-webxml` `file`	Creates an entire `web.xml` file for the `-webapp` option.
`-ieplugin` `class_id`	Specifies the Java plugin COM class ID for Internet Explorer. Used by the `<jsp:plugin>` tags.
`-deprecatedjavac`	Forces compilation of generated servlets using the deprecated `sun.tools.javac.Main`.

For example, this command compiles the hello JSP file and writes the compiled JSP under hellodir:

jspc -d hellodir -genclass hello.jsp

This command compiles all of the JSP files in the web application under webappdir into class files under jspclassdir:

jspc -d jspclassdir -genclass -webapp webappdir

To use either of these precompiled JSPs in a web application, put the classes under hellodir or jspclassdir into a JAR file, place the JAR file under WEB-INF/lib, and set the reload-interval property to -1 in the sun-web.xml file.

Package Names Generated by the JSP Compiler

When a JSP is compiled, a package is created for it. The package name starts with _jsps, and each path name component of the JSP is prefixed with an underscore. For example, the generated package name for /myjsps/hello.jsp would be _jsps._myjsps.

Other JSP Configuration Parameters

For information about the various JSP configuration parameters, see jsp-config The JSP compiler uses the default values for parameters that are not included in the file.