Oracle JavaServer Pages Developer's Guide and Reference Release 8.1.7 Part Number A83726-01 |
Library | Service | Contents | Index

## OracleJSP Configuration

The OracleJSP front-end servlet, `JspServlet`, supports a number of configuration parameters to control OracleJSP operation. They are set as servlet initialization parameters for `JspServlet`. How you accomplish this depends on the Web server and servlet environment you are using.

This section describes the OracleJSP configuration parameters and how to set them in the most prevalent Web server and servlet environments.

Only a limited number of these parameters are of interest in the Oracle products that supply OracleJSP, and how to set them may vary from product to product. Consult the product documentation for more information.

Configuration settings that apply to the Oracle Servlet Engine are typically supported as equivalent options in the OracleJSP pre-translation tool (`ojspc`). OSE does not employ the Oracle `JspServlet` in translating or running JSP pages.

### OracleJSP Configuration Parameters (Non-OSE)

This section describes the configuration parameters supported by the Oracle `JspServlet` for environments such as Apache/JServ, the Sun Microsystems JSWDK, or Tomcat. (Note that the Oracle Internet Application Server uses an Apache/JServ environment.)

For the Oracle Servlet Engine environment, some of the equivalent configuration functionality is supported through equivalent `ojspc` options.

#### Configuration Parameters Summary Table

Table A-2 summarizes the configuration parameters supported by Oracle `JspServlet` (the front-end of the OracleJSP container). For each parameter, the table notes the following:

- whether it is used during page translation or page execution

- whether it is typically of interest in a development environment, deployment environment, or both

- any equivalent `ojspc` translation options for pages that are targeted for the Oracle Servlet Engine (which does not use `JspServlet`)``

  OSE does not support execution-time configuration parameters.

Be aware of the following:

- The parameters `bypass_source`, `emit_debuginfo`, `external_resource`, `javaccmd`, and `sqljcmd` were not supported prior to OracleJSP release 1.1.0.0.0.

- The parameter `alias_translation` is for use in the Apache/JServ environment only.

- The parameter `session_sharing` is for use with `globals.jsa` only (presumably in a servlet 2.0 environment such as Apache/JServ).

  Notes: See "The ojspc Pre-Translation Tool" for a description of the `ojspc` options. The distinction between execution-time and translation-time is not particularly significant in a real-time translation environment, but may be of interest with respect to OSE.

  ##### Table A-2 OracleJSP Configuration Parameters

  Parameter | Related ojspc Options | Description | Default | Used in JSP Translation or Execution? | Used in Development or Deployment Environment?
  --- | --- | --- | --- | --- | ---
  alias_translation (Apache-specific) | n/a | boolean; `true` to work around Apache/JServ limitations in directory aliasing for JSP page references | false | execution | development and deployment
  bypass_source | n/a | boolean; `true` for OracleJSP to ignore `FileNotFound` exceptions on `.jsp` source; uses pre-translated and compiled code when source is not available | false | execution | deployment (also used by JDeveloper)
  classpath | -addclasspath (related, but different functionality) | additional classpath entries for OracleJSP class loading | null (no addl. path) | translation or execution | development and deployment
  developer_mode | n/a | boolean; `false` to not check timestamps to see if retranslation is necessary when a page is requested | true | execution | development and deployment
  emit_debuginfo | -debug | boolean; `true` to generate a line map to the original `.jsp` file for debugging | false | translation | development
  external_resource | -extres | boolean; `true` for OracleJSP to place all static content of the page into a separate Java resource file during translation | false | translation | development and deployment
  javaccmd | -noCompile | Java compiler command line--`javac` options, or alternative Java compiler run in a separate JVM (`null` means use JDK `javac` with default options) | null | translation | development and deployment
  page_repository_root | -srcdir -d | alternative root directory (fully qualified path) for OracleJSP to use in loading and generating JSP pages | null (use default root) | translation or execution | development and deployment
  session_sharing (for use with globals.jsa) | n/a | boolean; `true` for JSP session data to be propagated to the underlying servlet session for applications using `globals.jsa` | true | execution | development and deployment
  sqljcmd | n/a | SQLJ command line--`sqlj` options, or alternative SQLJ translator run in a separate JVM (`null` means use the Oracle SQLJ version provided with OracleJSP, with default option settings) | null | translation | development and deployment
  translate_params | n/a | boolean; `true` to override servlet containers that do not perform multibyte encoding | false | execution | development and deployment
  unsafe_reload | n/a | boolean; `true` to not restart the application and sessions whenever a JSP page is retranslated and reloaded | false | execution | development

#### Configuration Parameter Descriptions

This section describes the OracleJSP configuration parameters in more detail.

