Skip Headers

Oracle® Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide 10g Release 2 (10.1.2) B14014-02 |
| Library | Product | Contents | Index

Previous | Next |

# 7 JSP Translation and Deployment

This chapter discusses operation of the OC4J JSP translator, then discusses the `ojspc` utility and situations where pretranslation is useful, followed by general discussion of a number of additional JSP deployment considerations.

The following sections are included:

- Functionality of the JSP Translator

- The ojspc Pretranslation Utility

- JSP Deployment Considerations

## Functionality of the JSP Translator

JSP translators generate standard Java code for a JSP page implementation class. This class is essentially a servlet class wrapped with features for JSP functionality.

The following sections discuss general functionality of the JSP translator, focusing on its behavior in on-demand translation scenarios such as in OC4J in the Oracle Application Server:

- Features of Generated Code

- General Conventions for Output Names

- Generated Package and Class Names

- Generated Files and Locations

- Issues in the Current Release

- Oracle JSP Global Includes

Important: Implementation details in this section regarding package and class naming, file and directory naming, output file locations, and generated code are for illustrative purposes. The exact details are subject to change from release to release.

### Features of Gene rated Code

This section discusses general features of the page implementation class code that is produced by the JSP translator in translating JSP source (typically `.jsp` files).

#### Features of Page Implementation Class Code

When the JSP translator generates servlet code in the page implementation class, it automatically handles some of the standard programming overhead. For both the on-demand translation model and the pretranslation model, generated code automatically includes the following features:

- It extends a wrapper class provided by the JSP container that implements the `javax.servlet.jsp.HttpJspPage` interface, which extends the more generic `javax.servlet.jsp.JspPage` interface, which in turn extends the `javax.servlet.Servlet` interface.

- It implements the `_jspService()` method specified by the `HttpJspPage` interface. This method, often referred to as the "service" method, is the central method of the page implementation class. Code from any Java scriptlets, expressions, and JSP tags in the JSP page is incorporated into this method implementation.

- It includes code to request an HTTP session unless your JSP source code specifically sets `session="false"` in a `page` directive.

For introductory information about key JSP and servlet classes and interfaces, see Appendix A, "Servlet and JSP Technical Background".

#### Member Variables fo r Static Text

The service method, `_jspService()`, of the page implementation class includes print statements—`out.print()` or equivalent calls on the implicit `out` object—to print any static text in the JSP page. The JSP translator places the static text itself in a series of member variables in the page implementation class. The service method `out.print()` statements reference these member variables to print the text.

Note: The OC4J JSP translator can optionally place the static text in a Java resource file, which is advantageous for pages with large amounts of static text. See "Workarounds for Large Static Content or Significant Tag Library Usage". You can request this feature through the JSP `external_resource` configuration parameter for on-demand translation, or the `ojspc -extres` flag for pretranslation.

### General Co nventions for Output Names

The JSP translator follows a consistent set of conventions in naming output classes, packages, files, and directories. However, this set of conventions and other implementation details may change from release to release.

One fact that is not subject to change, however, is that the base name of a JSP page will be included intact in output class and file names as long as it does not include special characters. For example, translating `MyPage123.jsp` will always result in the string "MyPage123" being part of the page implementation class name, Java source file name, and class file name.

In Oracle Application Server 10g Release 2 (10.1.2), the base name is preceded by an underscore ("_"). Translating `MyPage123.jsp` results in the page implementation class `_MyPage123` in the source file `_MyPage123.java`, which is compiled into `_MyPage123.class`.

Similarly, where path names are used in creating Java package names, each component of the path is preceded by an underscore. Translating `/jspdir/myapp/MyPage123.jsp`, for example, results in class `_MyPage123` being in the following package:

    _jspdir._myapp

The package name is used in creating directories for output `.java` and `.class` files, so the underscores are also evident in output directory names. For example, in translating a JSP page in a directory such as `webapp/test`, the JSP translator by default will create a directory such as `webappdeployment/_pages/_test` for the page implementation class source. All output directories are created under the standard `_pages` directory, as described in "Generated Files and Locations".

If you include special characters in a JSP page name or path name, the JSP translator takes steps to ensure that no illegal Java characters appear in the output class, package, and file names. For example, translating `My-name_foo12.jsp` results in `_My_2d_name__foo12` being the class name, in source file `_My_2d_name__foo12.java`. The hyphen is converted to a string of alpha-numeric characters. (An extra underscore is also inserted before "`foo12`".) In this case, you can only be assured that alphanumeric components of the JSP page name will be included intact in the output class and file names. For example, you could search for "`My`", "`name`", or "`foo12`".

These conventions are demonstrated in examples provided later in this chapter.

### Generated Package and Class Names

Although the JSP specification defines a uniform process for parsing and translating JSP text, it does not describe how the generated classes should be named. That is up to each JSP implementation.

This section describes how the OC4J JSP translator creates package and class names when it generates code during translation.

Note: For information about general conventions that the OC4J JSP translator uses in naming output classes, packages, and files, see "General Conventions for Output Names".

#### Pack age Naming

In an on-demand translation scenario, the URL path that is specified when the user requests a JSP page—specifically, the path relative to the document root or application root—determines the package name for the generated page implementation class. Each directory in the URL path represents a level of the package hierarchy.

It is important to note, however, that generated package names are always lowercase, regardless of the case in the URL.

Consider the following URL as an example:

    http://host:port/HR/expenses/login.jsp

In the current OC4J JSP implementation, this results in the following package specification in the generated code:

    package _hr._expenses;

(Implementation details are subject to change in future releases.)

No package name is generated if the JSP page is at the application root directory, where the URL is as follows:

    http://host:port/login.jsp

#### Cla ss Naming

The base name of the `.jsp` file determines the class name in the generated code.

Consider the following URL example:

    http://host:port/HR/expenses/UserLogin.jsp

In the current OC4J JSP implementation, this yields the following class name in the generated code:

    public class _UserLogin extends ...

(Implementation details are subject to change in future releases.)

