4 Precompiling JSPs with ojspc

This chapter describes the JSP pretranslation and precompilation capabilities provided by the ojspc utility packaged with OC4J. The following sections discuss ojspc functionality:

• How the ojspc Utility Works

• Using ojspc

• Precompiling One or More JSPs

• Precompiling JSPs within a WAR File

• Complete Summary of ojspc Command Line Options

4.1 How the ojspc Utility Works

This chapter describes the basic precompliation functionality provided by ojspc, as well as batch precompilation of JSPs with an archive file. It includes the following sections:

• Overview of Basic ojspc Functionality

• Overview of Batch Pretranslation of WAR Files

4.1.1 Overview of Basic ojspc Functionality

For a simple JSP page, default functionality for ojspc is as follows:

• Invokes the JSP translator to translate the JSP file into Java page implementation class code, producing a .java file.

• Invokes the Java compiler to compile the .java file, which produces a .class file for the page implementation class.

By default, ojspc generates the same set of files that are generated by the JSP translator in an on-demand translation scenario and places them in or under the current working directory from which you ran ojspc .

Output includes the following files:

• A .java source file (for batch pretranslation, this is discarded after compilation)

• A .class file for the page implementation class

• Optionally, a Java resource file (.res) for the static text of the page

Under some circumstances (as is noted in the -extres option description later in this chapter), ojspc options direct the JSP translator to produce a .res Java resource file for static page content, instead of putting this content into the page implementation class.

4.1.2 Overview of Batch Pretranslation of WAR Files

The ojspc utility accepts not only JSP files for translation, but can also accept WAR or EAR files for batch pretranslation. The resulting .class files and any Java resource files are output to a nested JAR file inside the WAR file. The nested JAR file is set in the WEB-INF\lib path within the WAR, enabling the archive to be deployed as-is into OC4J.

When the name of an archive file appears on the ojspc command line, ojspc by default executes the following steps:

1. Opens the archive file.

2. Translates and compiles all .jsp and .java files in the archive.

3. Tag files within the archive are also compiled if they used in a JSP within the archive.

4. Updates the archive with a new nested JAR file on the WEB-INF\lib path, and adds the resulting .class files and any Java resource files into this file. Any .java files that were created in the process are discarded.

The name of the nested JAR file includes the base name of the resulting archive file and has the .jar extension. For example, if ojspc is run on sample.war, the nested JAR file name within the WAR would be __oracle_jsp_sample.jar.

File paths within the nested JAR file are according to Java package names and according to specified file paths of JSP include and forward statements. The .class and resource files in the nested JAR file are located in the same directory path as would be the case if the original JSP files were translated after extraction.

4.2 Using ojspc

The ojspc utility can be invoked from any directory, provided the location of the ojspc executable is added to the PATH on the host machine. The general ojspc command-line syntax is as follows:

ojspc [option_settings] file_list

The source file list can include JSP files and other source files (.java), or archive files (JAR, WAR, EAR, or ZIP files). To precompile all of the JSP files within a directory, specify *.jsp as the value for file_list.

See the following sections for specific ojspc usage scenarios:

• Precompiling One or More JSPs

• Precompiling JSPs within a WAR File

Important: The location of ojspc.bat must be added to the PATH to enable ojspc to be invoked from any working directory. The default path to ojspc.bat is: ORACLE_HOME/j2ee/home/jsp/bin/ojspc

The following are the most commonly used ojspc options used to control file generation and placement. See "Complete Summary of ojspc Command Line Options" for the complete list of options.

• -appRoot to specify an application root directory if the directory containing the JSP source file(s) is different from the working directory in which ojspc is being run

• -srcdir to place source files in a specified location (not relevant for batch pretranslation)

• -dir to place binary files—.class files and Java resource files—in a specified location (not relevant for batch pretranslation)

• -noCompile to not compile the generated page implementation class source

  As a result of this, no .class files are produced.

• -extres to put static text into a Java resource (.res) file.

4.3 Precompiling One or More JSPs

This section provides usage scenarios for precompiling JSPs.

Precompiling a Single JSP

This example illustrates basic ojspc usage, which translates and compiles the specified JSP.

cd /source
ojspc index.jsp

In this case, the following files will be generated within the /source working directory:

_index.class
_index.java

Precompiling Multiple JSPs

In the next example, all of the JSPs within the myapp/mysrcdir/ are compiled:

cd /source
ojspc myapp/mysrcdir/*.jsp

By default, the resulting .java and .class files will be generated in a new subdirectory named _myapp/_mysrcdir within the /source working directory.

Precompiling JSPs in a Different Source Directory

Now presume that you run ojspc from a directory outside of the directory structure containing the source files. In this case, you must specify the application root using the -appRoot option, in addition to the absolute path to the files.

cd /stuff
ojspc -appRoot /source D:/source/myapp/mysrcdir/*.jsp

The resulting files will be generated in /stuff/_source/_myapp/_mysrcdir.

Generating Different File Types in Different Directories

The next example will generate Java class and files in the directory specified with the -dir option, and.java source files in the directory specified using -srcdir. The -extres option will place the static text in the JSP into a Java resource file named _MyPage.res, which is useful when a page contains a lot of static content.

ojspc -dir myapp/mybindir -extres -srcdir myapp/mysrcdir MyPage.jsp

Be aware of the following when using ojspc:

• Use spaces between JSP file names in the file list to compile specific JSPs. Note that the path must be specified for each JSP if the files are not in the working directory.

• Specify *.jsp to compile all JSPs within the target directory.

• Use spaces as delimiters between option names and option values in the option list.

• Option names are not case sensitive but option values usually are (such as package names, directory paths, class names, and interface names).

• Enable boolean options (flags), which are disabled by default, by simply typing the option name in the command line. For example, type -extres, not -extres true.

4.4 Precompiling JSPs within a WAR File

You can run ojspc on a WAR file, or on an EAR containing one or more nested WAR files, and precompile the JSPs within. The utility will create a JAR named __oracle_jsp_<warFileName>.jar containing the compiled Java classes on the WEB-INF\lib path within the WAR. The resulting WAR can then be deployed as-is.

For example, assume that ojspc is run on sample.ear, which includes a sample-web.war containing several JSPs. Note that because no output file is specified, the existing WAR will be updated with the new JAR file.

ojspc sample.ear

The updated sample-web.war will now include the following file on the WEB-INF\lib path:

__oracle_jsp_sample-web.jar

Additional usage notes:

• By default, ojspc updates the original archive file with the new JAR. If you want keep the original archive file unaltered, use the -output option to specify a new archive file name.

• Use the -batchMask option to specify file name extensions for pretranslation and compilation. Whatever you specify is used instead of the defaults (*.jsp and *.java).

• Use the -deleteSource option if you do not want processed source files to appear in the resulting archive file. Be sure to read the description of this option under "Complete Summary of ojspc Command Line Options" before using it.

• Any .java files created during translation are discarded from the updated WAR.

4.5 Complete Summary of ojspc Command Line Options

Table 4-1 below summarizes the command-line options supported by the ojspc pretranslation utility.

Table 4-1 Options for ojspc Pretranslation Utility

Option	Description
-addclasspath	Use to specify additional classpath entries for javac to use when compiling generated page implementation class source.
-approot	Use to specify an application root directory. This option is used only when ojspc is run from a different directory other that containing the files to be translated. The default is the ojspc working directory. The specified application root directory path is used as follows: For static include directives in the page being translated The specified directory path is prepended to any application-relative (context-relative) paths in the include directives of the translated page. In determining the package of the page implementation class The package will be based on the location of the file being translated relative to the application root directory. The package, in turn, determines the placement of output files. Consider the following example. You want to translate the following file: /abc/def/ghi/test.jsp You run ojspc from the current directory, /abc, as follows: cd /abc ojspc def/ghi/test.jsp The test.jsp page has the following include directive: <%@ include file="/test2.jsp" %> The test2.jsp page is in the /abc directory, as follows: /abc/test2.jsp This example requires no -appRoot setting because the default application root setting is the current directory, which is the /abc directory. The include directive uses the application-relative /test2.jsp syntax (note the beginning "/"), so the included page will be found as /abc/test2.jsp. The package in this case is _def._ghi, based on the location of test.jsp relative to the current directory when you ran ojspc. (The current directory is the default application root.) Output files are placed accordingly. If, however, you run ojspc from some other directory, suppose /home/mydir, then you would need an -appRoot setting as in the following example: cd /home/mydir ojspc -appRoot /abc abc/def/ghi/test.jsp The package is still _def._ghi, based on the location of test.jsp relative to the specified application root directory.
-batchMask	Use to specify source files to process in an archive file during batch pretranslation. By default, all .jsp and .java files are processed. File masks specified through the -batchMask option are used instead of (not in addition to) these defaults. Place quotes around the list of file masks and use commas or semicolons as delimiters within the list. White space before or after a file mask is ignored. You can include directories in the mask. Note that file masks specified in this option are not case-sensitive. The -batchMask implementation includes complete support for standard wildcard pattern-matching. Given the default setting, the following two examples are equivalent: ojspc myapp.war ojspc -batchMask "*.jsp,*.java" myapp.war This next example drops processing for .java files while adding processing for.jsph files: ojspc -batchMask "*.jsph,*.jsp" myapp.war The following example does not process.java files, and only processes .jsp files whose names start with "abc" and who are in subdirectories under the top level of the archive file: ojspc -batchMask "*/abc*.jsp" myapp.zip The following example is the same as the preceding example, but also processes .jsp files whose names start with "abc" in the top level of the archive file: ojspc -batchMask "abc*.jsp, */abc*.jsp" myapp.jar This final example specifically processes the file a.jspc, as well as any .jsp files that start with "My" and are in a directory that is a subdirectory of mydir/subdir and matches the pattern "t?st" (any character as the second character, such as "test", "tast", or "tust"): ojspc -batchMask "mydir/subdir/t?st/My*.jsp" myapp.ear
-debug	Include to generate SMAP debugging data within the generated Java class file. An optional setting, file, generates debug information in an SMAP file within the working directory. The filename is the same as the generated Java class, with the .smap extension. For example, the debug data for foo.jsp will be output to _foo_jsp.smap.
-deleteSource	Include if you do not want processed source files to appear in the resulting archive file during batch pretranslation. This includes .jsp and .java files by default, or else only the files that match the file mask in the -batchMask option. Generated .java files are also discarded. If you do not use the -output option, then the contents of the original archive file are overwritten to remove any processed source files after processing. If you do use the -output option, then processed source files will not be copied to the specified output archive file. (The original archive file is unaltered.) Usage notes: Files whose names do not match the default file extensions (if you do not use the -batchMask option), or whose names do not match the name masks specified using the -batchMask option, will not be discarded through the -deleteSource option. You must delete these files manually from the resulting archive file if desired. In particular, this applies to statically included source files, which are not translatable on their own and so should not use the .jsp extension or any other extension that might result in an attempt to translate the files on their own. As in any situation where JSP source files are not deployed, if you use -deleteSource, then the target JSP runtime environment must be configured to operate properly without having source files available.
-dir (or -d)	Use to specify a base directory for ojspc placement of generated binary files—.class files and Java resource files. (The .res files produced for static content by the -extres option are Java resource files.) As a shortcut, -d is also accepted. The specified path is taken as a file system path (not an application-relative or page-relative path), and the directory must already exist. Subdirectories under the specified directory are created automatically, as appropriate, depending on the package. The default is to use the current directory (your current directory when you executed ojspc). It is recommended that you use this option to place generated binary files into a clean directory so that you easily know what files have been produced. Notes This option is ignored during batch pretranslation of WAR or EAR files. In environments such as Windows and Unix that allow spaces in directory names, enclose the directory name in quotes.
-extend	Specify the class for the generated page implementation class to extend. Do not use this option for batch pretranslation.
-extraImports	Use to add imports beyond the default JSP packages imported by OC4J. Specify package names or fully qualified class names for any additional imports . Be aware that the names must be in quotes, and either comma-delimited or semicolon-delimited, as in the following example: ojspc -extraImports "java.util.*,java.io.*" foo.jsp
-extres	Include to place static content of the page into a Java resource file instead of into the service method of the generated page implementation class. If there is a lot of static content in a page, this technique will speed translation and might speed execution of the page. For more information, see "Managing Heavy Static Content or Tag Library Usage". The resource file is placed in the same directory as output .class files. The file name is based on the JSP page name. In the current OC4J JSP implementation, it will be the same core name as the JSP name (unless special characters are included in the JSP name), but with an underscore ("_") prefix and .res suffix. Translation of MyPage.jsp, for example, would create _MyPage.res in addition to normal output. The exact implementation for name generation might change in future releases, however.
-forgiveDupDirAttr	Include to avoid JSP translation errors if you have duplicate settings for the same directive attribute within a single JSP translation unit.
-help (or -h)	Displays ojspc usage information in the console.
-ignoreErrors	Include to force ojspc to continue processing if an error is encountered, unless the error is caused by an issue with one of the XML descriptors packaged with the JSPs, such as web.xml or orion-web.xml.
-implement	Specify an interface for the generated page implementation class to implement. Do not use this option for batch pretranslation.
-noCompile	Include to direct ojspc to not compile the generated page implementation class. This is in case you want to compile it later for some reason, such as with an alternative Java compiler.
-noTldXmlValidate	Include to disable XML validation of TLD files. By default, validation of TLD files is performed.
-oldIncludeFromTop	Include to specify that page locations in nested include directives are relative to the top-level page. Otherwise, page locations are relative to the immediate parent page, which complies with the JSP specification. This option provides backward compatibility with OC4J versions prior to Oracle9iAS Release 2.
-output	Use specify the name of the output archive file during batch pretranslation. All contents of the original archive file are copied into the specified archive file. The output .class files and any resource files from pretranslation are then placed into a nested JAR file within the specified file (and source files are deleted from the specified file if -deleteSource is enabled). The original archive file is unaltered and you would use the new file instead of the original file for deployment. (See "Overview of Batch Pretranslation of WAR Files" for information about the nested JAR file.) Without the -output option, the original archive file is updated; no new archive file is created. The following is an example of -output usage: ojspc -output myappout.war myapp.war
-packageName	Specify the package name for the generated page implementation class. If not specified, the package name is determined according to the location of the .jsp file relative to your current directory when you ran ojspc. Consider an example where you run ojspc from the /myapproot directory, while the .jsp file is in the /myapproot/src/jspsrc directory (where % is a UNIX prompt): % cd /myapproot % ojspc -packageName myroot.mypackage src/jspsrc/Foo.jsp This results in myroot.mypackage being used as the package name. If this example did not use the -packageName option, the JSP translator (in its current implementation) would use _src._jspsrc as the package name by default. (Be aware that such implementation details are subject to change in future releases.)
-reduceTagCode	Include to direct further reduction in the size of generated code for custom tag usage. The default is false.
-reqTimeIntrospection	Include to allow request-time JavaBean introspection whenever compile-time introspection is not possible. When compile-time introspection is possible and succeeds, however, there is no request-time introspection regardless of the setting of this flag. The default is false. As a sample scenario for request-time introspection, assume a tag handler returns a generic java.lang.Object instance in the VariableInfo instance of the tag-extra-info class during translation and compilation, but actually generates more specific objects during request-time (runtime). In this case, if -reqTimeIntrospection is enabled, the Web container will delay introspection until request-time. An additional effect of this flag is to allow a bean to be declared twice, such as in different branches of an if..then..else loop. Consider the example that follows. Without -reqTimeIntrospection being enabled, this code would cause a parse exception. With it enabled, the code will work without error: <% if (cond) { %> <jsp:useBean id="foo" class="pkgA.Foo" /> <% } else { %> <jsp:useBean id="foo" class="pkgA.Foo2" /> <% } %>
-setpropertyOnErrContinue	Include to continue iterating over request parameters and setting corresponding bean properties when an error is encountered during jsp:setProperty when property="*".
-srcdir	Use this option to place generated source files into a clean directory so that you conveniently know what files have been produced. Do not use this option for batch pretranslation. Specify the location where ojspc will place the generated (.java) source files. The specified directory must already exist. The specified path is taken simply as a file system path, not an application-relative or page-relative path. Subdirectories under the specified directory are created automatically, as appropriate, depending on the package. The default is to use the current directory (your current directory when you executed ojspc).
-staticTextInChars	Include to instruct the JSP translator to generate static text in JSP pages as characters instead of bytes. The default is false, which improves performance in outputting static text blocks. Enable this flag if your application requires the ability to change the character encoding dynamically during runtime, such as in the following example: <% response.setContentType("text/html; charset=UTF-8"); %>
-tagReuse	Use this option to specify the mode of tag handler reuse (tag handler instance pooling). Values are as follows: runtime: Enables the runtime model of tag handler reuse. You can override this in any particular JSP page by setting the JSP page context attribute oracle.jsp.tags.reuse to a value of false. Note that this option is deprecated in the current release. none: Disables tag handler reuse. You can override this in any particular JSP page by setting the JSP page context attribute oracle.jsp.tags.reuse to a value of true. compiletime (default): Enables the compile-time model of tag handler reuse in its basic mode. compiletime_with_release: Enables the compile-time model of tag handler reuse in its "with release" mode, where the tag handler release() method is called between usages of a given tag handler within a given page.
-verbose	Include to direct ojspc to print status information as it executes. The following example shows -verbose output for the translation of myerror.jsp. (In this example, ojspc is run from the directory where myerror.jsp is located.) > ojspc -verbose myerror.jsp Translating file: myerror.jsp JSP files translated successfully. Compiling Java file: ./_myerror.java
-version	Include to display the JSP version number.
-xmlValidate	Include to request XML validation of the web.xml file. By default, validation of web.xml is not performed.