##### alias_translation

(boolean; OracleJSP default: `false`) (Apache-specific)

This parameter allows OracleJSP to work around limitations in the way Apache/JServ handles directory aliasing. For information about the current limitations, see "Directory Alias Translation".

You must set `alias_translation` to `true` for `httpd.conf` directory aliasing commands (such as the following example) to work properly in the Apache/JServ servlet environment:

    Alias /icons/ "/apache/apache139/icons/"

##### bypass_source

(boolean; OracleJSP default: `false`)

Normally, when a JSP page is requested, OracleJSP will throw a `FileNotFound` exception if it cannot find the corresponding `.jsp` source file, even if it can find the page implementation class. (This is because, by default, OracleJSP checks the page source to see if it has been modified since the page implementation class was generated.)

Set this parameter to `true` for OracleJSP to proceed and execute the page implementation class even if it cannot find the page source.

If `bypass_source` is enabled, OracleJSP will still check for retranslation if the source is available and is needed (one of the factors in determining whether it is needed is the setting of the `developer_mode` parameter).

Notes: The `bypass_source` option is useful in deployment environments that have the generated classes only, not the source. (For related discussion, see "Deployment of Binary Files Only".) Oracle JDeveloper enables `bypass_source` so that you can translate and run a JSP page before you have saved the JSP source to a file.

##### classpath

(fully qualified path; OracleJSP default: `null`)

Use this parameter to add classpath entries to the OracleJSP default classpath for use during translation, compilation, or execution of JSP pages. For information about the OracleJSP classpath and class loader, see "Classpath and Class Loader Issues (Non-OSE Only)".

The exact syntax depends on your Web server environment and operating system. See "OracleJSP Configuration Parameter Settings" for some examples.

Overall, OracleJSP loads classes from its own classpath (including entries from this `classpath` parameter), the system classpath, the Web server classpath, the page repository, and predefined locations relative to the root directory of the JSP application.

Be aware that classes loaded through the `classpath`-specified path are loaded by the JSP class loader, not the system class loader. During JSP execution, classes loaded by the JSP class loader cannot access (or be accessed by) classes loaded by the system class loader or any other class loader.

Notes: OracleJSP runtime automatic class reloading applies only to classes in the OracleJSP classpath. This includes paths specified through this `classpath` parameter. (See "Dynamic Class Reloading" for information about this feature.) When you are pre-translating pages to run in the Oracle Servlet Engine, the `ojspc` `-addclasspath` option offers some related, though different, functionality. See "Option Descriptions for ojspc".

##### developer_mode

(boolean; OracleJSP default: `true`)

Set this flag to `false` to instruct OracleJSP to not routinely compare the timestamp of the page implementation class to the timestamp of the `.jsp` source file when a page is requested. Ordinarily, OracleJSP checks every time to see if the source has been modified since the page implementation class was generated. If that is the case, OracleJSP retranslates the page. With `developer_mode=false`, OracleJSP will check only upon the initial request for the page or application. For subsequent requests, it will simply re-execute the generated page implementation class.

Oracle generally recommends setting `developer_mode` to `false`, particularly in a deployment environment where code is not likely to change and where performance is a significant issue.

##### emit_debuginfo

(boolean; OracleJSP default: `false`) (for developer only)

Set this flag to true to instruct OracleJSP to generate a line map to the original `.jsp` file for debugging. Otherwise, lines will be mapped to the generated page implementation class.

Notes: Oracle JDeveloper enables `emit_debuginfo`. When you are pre-translating pages to run in the Oracle Servlet Engine, the `ojspc` `-debug` option is equivalent. See "Option Descriptions for ojspc".

##### external_resource

(boolean; OracleJSP default: `false`)

Set this flag to true to instruct the OracleJSP translator to place generated static content (the Java print commands that output static HTML code) 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. For release 8.1.7, it will be the same name as the JSP name, but with the `.res` suffix. (Translation of `MyPage.jsp`, for example, would create `MyPage.res` in addition to normal output. The exact implementation may change in future releases, however.)

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

If there is a lot of static content in a page, this technique will speed translation and may speed execution of the page. In extreme cases, it may even prevent the service method from exceeding the 64K method size limit imposed by the Java VM. For more information, see "Workarounds for Large Static Content in JSP Pages".

Note: When you are pre-translating pages to run in the Oracle Servlet Engine, the `ojspc` `-extres` option is equivalent. The `ojspc -hotload` option is also relevant, performing the `-extres` functionality along with additional steps to allow hotloading into Oracle8i. See "Option Descriptions for ojspc".

##### javaccmd

(compiler executable; OracleJSP default: `null`)``