Be aware that the case (lowercase/uppercase) that users specify in the URL must match the case of the actual `.jsp` file name. For example, they can specify `UserLogin.jsp` if that is the actual file name, or `userlogin.jsp` if that is the actual file name, but not `userlogin.jsp` if `UserLogin.jsp` is the actual file name.

Currently, the translator determines the case of the class name according to the case of the file name. For example:

- The file name `UserLogin.jsp` results in the class `_UserLogin`.

- The file name `Userlogin.jsp` results in the class `_Userlogin`.

- The file name `userlogin.jsp` results in the class `_userlogin`.

If you care about the case of the class name, then you must name the `.jsp` file accordingly. However, because the page implementation class is invisible to the end user, this is usually not a concern.

### Generated Files and Locations

For on-demand translation scenarios, this section describes files that are generated by the JSP translator and where they are placed. (For pretranslation scenarios, `ojspc` places files differently and has its own set of relevant options. See "Summary of ojspc Output Files, Locations, and Related Options".)

Wherever JSP configuration parameters are mentioned, see "JSP Configuration Parameters" for more information.

Note: For information about general conventions used in naming output classes, packages, and files, see "General Conventions for Output Names".

#### Files Ge nerated by the JSP Translator

This section lists files that are generated by the JSP translator. For the file name examples, presume a file `Foo.jsp` is being translated.

Source files:

- A `.java` file (for example, `_Foo.java`) is produced for the page implementation class.

Binary files:

- A `.class` file is produced by the Java compiler for the page implementation class. The Java compiler is the JDK `javac` by default, but you can specify an alternative compiler using the JSP `javaccmd` configuration parameter.

- A `.res` Java resource file (for example, `_Foo.res`) is optionally produced for the static page content if the `external_resource` JSP configuration parameter is enabled.

Note: The exact names of generated files for the page implementation class might change in future releases, but will still have the same general form. The names would always include the base name, such as "Foo" in these examples, but might include variations beyond that.

#### JSP Tran slator Output File Locations

The JSP translator places generated output files under a `_pages` directory that is created under the JSP cache directory, which is specified in the `jsp-cache-directory` attribute of the `<orion-web-app>` element in either the `global-web-application.xml` file or the application `orion-web.xml` file. Here is the general base location if you assume the default "`./persistence`" value of `jsp-cache-directory`:

    ORACLE_HOME/j2ee/home/app-deployment/app-name/web-app-name/persistence/_pages/...

In OC4J standalone, here is the location relative to where OC4J is installed:

    j2ee/home/app-deployment/app-name/web-app-name/persistence/_pages/...

Note the following, and refer to "Key OC4J Configuration Files" for related information about the noted configuration files:

- The `app-deployment` directory is the OC4J deployment directory specified in the OC4J `server.xml` file. (In OC4J standalone, this is typically the `application-deployments` directory.)

- Also, `app-name` is the application name, according to an `<application>` element in `server.xml`.

- And `web-app-name` is the corresponding "Web application name", mapped to the application name in a `<web-app>` element in the OC4J Web site XML file (typically `default-web-site.xml` file in Oracle Application Server or `http-web-site.xml` in OC4J standalone).

The path under the `_pages` directory depends on the path of the `.jsp` file under the application root directory.

As an example, in OC4J standalone, consider the page `welcome.jsp` in the `examples/jsp` subdirectory under the OC4J standalone default Web application directory. The path to this page would be as follows, relative to where OC4J is installed:

    j2ee/home/default-web-app/examples/jsp/welcome.jsp

Assuming the default application deployment directory, the JSP translator would place the output files ( `_welcome.java` and `_welcome.class`) in the following directory:

    j2ee/home/application-deployments/default/defaultWebApp/persistence/_pages/_examples/_jsp

Because the `.jsp` source file is in the `examples/jsp` subdirectory under the application root directory, the JSP translator generates `_examples._jsp` as the package name and places the output files into an `_examples/_jsp` subdirectory under the `_pages` directory.

Note the following for OC4J standalone:

- The `application-deployments` directory is the OC4J default deployment directory.

- Also, `default` is the OC4J default application name and `defaultWebApp` is the default Web application name, both used for JSP pages placed in the `default-web-app` directory.

Important: Implementation details, such as the location of generated output files and use of "_" in output file names, are subject to change in future releases.

### Issues in the Current Release

In conditions where OC4J is heavily loaded and running out of resources, the JSP translator may occasionally produce a zero-length `.class` file, resulting in a "500 Internal Server Error". Use one of the following techniques to remedy the problem:

- Touch the appropriate JSP file so that it will be retranslated and recompiled.

- Remove the zero-length class file. (Its location will be noted in the error output.)

### Oracle JSP Global In cludes

The OC4J JSP container provides a feature called global includes. You can use this feature to specify one or more files to statically include into JSP pages in or under a specified directory, through virtual JSP `include` directives. During translation, the JSP container looks for a configuration file, `/WEB-INF/ojsp-global-include.xml`, that specifies the included files and the directories for the pages.

This enhancement is particularly convenient for migrating applications that used `globals.jsa` or `translate_params` functionality in previous Oracle JSP releases.

Globally included files can be used for the following, for example:

- Global bean declarations (formerly supported through `globals.jsa`)

- Common page headers or footers

#### The ojsp-global-include.xml File

The `ojsp-global-include.xml` file specifies the names of files to include, whether they should be included at the tops or bottoms of JSP pages, and the locations of JSP pages to which the global includes should apply. This section describes the elements of `ojsp-global-include.xml`.

##### <ojsp-global-include>

This is the root element of the `ojsp-global-include.xml` file. It has no attributes.

Subelement of `<ojsp-global-include>`:

    <include>

##### <include ... >

Use the `<include>` subelement of `<ojsp-global-include>` to specify a file to be included and whether it should be included at the top or bottom of JSP pages.

Subelement of `<include>`:

    <into>

Attributes of `<include>`:

