Skip Headers

Oracle® Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide 10g Release 3 (10.1.3) Part No. B14430-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 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 ojs pc 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 Over view 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 j`sp: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.