This parameter is useful in either of the following circumstances:

- if you want to set `javac` command-line options (although default settings are typically sufficient)

- if you want to use a compiler other than `javac` (optionally including command-line options)``

Specifying an alternative compiler results in OracleJSP spawning that executable as a separate process in a separate JVM, instead of spawning the JDK default compiler within OracleJSP's JVM. You can fully specify the path for the executable, or specify only the executable and let OracleJSP look for it in the system path.

The following `javaccmd` setting enables the `javac -verbose` option:

    javaccmd=javac -verbose

The exact syntax depends on your servlet environment. See "OracleJSP Configuration Parameter Settings".

Notes: The specified Java compiler must be installed in the classpath and any front-end utility (if applicable) must be installed in the system path. When you are pre-translating pages to run in the Oracle Servlet Engine, the `ojspc` `-noCompile` option allows similar functionality. It results in no compilation by `javac`, so you can compile the translated classes manually using your desired compiler. See "Option Descriptions for ojspc".

##### page_repository_root

(fully qualified directory path; OracleJSP default: `null`)

OracleJSP uses the Web server document repository to generate or load translated JSP pages. By default, in an on-demand translation scenario, the root directory is the Web server doc root directory (for Apache/JServ) or the servlet context root directory of the application the page belongs to. JSP page source is in the root directory or some subdirectory. Generated files are written to a `_pages` subdirectory or some corresponding subdirectory.

Set the `page_repository_root` option to instruct OracleJSP to use a different root directory.

For information about file locations relative to the root directory and `_pages` subdirectory, see "OracleJSP Translator Output File Locations".

Notes: The specified directory, `_pages` subdirectory, and any appropriate subdirectories under these are created automatically if they do not already exist. When you are pre-translating pages to run in the Oracle Servlet Engine, the `ojspc` options `-srcdir` and `-d` provide related functionality. See "Option Descriptions for ojspc".

##### session_sharing

(boolean; OracleJSP default: `true`) (for use with globals.jsa)

When a `globals.jsa` file is used for an application, presumably in a servlet 2.0 environment, each JSP page uses a distinct JSP session wrapper attached to the single overall servlet session object provided by the servlet container.

In this situation, the default `true` setting of the `session_sharing` parameter results in JSP session data being propagated to the underlying servlet session. This allows servlets in the application to access the session data of JSP pages in the application.

If `session_sharing` is `false` (which parallels standard behavior in most JSP implementations), JSP session data is not propagated to the servlet session. As a result, an application's servlets would not be able to access JSP session data.

This parameter is meaningless if `globals.jsa` is not used. For information about `globals.jsa`, see "Overview of globals.jsa Functionality".

##### sqljcmd

(SQLJ translator executable; OracleJSP default: `null`)

This parameter is useful in any of the following circumstances:

- if you want to set SQLJ command-line options

- if you want to use a different SQLJ translator (or at least a different version) than the one provided with OracleJSP

- if you want to run SQLJ in a separate process from OracleJSP

Specifying a SQLJ translator executable results in OracleJSP spawning that executable as a separate process in a separate JVM, instead of spawning the default SQLJ translator within OracleJSP's JVM.

You can fully specify the path for the executable, or specify only the executable and let OracleJSP look for it in the system path.

Following is an example of a `sqljcmd` setting:

    sqljcmd=sqlj -user=scott/tiger -ser2class

(The exact syntax depends on your servlet environment. See "OracleJSP Configuration Parameter Settings".)

Notes: Appropriate SQLJ files must be in the classpath, and any front-end utility (such as `sqlj` in the example) must be in the system path. (For Oracle SQLJ, `translator.zip` and the appropriate SQLJ runtime ZIP file must be in the classpath. See "Summary of Files".) Presumably the great majority of OracleJSP developers will use Oracle SQLJ (as opposed to some other SQLJ product) if they use SQLJ code in their JSP pages; however, this option is useful if you want to use a different Oracle SQLJ version (for example, one intended for use with Oracle JDBC 8.0.x/7.3.x drivers instead of Oracle8i drivers) or if you want to set SQLJ options.

##### translate_params

(boolean; OracleJSP default: `false`)

Set this flag to `true` to override servlet containers that do not encode multibyte (NLS) request parameters or bean property settings. With this setting, OracleJSP encodes request parameters and bean property settings. Otherwise, OracleJSP returns the parameters from the servlet container unchanged.

Because the Oracle Servlet Engine does not support execution-time configuration parameters, `translate_params` cannot be set for the OSE environment. See "Code Equivalent to the translate_params Configuration Parameter" for a workaround.

For more information about the functionality and use of `translate_params`, including situations where it should not be used, see "OracleJSP Extended Support for Multibyte Parameter Encoding".