- `file`: Specify the file to be included, such as `"/header.html"` or `"/WEB-INF/globalbeandeclarations.jsph"`. The file name setting must start with a slash ("`/`"). In other words, it must be application-relative, not page-relative.

- `position`: Specify whether the file is to be included at the top or bottom of JSP pages. Supported values are "`top`" (default) and "`bottom`".

##### <into ... >

Use this subelement of `<include>` to specify a location (a directory, and possibly subdirectories) of JSP pages into which the specified file is to be included. This element has no subelements.

Attributes of `<into>`:

- `directory`: Specify a directory. Any JSP pages in this directory, and optionally its subdirectories, will statically include the file specified in the `file` attribute of the `<include>` element. The `directory` setting must start with a slash ("`/`"), such as `"/dir1"`. The setting can also include a slash after the directory name, such as `"/dir1/"`, or a slash will be appended internally during translation.

- `subdir`: Use this to specify whether JSP pages in all subdirectories of the `directory` should also have the file statically include. Supported values are "`true`" (default) and "`false`".

#### Global Include Examples

This section provides examples of global includes.

##### Example: Header/Footer

Assume the following `ojsp-global-include.xml` file:

    <?xml version="1.0" standalone='yes'?>
    <!DOCTYPE ojsp-global-include SYSTEM 'ojsp-global-include.dtd'>

    <ojsp-global-include>
      <include file="/header.html">
         <into directory="/dir1" />
      </include>
      <include file="/footer1.html" position="bottom">
         <into directory="/dir1" subdir="false" />
         <into directory="/dir1/part1/" subdir="false" />
      </include>
      <include file="/footer2.html" position="bottom">
         <into directory="/dir1/part2/" subdir="false" />
      </include>
    </ojsp-global-include>

This example accomplishes three objectives:

- The `header.html` file is included at the top of any JSP page in or under the `dir1` directory. The result would be the same as if each `.jsp` file in or under this directory had the following `include` directive at the top of the page:

      <%@ include file="/header.html" %>

- The `footer1.html` file is included at the bottom of any JSP page in the `dir1` directory or its `part1` subdirectory. The result would be the same as if each `.jsp` file in those directories had the following `include` directive at the bottom of the page:

      <%@ include file="/footer1.html" %>

- The `footer2.html` file is included at the bottom of any JSP page in the `part2` subdirectory of `dir1`. The result would be the same as if each `.jsp` file in that directory had the following `include` directive at the bottom of the page:

      <%@ include file="/footer2.html" %>

Note: If multiple header or multiple footer files are included into a single JSP page, the order of inclusion is according to the order of `<include>` elements in the `ojsp-global-include.xml` file.

##### Example: translate_params Equivalent Code

Assume the following `ojsp-global-include.xml` file:

    <?xml version="1.0" standalone='yes'?>
    <!DOCTYPE ojsp-global-include SYSTEM 'ojsp-global-include.dtd'>

    <ojsp-global-include>
      <include file="/WEB-INF/nls/params.jsf">
         <into directory="/" />
      </include>
    </ojsp-global-include>

And assume `params.jsf` contains the following:

    <% request.setCharacterEncoding(response.getCharacterEncoding()); %>

The `params.jsf` file (essentially, the `setCharacterEncoding()` method call) is included at the top of any JSP page in or under the application root directory. In other words, it is included in any JSP page in the application. The result would be the same as if each `.jsp` file in or under this directory had the following `include` directive at the top of the page:

    <%@ include file="/WEB-INF/nls/parms.jsf" %>

## The ojs pc Pretranslation Utility

The `ojspc` utility is provided with OC4J for pretranslation of JSP pages. For consideration of pretranslation scenarios, see "JSP Pretranslation" and "Deployment of Binary Files Only".

The following sections discuss `ojspc` functionality:

- Overview of Basic ojspc Functionality

- Overview of ojspc Batch Pretranslation

- Option Summary Table for ojspc

- Command-Line Syntax for ojspc

- Option Descriptions for ojspc

- Summary of ojspc Output Files, Locations, and Related Options

Important: When you pretranslate JSP pages, be aware that significant differences between the development system and the runtime system, such as a different operating system or JDK, could cause problems. For use of `ojspc`, the `tools.jar` file from your JDK must be in the classpath. This is taken care of automatically in an Oracle Application Server installation. When using `ojspc` batch pretranslation in the current release, do not place `.java` files in or under the `/WEB-INF/lib` or `/WEB-INF/classes` directory. Placing `.java` files in or under either of these directories may result in one or more duplicate `.class` files at the top level of the of the archive during batch pretranslation.

### Overview of Basic ojspc Functionality

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

- It takes a JSP file (typically `.jsp`), either directly as an argument or from an archive file taken as an argument.

- It invokes the JSP translator to translate the JSP file into Java page implementation class code, producing a `.java` file.

- It invokes the Java compiler to compile the `.java` file, producing a `.class` file for the page implementation class.

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.

Because `ojspc` invokes the JSP translator, `ojspc` output conventions are the same as for the translator in general, as applicable. For general information about JSP translator output, including generated code features, general conventions for output names, generated package and class names, and generated files and locations, see "Functionality of the JSP Translator".

Note: The `ojspc` command-line tool is a front-end utility that invokes the `oracle.jsp.tool.Jspc` class.

### Over view of ojspc Batch Pretranslation

Prior to Oracle9iAS Release 2 (9.0.3), `ojspc` accepted only JSP files for translation. Now, however, it can also accept archive files—JAR, WAR, EAR, or ZIP files—for batch pretranslation.

Note: The `ojspc` utility does not depend on the file name extension to determine whether a file is an archive file. It makes the determination by examining the internal file structure.

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 file.

3. Adds the resulting `.class` files and any Java resource files into a nested JAR file inside the archive file, and discards `.java` files that were created in the process. The `.class` and resource files in the nested JAR file have directory paths such that upon extraction, they will be located in the same directory as would be the case if the original JSP files were translated after extraction.

