JspC -- A Command Line JSP Compilation Tool

$Id$

OVERVIEW

Even thought the primary focus of JSP is as a container run environment, sometimes it is useful to create a pure servlet out of the JSP page. JspC encapsulates the core JSP to servlet translation into a program that has no dependencies on a containing servlet engine and allows you to translate JSP pages into an equivalent Java servlet.

GENERAL USE

The most basic use of JspC is to compile a JSP page in place with the jsp page(s) as the arguments. This will compile the page with the resulting java files placed in the directory JspC was called from. The package will be determined from the directories that the JSP page lives in. This will be relative to the web-app it live in (if it exists or is specified) or the default package. The class name will be the name of the JSP page without the extension.

To override these default values you can use the -c and -p options. -c <class name> changes the name of the class of the first compiled JSP page to the class specified. Subsequent JSP pages will not be affected by this option. The -p <package name> option sets the package name of all JSP pages compiled by that invocation. Web-Apps specified for translation will not be affected by either of these options.

The directory that the resulting java files will go into is specified by the -d <dir> and -dd <dir> options. Both of these specify a directory that files will be written into. When using -d the java files will be placed in package appropriate sub directories while with -dd all of the java files will be placed literally into the specified directory (without any subdirectory structure).

The amount of command line output can be throttled by the -q and the -v<#> options. -q has the same effect as -v0, which is to turn off all but fatal error messages. -v1 builds on -v0 and it will print out error messages, -v2 adds warnings, -v3 adds informational messages that have no operational impact, and -v4 adds various messages used in debugging JspC itself.

-ieplugin is used by the <jsp:plugin> tags. If the Java Plug-in COM Class-ID you want to use changes then it can be specified here. This should not need to be altered.

As an aid to makefiles, the -die[#] option will cause the JVM to exit with an error code if a fatal error occurs during the translation. This can be caused by such things as an invalid JSP or an unwritable destination. There is an optional number that can be specified to specify the specific exit code, but it defaults to 1 if it is not specified or cannot be deciphered.

The -mapped option will split the JSP text content into a one line per call format. There are comments above and below the mapped write calls to localize where in the JSP file each line of text comes from. This can lead to a minor performance degradation (but it is bound by a linear complexity). Without this options all adjacent writes are concatenated into a single write.

WEB-APP INTEGRATION

JspC is web-app aware. The package names and all relative uri references in JSP elements are rooted to a web-app base that is either heuristically determined or specified by the user.

-uriroot <dir> specifies the root of the web application. This is where all absolute uris will be resolved from. If it is not specified then the first JSP page will be used to derive it. To derive it each parent directory of the first JSP page is searched for a WEB-INF directory, and the directory closest to the JSP page that has one will be used. If none can be found then the directory JspC was called from will be used. This only affects pages translated from an explicitly declared JSP file.

-uribase <uri> is used to establish the uri context of relative URI references in the JSP pages. If it does not exist then it is derived from the location of the file relative to the declared or derived value of -uriroot. This only affects pages translated from an explicitly declared JSP file.

The jsp files option of -webapp <dir> is used to specify that an entire web-app's JSP files are to be translated. The value of -uriroot for that directory becomes the specified directory, and all relative uris are resolved against their position in the web app. Currently specifying a war, jar, or zip file is not supported. Each directory is recursively searched and any file with a .jsp extension is parsed as though it is a JSP page. These pages obey the -d, -dd, and -p options.

Appropriate entries for the web.xml file can be created via the -webinc <file> and -webxml <file> options. All JSP files and web-apps parsed by the single invocation will have appropriate servlet and servlet-mapping elements created for them. The webinc creates only an XML fragment suitable for inclusion into an existing web.xml file, while the webxml option creates an entire file with the appropriate headers and root elements suitable for use as a web.xml file.

COMMAND LINE SUMMARY

Usage: jspc <options> [--] <jsp files>
where jsp files is any number of:
    <file>         A file to be parsed as a jsp page
    -webapp <dir>  A directory containing a web-app, all jsp pages
                   will recursively be parsed
where options include:
    -q          Quite mode (same as -v0)
    -v[#]       Verbose mode (optional number is level, default is 2)
    -d <dir>    Output Directory
    -dd <dir>   Literal Output Directory.  (package dirs will not be made)
    -p <name>         Name of target package
    -c <name>         Name of target class name
                (only applies to first JSP page)
    -mapped     Generate separate write() calls for each HTML line in the JSP
    -die[#]     Generate an error return code (#) on fatal errors.
                If the number is absent or unparsable it defaults to 1.
    -uribase <dir>  The uri directory compilations should be relative to
                    (Default is "/")
    -uriroot <dir>  The root directory that uri files should be resolved
                    against, (Default is the directory jspc is invoked from)
    -webinc <file>  Creates partial servlet mappings for the -webapp option
    -webxml <file>  Creates a complete web.xml when using the -webapp option.
    -ieplugin <clsid>  Java Plugin classid for Internet Explorer
    -sax2 <driverclassname> Driver class name for the SAX 2.0 parser to be used