##### unsafe_reload

(boolean; OracleJSP default: `false`) (for developer only)

By default, OracleJSP restarts the application and sessions whenever a JSP page is dynamically retranslated and reloaded (which occurs when the JSP translator finds a `.jsp` source file with a more recent timestamp than the corresponding page implementation class).

Set this parameter to `true` to instruct OracleJSP not to restart the application after dynamic retranslations and reloads. This avoids having existing sessions become invalid.

For a given JSP page, this parameter has no effect after the initial request for the page if `developer_mode` is set to `false` (in which case OracleJSP never retranslates after the initial request).

Important: This parameter is intended for developers only and is not recommended for deployment environments.

### OracleJSP Configuration Parameter Settings

How to set the JSP configuration parameters discussed in the preceding section ("OracleJSP Configuration Parameters (Non-OSE)") depends on your Web server and servlet environment.

Non-Oracle environments support configuration parameter settings through properties files or similar functionality.

The Oracle Servlet Engine, provided with the Oracle8i JServer environment, does not directly support OracleJSP configuration parameters (because it does not use `JspServlet`). However, some of the translation parameter settings have equivalent OracleJSP translator options. These options are noted in the "Configuration Parameters Summary Table".

Other Oracle products that support OracleJSP have their own mechanisms for configuration settings--consult the product documentation.

The remainder of this section describes how to set configuration parameters in the Apache/JServ, Sun Microsystems JSWDK, and Tomcat environments.

#### Setting OracleJSP Parameters in Apache/JServ

Each Web application in an Apache/JServ environment has its own properties file, known as a zone properties file. In Apache terminology, a zone is essentially the same as a servlet context.

The name of the zone properties file depends on how you mount the zone. (See the Apache/JServ documentation for information about zones and mounting.)

To set OracleJSP configuration parameters in an Apache/JServ environment, set the `JspServlet` `initArgs` property in the application zone properties file, as in the following example (which happens to use UNIX syntax):

    servlet.oracle.jsp.JspServlet.initArgs=developer_mode=false,
    sqljcmd=sqlj -user=scott/tiger -ser2class=true,classpath=/mydir/myapp.jar

(The preceding is a single wrap-around line.)

The servlet path, `servlet.oracle.jsp.JspServlet`, also depends on how you mount the zone. It does not represent a literal directory path.

Note: Because `initArgs` parameters are comma-separated, there can be no commas within a parameter setting. Spaces and other special characters (such as "=" in this example) do not cause a problem, however.

#### Setting OracleJSP Parameters in JSWDK

To set OracleJSP configuration parameters in a JSWDK environment, set the `jsp.initparams` property in the `servlet.properties` file in the `WEB-INF` directory of the application's servlet context, as in the following example (which happens to use UNIX syntax):

    jsp.initparams=developer_mode=false,classpath=/mydir/myapp.jar

Note: Because `initparams` parameters are comma-separated, there can be no commas within a parameter setting. Spaces and other special characters do not cause a problem, however.

#### Setting OracleJSP Parameters in Tomcat

To set OracleJSP configuration parameters in a Tomcat environment, add `init-param` entries in the `web.xml` file as shown below.

Note: There is a global `web.xml` file in the `[TOMCAT_HOME]/conf` directory. To override any settings in this file for a particular application, update the `web.xml` file in the `WEB-INF` directory under the particular application root.

    <servlet>
       <init-param>
          <param-name>
             developer_mode
          </param-name>
          <param-value>
             true
          </param-value>
       </init-param>
       <init-param>
          <param-name>
             external_resource
          </param-name>
          <param-value>
             true
          </param-value>
       </init-param>
       <init-param>
          <param-name>
             javaccmd
          </param-name>
          <param-value>
             javac -verbose
          </param-value>
       </init-param>
    </servlet>

#### Oracle Servlet Engine JSP Configuration

Because the Oracle Servlet Engine does not use the OracleJSP `JspServlet` front-end, it requires other mechanisms for OracleJSP configuration settings.

Appropriate translation-time configuration parameters have equivalent support through command-line options of `ojspc`, which is the utility to pre-translate JSP pages for the OSE environment. The correlation between OracleJSP configuration parameters and `ojspc` options is noted in the table in "Configuration Parameters Summary Table".

There is no such equivalent support for runtime configuration parameters, however. The most significant of these is `translate_params`, required for NLS use in servlet environments that do not support multibyte encoding of request parameters. The Oracle Servlet Engine requires this functionality, but it is left to the developer to write equivalent code in the JSP page. For details, see "Code Equivalent to the translate_params Configuration Parameter".

| Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index