By default, the mechanics are that the original archive file is extracted into a temporary storage area, a temporary archive file is created, contents of the original archive file are copied into the temporary file, output `.class` and resource files from pretranslation are added to a nested JAR file within the temporary file, the original archive file is deleted, and the temporary file is given the name of the original file. The original archive file is extracted in its entirety to ensure successful compilation of the translated pages. Alternatively, you have the option of specifying a new output file name, which will preserve the original archive file.

The nested JAR file is in the `_pages` directory of the resulting archive file. Its name includes the base name of the resulting archive file (either the original archive file name or a name according to the `ojspc` `-output` option) and has the `.jar` extension. In the OC4J 10.1.2 implementation, assuming an archive output file name of `myarch.war`, for example, the nested JAR file name would be `__oracle_jsp_myarch.jar`. Implementation details might change in future releases, but the base name of the archive file will always be included in the nested JAR file name.

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, as applicable and as one would expect.

Note: The only support for nested archive files is a WAR file within an EAR file. In this circumstance, the contents of the EAR file are extracted, then the contents of the WAR file are extracted and processed and the WAR file is updated appropriately, then the other contents of the EAR file are processed and the EAR file is updated appropriately.

There are `ojspc` settings for additional functionality, as follows:

- You can 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`).

- You can use the `-output` option to specify a new archive file name. By default, `ojspc` updates the original archive file, adding output `.class` files and any resource files (and possibly deleting processed source files, according to the `-deleteSource` option). If you want to be sure that the original archive file is unaltered, then enable the `-output` option. In this case, all contents of the original archive file are copied into the specified output archive file, then the specified output archive file is updated instead of the original file. The original archive file is unaltered, and you would use the new file instead of the original file for deployment.

- You can use the `-deleteSource` option if you do not want processed source files to appear in the resulting archive file. If you do not also use the `-output` option, this effectively means that all processed source files are removed from the original archive file after processing. If you do not use the `-batchMask` option, this consists of all `.jsp` and `.java` files. Otherwise, this consists of all files specified in the `-batchMask` setting.

For examples of these options, see the descriptions of those options under "Option Descriptions for ojspc".

### Option Summary Table for ojspc

Table 7-1 summarizes the options supported by the `ojspc` pretranslation utility. These options are further discussed in "Option Descriptions for ojspc".

The second column notes comparable or related JSP configuration parameters for on-demand translation environments, such as OC4J.

Table 7-1 Options for ojspc Pretranslation Utility

Option | Related JSP Configuration Parameters | Description | Default
--- | --- | --- | ---
-addclasspath | (None) | Specify additional classpath entries for `javac`. | Empty (no additional path entries)
-appRoot | (None) | Specify the application root directory for application-relative static `include` directives from the page. | Current directory
-batchMask | (None) | For batch pretranslation, optionally specify file masks for processing. | `*.jsp`, `*.java`
-dir (or -d) | (None) | Specify the location where `ojspc` should place generated binary files (`.class` and resource). Do not use this option for batch pretranslation. | Current directory
-deleteSource | (None) | For batch pretranslation, use this flag to direct that processed source files should be removed from (or not copied to) the resulting archive file. | `false`
-extend | (None) | Specify the class for the generated page implementation class to extend. Do not use this option for batch pretranslation. | Empty
-extraImports | extra_imports | Use this to add imports beyond the JSP defaults. | Empty
-extres | external_resource | Use this flag to direct `ojspc` to generate an external resource file for static text from the JSP file. | `false`
-forgiveDupDirAttr | forgive_dup_dir_attr | Use this flag to avoid JSP 1.2 translation errors if you have duplicate settings for the same directive attribute within a single JSP translation unit. | `false`
-help (or -h) | (None) | Use this flag to direct `ojspc` to display usage information. | `false`
-implement | (None) | Specify an interface for the generated page implementation class to implement. Do not use this option for batch pretranslation. | Empty
-noCompile | javaccmd | Use this flag to direct `ojspc` to not compile the generated page implementation class. | `false`
-noTldXmlValidate | no_tld_xml_validate | Use this flag to disable XML validation of TLD files. By default, validation of TLD files is performed. | `false`
-oldIncludeFromTop | old_include_from_top | Use this flag to specify that page locations in nested `include` directives are relative to the top-level page, for backward compatibility with Oracle JSP behavior prior to Oracle9iAS Release 2. | `false`
-output | (None) | For batch pretranslation, optionally specify the name of the output archive file. | Original archive file
-packageName | (None) | Specify the package name for the generated page implementation class. | Empty (with package names according to `.jsp` file location)
-reduceTagCode | reduce_tag_code | Use this flag to direct further reduction in the size of generated code for custom tag usage. | `false`
-reqTimeIntrospection | req_time_introspection | Enable this flag in order to allow request-time JavaBean introspection whenever compile-time introspection is not possible. | `false`
-srcdir | (None) | Specify the location where `ojspc` should place generated source files (`.java`). Do not use this option for batch pretranslation. | Current directory
-staticTextInChars | static_text_in_chars | Use this flag to instruct the JSP translator to generate static text in JSP pages as characters instead of bytes. | `false`
-tagReuse | tags_reuse_default | This specifies the mode for JSP tag handler reuse: `runtime` for the runtime model, `compiletime_with_release` or `compiletime` for the compile-time model, or `none` to disable tag handler reuse. | runtime
-verbose | (None) | Use this flag to direct `ojspc` to print status information as it executes. | `false`
-version | (None) | Use this flag to direct `ojspc` to display the JSP version number. | `false`
-xmlValidate | xml_validate | Use this flag to request XML validation of the `web.xml` file. By default, validation of `web.xml` is not performed. | `false`

### Command-Line Syntax for ojspc

Following is the general `ojspc` command-line syntax (where `%` is the system prompt):

    % ojspc [option_settings] file_list

The file list can include JSP files and other source files (```.java`), or archive files (JAR, WAR, EAR, or ZIP files).

Be aware of the following syntax notes:

- If multiple JSP files are translated, they all must use the same character set, either by default or through `page` directive settings.

- Use spaces between file names in the file list.

- 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`.

- Option settings and file names can actually be in any order, including interspersed.

Here are two examples:

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

    % ojspc -deleteSource myapp.war

### Option Descriptions for ojspc

This section describes the `ojspc` options in more detail.

#### -addclasspath

(fully qualified path; `ojspc` default: empty)

Use this option to specify additional classpath entries for `javac` to use when compiling generated page implementation class source. Otherwise, `javac` uses only the system classpath.

#### -appRoot

(fully qualified path; `ojspc` default: current directory)

Use this option to specify an application root directory. The default is your current directory when you ran `ojspc`.

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. (See "Summary of ojspc Output Files, Locations, and Related Options".)

This option is necessary, for example, so that included files can still be found if you run `ojspc` from some other directory.

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 (where `%` is a UNIX prompt):

      % 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.

Note: It is typical for the specified application root directory to be some level of parent directory of the directory where the translated JSP page is located.

#### -ba tchMask

(file masks to batch-process in archive; `ojspc` default: see description)

For batch pretranslation, you can use this option to specify source files to process in an archive file. 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.

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 `.jspf` and `.jsph` files:

    % ojspc -batchMask "*.jspf,*.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, a.jspc" myapp.ear

Important: File masks specified in this option are not case-sensitive.

#### -deleteSo urce

(boolean; `ojspc` default: `false`)

For batch pretranslation, enable this flag if you do not want processed source files to appear in the resulting archive file. This is `.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, as usual.

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.)

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. See "Configuring the OC4J JSP Container for Execution with Binary Files Only".

#### -dir

(fully qualified path; `ojspc` default: current directory)

Use this option 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. See "Summary of ojspc Output Files, Locations, and Related Options" for more information.

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: Do not use `-dir` for batch pretranslation. In environments such as Windows that allow spaces in directory names, enclose the directory name in quotes.

#### -extend

(fully qualified Java class name; `ojspc` default: empty)

Use this option to specify a Java class that the generated page implementation class will extend.

Note: Do not use `-extend` for batch pretranslation.

#### -extraImports

(import list; `ojspc` default: empty)

As described in "Default Package Imports", the OC4J JSP container has a smaller default list of packages that are imported into each JSP page than was the case prior to Oracle9iAS Release 2 (9.0.3). This is in accordance with the JSP specification. You can avoid updating your code, however, by specifying package names or fully qualified class names for any additional imports through the `-extraImports` option. 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

Notes: White space within the quotes, before or after package names or class names, is ignored. In an on-demand translation scenario, the JSP `extra_imports` configuration parameter provides the same functionality. As an alternative to using `-extraImports`, you can use global includes. See "Oracle JSP Global Includes".

#### -ex tres

(boolean; `ojspc` default: `false`)

Enabling this flag instructs `ojspc` to place static content of the page into a Java resource file instead of into the service method of the generated page implementation class.

The resource 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.

The resource file is placed in the same directory as output `.class` files.

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 "Workarounds for Large Static Content or Significant Tag Library Usage".

Note: In an on-demand translation scenario, the JSP `external_resource` configuration parameter provides the same functionality.

#### -for giveDupDirAttr

(boolean; `ojspc` default: `false`)

Enabling this flag avoids translation errors in JSP 1.2 (or higher) if you have duplicate settings for the same directive attribute within a single JSP translation unit (a JSP page plus anything it includes through `include` directives).

The JSP specification directs that a JSP container must verify that directive attributes, with the exception of the `page` directive `import` attribute, are not set more than once each within a single JSP translation unit. See "Duplicate Settings of Page Directive Attributes Are Disallowed" for more information.

The JSP 1.1 specification did not specify such a limitation. OC4J offers the `-forgiveDupDirAttr` option for backward compatibility.

Note: In an on-demand translation scenario, the JSP `forgive_dup_dir_attr` configuration parameter provides the same functionality.

#### -help

(boolean; `ojspc` default: `false`)

Use this option to have `ojspc` display usage information and then exit. As a shortcut, `-h` is also accepted.

#### -implement

(fully qualified Java interface name; `ojspc` default: empty)

Use this option to specify a Java interface that the generated page implementation class will implement.

Note: Do not use `-implement` for batch pretranslation.

#### -no Compile

(boolean; `ojspc` default: `false`)

Enabling this flag directs `ojspc` to not compile the generated page implementation class Java source. This is in case you want to compile it later for some reason, such as with an alternative Java compiler.

Note: In an on-demand translation scenario, the JSP `javaccmd` configuration parameter provides related functionality. It enables you to specify a complete Java compiler command line, optionally using an alternative compiler.

#### -noTldXmlValida te

(boolean; `ojspc` default: `false`)

Enable this flag if you do not want XML validation of tag library descriptor (TLD) files of the application. By default, validation of TLD files is performed.

See "Overview of TLD File Validation and Features" for related information.

Note: In an on-demand translation scenario, the JSP `no_tld_xml_validate` configuration parameter provides the same functionality.

#### -oldIncludeFromTop

(boolean; `ojspc` default: `false`)

This is for backward compatibility with Oracle JSP versions prior to Oracle9iAS Release 2, for functionality of `include` directives. If you enable this flag, 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.

Note: In an on-demand translation scenario, the JSP `old_include_from_top` configuration parameter provides the same functionality.

#### -outp ut

(archive file name; `ojspc` default: none)

For batch pretranslation, use the `-output` option if you want to specify a new archive file for output instead of updating the original archive file. In this case, all contents of the original archive file are copied into the specified archive file, then the output `.class` files and any resource files from pretranslation are 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 ojspc Batch Pretranslation" for information about the nested JAR file.)

Without the `-output` option, the original archive file is updated; no new archive file is created.

Here is an example of `-output` usage:

    % ojspc -output myappout.war myapp.war

#### -packa geName

(fully qualified package name; `ojspc` default: per `.jsp` file location)

Use this option to specify a package name for the generated page implementation class, using Java "dot" syntax.

Without setting this option, 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

(boolean; `ojspc` default: `false`)

The Oracle JSP implementation reduces the size of generated code for custom tag usage, but enabling this flag results in even further size reduction. There might be performance consequences regarding tag handler reuse, however. See "Tag Handler Code Generation".

Note: In an on-demand translation scenario, the JSP `reduce_tag_code` configuration parameter provides the same functionality.

#### -reqTimeIntrospection

(boolean; `ojspc` default: `false`)

Enabling this flag allows 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.

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 JSP container will delay introspection until request-time. (See "Scripting Variables, Declarations, and Tag-Extra-Info Classes" for information about use of `VariableInfo`.)

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.Foo1" />
    <% } else { %>
          <jsp:useBean id="foo" class="pkgA.Foo2" />
    <% } %>

Note: In an on-demand translation scenario, the JSP `req_time_introspection` configuration parameter provides the same functionality.

#### -src dir

(fully qualified path; `ojspc` default: current directory)

Use this option to specify a base directory location for `ojspc` placement of generated source files (`.java` files).

The specified path is taken simply as a file system path, not an application-relative or page-relative path. The directory must already exist.

Subdirectories under the specified directory are created automatically, as appropriate, depending on the package. See "Summary of ojspc Output Files, Locations, and Related Options" for more information.

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 source files into a clean directory so that you conveniently know what files have been produced.

Notes: Do not use `-srcdir` for batch pretranslation. In environments such as Windows that allow spaces in directory names, enclose the directory name in quotes.

#### -staticTextInChars

(boolean; `ojspc` default: `false`)

Enabling this flag directs the JSP translator to generate static text in JSP pages as characters instead of bytes. The default setting 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"); %>

Note: In an on-demand translation scenario, the JSP `static_text_in_chars` configuration parameter provides the same functionality.

#### -tagReuse

(mode for tag handler reuse; `ojspc` default: `runtime`)

Use this option to specify the mode of tag handler reuse (tag handler instance pooling), as follows:

- Use the setting `none` to disable 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`.

- Use the default setting `runtime` to enable 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`.

- Use the setting `compiletime` to enable the compile-time model of tag handler reuse in its basic mode.

- Use the setting `compiletime_with_release` to enable 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.

Notes: If you use a value of `runtime`, and your code allows the JSP container to continue processing a JSP page in the event that custom tags cause exceptions, you may encounter subsequent occurrences of `ClassCastException`. In this event, change the `-tagReuse` value to `compiletime` or `compiletime_with_release`. If you switch from the runtime model (`-tagReuse` value of `runtime`) to the compile-time model (`-tagReuse` value of `compiletime` or `compiletime_with_release`), or from the compile-time model to the runtime model, you must retranslate the JSP pages. For backward compatibility, a setting of `true` is also supported and is equivalent to a setting of `runtime`, and a setting of `false` is supported and is equivalent to a setting of `none`. In an on-demand translation scenario, the JSP `tags_reuse_default` configuration parameter provides the same functionality.

See "Disabling or Enabling Runtime or Compile-Time Tag Handler Reuse" for more information about tag handler reuse.

#### -verbose

(boolean; `ojspc` default: `false`)

Enabling this flag directs `ojspc` to report its translation steps 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; assume `%` is a UNIX prompt.)

    % ojspc -verbose myerror.jsp
    Translating file: myerror.jsp
    1 JSP files translated successfully.
    Compiling Java file: ./_myerror.java

#### -version

(boolean; `ojspc` default: `false`)

Use this option to have `ojspc` display the JSP version number and then exit.

#### -xmlValida te

(boolean; `ojspc` default: `false`)

Enable this flag if you want XML validation of the application `web.xml` file. Because the Tomcat JSP reference implementation does not perform XML validation, this flag is disabled by default.

Note: In an on-demand translation scenario, the JSP `xml_validate` configuration parameter provides the same functionality.

### Summ ary of ojspc Output Files, Locations, and Related Options

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 your current directory, from which you ran `ojspc` (not considering batch pretranslation).

Here are the 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

For more information about files that are generated by the JSP translator, see "Generated Files and Locations".

To summarize some of the commonly used options described under "Option Descriptions for ojspc", you can use the following `ojspc` options to affect file generation and placement:

- `-appRoot` to specify an application root directory

- `-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 file

For output file placement, not considering batch pretranslation, the directory structure underneath the current directory (or directories specified by the `-dir` and `-srcdir` options, as applicable) is based on the package. The package is based on the location of the file being translated relative to the application root, which is either the current directory or the directory specified in the `-appRoot` option.

For example, suppose you run `ojspc` as follows (where `%` is a UNIX prompt):

    % cd /abc
    % ojspc def/ghi/test.jsp

Then the package is `_def._ghi` and output files will be placed in the directory `/abc/_def/_ghi`, where the `_def/_ghi` subdirectory structure is created as part of the process.

If you specify alternate output locations through the `-dir` and `-srcdir` options, a `_def/_ghi` subdirectory structure is created under the specified directories.

Now presume that you run `ojspc` from some other directory, as follows:

    % cd /home/mydir
    % ojspc -appRoot /abc /abc/def/ghi/test.jsp

The package is still `_def._ghi`, according to the location of `test.jsp` relative to the specified application root. Output files will be placed in the directory `/home/mydir/_def/_ghi` or in a `_def/_ghi` subdirectory under locations specified through the `-dir` and `-srcdir` options. In either case, the `_def/_ghi` subdirectory structure is created as part of the process.

## JSP Deployment Considerations

The following sections cover general deployment considerations and scenarios, mostly independent of your target environment:

- Overview of EAR/WAR Deployment

- Application Deployment with Oracle JDeveloper

- JSP Pretranslation

- Deployment of Binary Files Only

### Overview of E AR/WAR D eployment

This section provides an overview of OC4J deployment features and standard WAR deployment features.

See Oracle Application Server Containers for J2EE User's Guide for detailed information about deployment to OC4J in an Oracle Application Server environment.

#### OC4J Deployment Features

In OC4J, deploy each application through a standard EAR (Enterprise archive) file. The name of the application and the name and location of the EAR file are specified through an `<application>` element in the OC4J `server.xml` file. This file is in the OC4J configuration files directory.

Note: In Oracle Application Server, directory paths are configurable; in OC4J standalone, the configuration files directory is `j2ee/home/config` by default.

In an Oracle Application Server environment, use Enterprise Manager for deployment and configuration and do not update `server.xml` or other configuration files directly. Refer to the Oracle Application Server Containers for J2EE User's Guide for information.

In an OC4J standalone development environment, OC4J supports the `admin.jar` tool for deployment. This modifies `server.xml`, `http-web-site.xml`, and other configuration files for you, based on settings you specify to the tool. Or you can modify the configuration files manually (not generally recommended). Note that if you modify configuration files in Oracle Application Server without going through Enterprise Manager, you must run the `dcmctl` tool, using its `updateConfig` command, to inform Oracle Application Server Distributed Configuration Management (DCM) of the updates. (This does not apply in an OC4J standalone mode, where OC4J is being run apart from Oracle Application Server.)

The `dcmctl` tool is documented in the Oracle Application Server Administrator's Guide.

The EAR file includes the following:

- A standard `application.xml` configuration file, in `/META-INF`

- Optionally, an `orion-application.xml` configuration file, in `/META-INF`

- A standard WAR (Web archive) file

The WAR file includes the following:

- A standard `web.xml` configuration file, in `/WEB-INF`

  In the `web.xml` file for any particular application, you can override global settings for individual configuration parameters or for the definition of the JSP servlet (`oracle.jsp.runtimev2.JspServlet` by default). Each application uses its own instance of the JSP servlet.

- Optionally, an `orion-web.xml` configuration file, in `/WEB-INF`

- Classes necessary to run the application (servlets, JavaBeans, and so on), under `/WEB-INF/classes` and in JAR files in `/WEB-INF/lib`

- JSP pages and static HTML files

See the Oracle Application Server Containers for J2EE User's Guide for more information about deployment to Oracle Application Server. See the Oracle Application Server Containers for J2EE Stand Alone User's Guide for deployment to a standalone environment and for information about `admin.jar`. Also see "Key OC4J Configuration Files" for a summary of important configuration files in OC4J.

#### Standard WAR Deployment

The JSP specification (since JSP 1.1) supports the packaging and deployment of Web applications, including JavaServer Pages, according to the servlet specification (since servlet 2.2).

In typical implementations, you can deploy JSP pages through the WAR mechanism, creating WAR files through the JAR utility. The JSP pages can be delivered in source form and are deployed along with any required support classes and static HTML files.

According to the servlet specification, a Web application includes a deployment descriptor file, `web.xml`, that contains information about the JSP pages and other components of the application. The `web.xml` file must be included in the WAR file.

The servlet specification also defines an XML DTD for `web.xml` deployment descriptors and specifies exactly how a servlet container must deploy a Web application to conform to the deployment descriptor.

Through these logistics, a WAR file is the best way to ensure that a Web application is deployed into any standard servlet environment exactly as the developer intends.

Deployment configurations in the `web.xml` deployment descriptor include mappings between servlet paths and the JSP pages and servlets that will be invoked. You can specify many additional features in `web.xml` as well, such as timeout values for sessions, mappings of file name extensions to MIME types, and mappings of error codes to JSP error pages.

For more information about standard WAR deployment, see the Sun Microsystems Java Servlet Specification.

Note: In OC4J, you typically deploy a WAR file within an EAR file. If you deploy a WAR file directly, OC4J transparently wraps it in an EAR file.

### Application Deploy ment with Oracle JDeveloper

Oracle JDeveloper supports many types of deployment profiles, including simple archive, J2EE application (EAR file), J2EE EJB module (EJB JAR file), J2EE Web module (WAR file), J2EE client module (client JAR file), tag library for JSP 1.2 (tag library JAR file), business components EJB session bean profile, and business components archive profile.

When creating an Oracle ADF Business Components Web application using Oracle JDeveloper, a J2EE Web module deployment archive is generated, containing both the Oracle ADF Business Components and the Web application files.

The JDeveloper deployment wizards create all the necessary code to deploy business components as a J2EE Web module. Typically, a JSP client accesses the Business Components application in a J2EE Web Module configuration. The JSP client can also use data tags, data Web beans, or UIX tags to access the business components. (See the Oracle Application Server Containers for J2EE JSP Tag Libraries and Utilities Reference for an overview of the Business Components and UIX tag libraries.)

A J2EE Web module is packaged as a WAR file that contains one or more Web components (servlets and JSP pages) and `web.xml`, the deployment descriptor file.

JDeveloper lets you create the deployment profile containing the Web components and the `web.xml` file, and packages them into a standard J2EE EAR file for deployment. JDeveloper takes the resulting EAR file and deploys it to one or more Oracle Application Server instances.

For information about JDeveloper, refer to the JDeveloper online help or to the following site on the Oracle Technology Network:

    http://www.oracle.com/technology/products/jdev/content.html

### JSP Pretranslation

JSP pages are typically used in an on-demand scenario, where pages are translated as they are invoked, in a sequence that is invisible to the user. Another approach is to pretranslate JSP pages, which offers at least two advantages:

- It saves users the translation overhead the first time a page is invoked.

- It ensures that the developer or deployer, instead of users, will see any translation or compilation errors.

You also might want to pretranslate pages so that you can deploy binary files only, as discussed in "Deployment of Binary Files Only".

OC4J users can employ the Oracle `ojspc` utility, either specifying individual files for pretranslation or specifying archive files (JAR, WAR, EAR, or ZIP) for batch pretranslation. There is also a standard `jsp_precompile` mechanism. These topics are covered in the following sections:

- Techniques for Page Pretranslation with ojspc

- Batch Pretranslation with ojspc

- Standard JSP Pretranslation without Execution

Also see "The ojspc Pretranslation Utility" for detailed information about this utility.

#### Techniques for Page Pretranslation with ojs pc

When you pretranslate with `ojspc` (not considering batch pretranslation), use the`-dir` option to set an appropriate output base directory for placement of generated binary files.

Consider the example in "JSP Translator Output File Locations", where the JSP page is located in the `examples/jsp` subdirectory under the OC4J standalone default Web application directory:

    j2ee/home/default-web-app/examples/jsp/welcome.jsp

A user would invoke this with a URL such as the following:

    http://host:port/examples/jsp/welcome.jsp

(This is just a general example and does not consider OC4J configuration for the context path.)

In an on-demand translation scenario for this page, as explained in the example, the JSP translator would by default use the following base directory for placement of generated binary files:

    j2ee/home/application-deployments/default/defaultWebApp/persistence/_pages/_examples/_jsp

When you pretranslate, set your current directory to the application root directory, then in `ojspc` set the `_pages` directory as the output base directory. This results in the appropriate package name and file hierarchy. Continuing the example (where `%` is a UNIX prompt, `OC4J_HOME` is the directory where OC4J is installed, and the `ojspc` command wraps around to a second line):

    % cd OC4J_HOME/j2ee/home/default-web-app
    % ojspc examples/jsp/welcome.jsp
    -dir OC4J_HOME/j2ee/home/application-deployments/default/defaultWebApp/persistence/_pages

(This assumes you specify the appropriate `OC4J_HOME` directory.) The `ojspc` command translates `examples/jsp/welcome.jsp` and specifies the `_pages` directory as the base output directory.

The URL noted above specifies an application-relative path of `examples/jsp/welcome.jsp`, so at execution time the JSP container looks for the binary files in an `_examples/_jsp` subdirectory under the `_pages` directory. This subdirectory would be created automatically by `ojspc` if it is run as in the above example.

At execution time, the JSP container would find the pretranslated binaries and would not have to perform translation, assuming that either the source file was not altered after pretranslation, or the JSP `main_mode` flag is set to `justrun`.

Note: OC4J JSP implementation details, such as use of underscores ("_") in output directory names, are subject to change from release to release. This documentation applies specifically to Oracle Application Server 10g Release 2 (10.1.2).

#### Batch Pretranslation with ojs pc

There are `ojspc` features for batch pretranslation of JSP files in archive files (JAR, WAR, EAR, or ZIP files). When you specify an archive file on the `ojspc` command line, by default all `.jsp` and `.java` files in the contents will be pretranslated and compiled, as appropriate, and the archive file will be updated to include the output `.class` files and any Java resource files (but not generated `.java` files). You would then deploy the resulting archive file.

In addition to this basic functionality, you can use key `ojspc` options as follows:

- You can use the `-batchMask` option to specify file name extensions for pretranslation and compilation. Whatever you specify is instead of the defaults (`*.jsp` and `*.java`).

- You can use the `-output` option to specify a new archive file name. By default, `ojspc` updates the original archive file, adding output `.class` files and any resource files (and possibly deleting processed source files, according to the `-deleteSource` option). If you want to be sure that the original archive file is unaltered, then enable the `-output` option. In this case, all contents of the original archive file are copied into the specified archive file, then the specified file is updated instead of the original file. The original archive file is unaltered, and you would use the new file instead of the original file for deployment.

- You can use the `-deleteSource` option if you do not want processed source files to appear in the resulting archive file. If you do not also use the `-output` option, this effectively means that all processed source files are removed from the original archive file after processing. If you do not use the `-batchMask` option, this consists of all `.jsp` and `.java` files. Otherwise, this consists of all files specified in the `-batchMask` setting.

#### Standard J SP Pretranslation without Execution

It is also possible to specify JSP pretranslation without execution when you invoke the page in an on-demand scenario. Accomplish this as follows:

1. Enable the JSP `precompile_check` configuration parameter. (See "JSP Configuration Parameters".)

2. Enable the standard `jsp_precompile` request parameter when you invoke the JSP page from the browser.

Following is an example of using `jsp_precompile`:

    http://host:port/foo.jsp?jsp_precompile=true

or:

    http://host:port/foo.jsp?jsp_precompile

(The "`=true`" is optional.)

Refer to the Sun Microsystems JavaServer Pages Specification for more information about this mode of operation.

### Deplo yment of Binary Files Only

You can avoid exposing your JSP source, for proprietary or security reasons, by pretranslating the pages and deploying only the translated and compiled binary files. Pages that are pretranslated, either from previous execution in an on-demand translation scenario or by using `ojspc`, can be deployed to any standard J2EE environment. This involves two steps:

1. You must archive and deploy the binary files appropriately.

2. In the target environment, the JSP container must be configured to run pages without the JSP source being available.

#### Archiving and Deploying the Binary Files

You must take steps to create and archive the binary files in an appropriate hierarchy.

- If you pretranslate with `ojspc`, you must first set your current directory to the application root directory. After running `ojspc`, archive the output files using the `ojspc` output directory as the base directory for the archive. See "The ojspc Pretranslation Utility" for general information about this utility.

- If you are archiving binary files produced during previous execution in an on-demand translation environment, then archive the output directory structure, typically under the `_pages` directory.

In the target environment, place the archive JAR file in the `/WEB-INF/lib` directory. Alternatively, restore the archived directory structure under the appropriate directory, typically under the `_pages` directory.

#### Configuring the OC4J JSP Container for Execution with Binary Files Only

If you have deployed binary files to an OC4J environment, set the JSP configuration parameter `main_mode` to the value `justrun` or `reload` to execute JSP pages without the original source.

Without this setting, the JSP translator will always look for the JSP source file to see if it has been modified more recently than the page implementation `.class` file, and will terminate with a "file not found" error if it cannot find the source file.

With `main_mode` set appropriately, the user can invoke a page with the same URL that would be used if the source file were in place.

For how to set configuration parameters in the OC4J environment, see "Setting JSP Configuration Parameters in OC4J".