Skip Headers

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

Previous | Next |

# 3 Configuring the OC4J JSP Environment

This chapter covers basic issues in your JSP environment, including key support files, key OC4J configuration files, and configuration of the Web container. It also discusses initial considerations such as application root functionality, classpath functionality, security issues, and file naming conventions.

The following sections are included in this chapter:

- Configuring the OC4J JSP Container

- Configuring JSP Compilation in OC4J

- Configuring Runtime JSP Retranslation and Reloading in OC4J

- Key JSP-Related Support Files Provided with OC4J

Note: JSP pages will run with any standard browser supporting HTTP 1.0 or higher. The JDK or other Java environment in the user's Web browser is irrelevant, as any Java code in a JSP page is executed within the Web server.

## 3.1 Configuring the OC4J JSP Container

This section explains your options for configuring the OC4J JSP container, with a focus on configuring the container for JSP development. It includes the following topics:

- Summary of JSP Configuration Parameters

- Setting JSP Parameters in Application Server Control Console

- Setting JSP Parameters in the XML Configuration Files

### 3.1.1 Summary of JSP Configuration Parameters

A number of parameters for configuring the JSP container environment are available in OC4J. Table 3-1 summarizes the supported configuration parameters.

Parameters that are listed in the Application Server Control Console JSP Property column of this table can be set through the JSP Container Properties page of the Oracle Enterprise Manager 10g Application Server Control Console management interface provided with OC4J. See "Setting JSP Parameters in Application Server Control Console" for details.

Parameters that are not exposed through Application Server Control Console can be set directly in the `global-web-application.xml` configuration file, which is located in the `ORACLE_HOME/j2ee/home/config` directory by default. The JSP parameters persisted in this file are the default values inherited by all Web modules running within the OC4J server instance.

You can override any of the global settings for a specific Web application by modifying the Web module's `web-xml` or `orion-web.xml` deployment descriptors. Note that these files must be edited manually; Application Server Control Console does not provide any editing capabilities.

See "Setting JSP Parameters in the XML Configuration Files" for details on setting parameters in the `global-web-application.xml` or `orion-web.xml` files.

Table 3-1 JSP Environment Configuration Parameters

Application Server Control Console JSP Property | XML Parameter | Description
--- | --- | ---
(None) | `check_page_scope` `<init-param>` | Set to `true` to enable page-scope checking by `JspScopeListener` within OC4J. The default is `false`. See the Oracle Containers for J2EE JSP Tag Libraries and Utilities Reference for detailed information about the `JspScopeListener` utility.
(None) | `debug <init-param>` | Set to enable JSR-45 debugging support. Valid values are: `file`: Generates an SMAP file. `class`: Embeds the debugging in the generated class file. `none` (default): No debugging information is generated
Debug Mode | `debug_mode <init-param>` | Set to `true` to print the stack trace when certain runtime exceptions occur. The default is `false`. When this parameter is `false` and a file is not found, the full path of the missing file is not displayed. This is an important security consideration if you want to suppress the display of the physical file path when non-existent JSP files are requested.
External Resource for Static Content | `external_resource <init-param>` | Set to `true` to instruct the JSP translator to place static content within a JSP page into a Java resource file instead of into the generated page implementation class during translation. The default is `false`. The translator places the resource file into the same directory as generated class files. The resource file name is based on the JSP page name, with the `.res` suffix. The translation of `MyPage.jsp`, for example, would create `_MyPage.res` in addition to normal output. (The exact implementation might change in future releases.) If there is a lot of static content in a page, this technique will speed translation and may speed execution of the page. For more information, see "Managing Heavy Static Content or Tag Library Usage".
Extra Import Package List | `extra_imports <init-param>` | Use to import additional packages beyond the JSP defaults described in "Packages Imported By Default in OC4J". Note that in an XML file, the names can be either comma-delimited or space-delimited. Either of the following is valid:
    <init-param>
     <param-name>extra_imports</param-name>
     <param-value>java.util.* java.beans.*</param-value>
    </init-param>
or:
    <init-param>
     <param-name>extra_imports</param-name>
     <param-value>java.util.*,java.beans.*</param-value>
    </init-param>
Accept Duplicate Directive Attributes | `forgive_dup_dir_attr <init-param>` | Set to `true` to avoid JSP translation errors if you have duplicate settings with different values for the same directive attribute within a single JSP translation unit. The default is `false`.
Validate XML | `xml_validate` `<init-param>` | Set this boolean to `true` to perform XML validation of the `web.xml` file. The default is `false`, meaning that validation of `web.xml` is not performed.
When a JSP Changes | `main_mode` `<init-param>` | Use to specify whether JSP-generated classes are automatically reloaded or JSP pages are automatically retranslated when changes are made. If enabled, this feature allows new or modified JSPs to be loaded into the OC4J runtime, without requiring the Web application to be redeployed or restarted. See "Configuring Runtime JSP Retranslation and Reloading in OC4J" for additional information. Valid settings are: `recompile` (default): The container will check the timestamp of the JSP page, retranslate it and reload it if has been modified since it was last loaded. The functionality described for `reload` will also be executed. `reload`: The container will check the timestamp of classes generated by the JSP translator, such as page implementation classes, and reload any that have changed or been redeployed since they were last loaded. This might be useful, for example, when you deploy or redeploy compiled classes, but not JSP pages, from a development environment to a production environment. `justrun`: The container will not perform any timestamp checking, so there is no retranslation of JSP pages or reloading of JSP-generated Java classes. This is the most efficient mode for a production environment, where JSP pages are not expected to change frequently.
(None) | `no_tld_xml_validate` `<init-param>` | Set to `true` to not perform XML validation of TLD files. The default is `true`, meaning validation of the XML structure of TLD files is not performed.
(None) | `old_include_from_top` `<init-param>` | Set to `true` for page locations in nested `include` directives to be relative to the top-level page, for backward compatibility with behavior prior to Oracle9iAS Release 2. The default is `false`.
Precompile Check | `precompile_check` `<init-param>` | Set to `true` to check the HTTP request for a standard `jsp_precompile` setting. The default is `false`. If `precompile_check` is `true` and the request enables `jsp_precompile`, then the JSP page will be pretranslated only, without execution. Setting `precompile_check` to `false` improves performance and ignores any `jsp_precompile` setting in the request.
Reduce Code Size for Custom Tags | `reduce_tag_code` `<init-param>` | Set this boolean to `true` for further reduction in the size of generated code for custom tag usage. The default is `false`.
(None) | `req_time_introspection` `<init-param>` | Set this boolean to `true` to enable request-time JavaBean introspection whenever compile-time introspection is not possible. When compile-time introspection is possible and succeeds, however, there is no request-time introspection regardless of the setting of this flag. The default is `false`. As an example of a scenario for use of request-time introspection, assume a tag handler returns a generic `java.lang.Object` instance in `VariableInfo` of the tag-extra-info class during translation and compilation, but actually generates more specific objects during runtime. In this case, if `req_time_introspection` is enabled, the Web container will delay introspection until request-time. An additional effect of this flag is to allow a bean to be declared twice, such as in different branches of an `if..then..else` loop. Consider the example that follows. With the default `false` value of `req_time_introspection`, this code would cause a parse exception. With a `true` value, the code will work without error:
    <% if (cond) { %>
          <jsp:useBean id="foo" class="pkgA.Foo1" />
    <% } else { %>
          <jsp:useBean id="foo" class="pkgA.Foo2" />
    <% } %>
(None) | `setproperty_onerr_continue` `<init-param>` | Set this boolean to `true` to continue iterating over request parameters and setting corresponding bean properties when an error is encountered during `jsp:setProperty` when `property="*"`. The default is `false`.
Generate Static Text as Bytes | `static_text_in_chars` `<init-param>` | Set this boolean to `true` to instruct the JSP translator to generate static text in JSP pages as characters instead of bytes. The default is `false`. 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"); %>
The `false` default setting improves performance in outputting static text blocks.
(None) | `jsp-print-null <init-param>` | Set this flag to `false` to print an empty string instead of the string "null" for null output from a JSP page. The default is `true`.
Tags Reuse Default | `tags_reuse_default` `<init-param>` | Use this parameter to specify the mode for tag handler reuse, also known as tag pooling. Set to `compiletime` to enable the compile-time model of tag handler reuse in its basic mode. This is the default value. Set to `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. Set to `none` or `false` to disable tag handler reuse. You can override this value in any particular JSP page by setting the JSP page context attribute `oracle.jsp.tags.reuse` to a value of `true`. Set to `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`. Note that the `runtime` option and its equivalent, `true`, are deprecated in this release of OC4J.
JSP Page Timeout | `jsp-timeout` attribute of the root `<orion-web-app>` element | Specify an integer value greater than `0` indicating the amount of time, in seconds, after which a JSP page will be removed from memory unless it is requested. The default is `0`.
Persistent TLD Caching | `jsp-cache-tlds` attribute of the root `<orion-web-app>` element | OC4J provides a persistent caching feature for TLD files, with a global cache for TLD files in well-known tag library locations, as well as an application-level cache for any application that uses TLD caching. See "Enabling the TLD Caching Feature" for more information. By default, applications inherit the TLD caching value set at the global Web application level. However, if TLD caching is set at the application level, this value will override the global setting. Set to `standard` (default) to search the Web application's `/WEB-INF` directory for files with the `.tld` extension. Any TLD files found will be added to the list of TLD files inherited from the global Web application. Note that the `/WEB-INF/lib` and `/WEB-INF/classes` directories will not be searched for files with the `.tld` extension. This is the default value set at both the global and application levels as of release 10g Release 3 (10.1.3). Set to `on` to search all directories within the Web application for TLD files. Any found will be added to the list of TLD files inherited from the global Web application. Set to `off` to disable persistent TLD caching. The `/WEB-INF/lib` and `/WEB-INF/classes` directories will not be searched for files with the `.tld` extension.. Note that the value of this parameter has implications on the ability to set multiple well-known tag libraries, as described in the Tag Lib Locations (`jsp-taglib-locations`) notation below.
Tag Libraries Location List | `jsp-taglib- locations` attribute of the root `<orion-web-app>` element | As an extension of standard JSP "well-known URI" functionality described in the JSP specification, the OC4J JSP container supports the use of one or more well-known tag libraries - directories in which you can place tag library JAR files to allow the libraries to be shared across multiple Web applications. See "Specifying Well-Known Tag Library Locations" for more information. If TLD caching is disabled (`off)`, the well-known tag library location is limited to a single directory, which is `ORACLE_HOME/j2ee/home/jsp/lib/taglib` by default.If TLD caching is enabled (`standard` or `on`), you can specify one or more well-known tag librarylocations using a semicolon-delimited list of directory paths. Note that the `jsp-taglib-locations` attribute can be set only in `global-web-application.xml`, not in an individual Web module's `orion-web.xml` file. Otherwise, the locations will be ignored. Note that tag libraries placed in a well-known directory must be packaged in a JAR file.
(None) | `simple-jsp- mapping` attribute of the root `<orion-web-app>` element | Set to `true` if the "`*.jsp`" file extension is mapped to only the `oracle.jsp.runtimev2.JspServlet` front-end JSP servlet in the `<servlet>` elements of any Web descriptors affecting your application (`global-web-application.xml`, `web.xml`, and `orion-web.xml`). This will allow performance improvements for JSP pages. The default setting is `true`. If you must map the *.jsp extension to another servlet, set this parameter to `false`.

### 3.1.2 Setting JSP Parameters in Application Server Control Console

Oracle Enterprise Manager 10g Application Server Control Console is the administration console for an Oracle Application Server instance. It is installed by default with OC4J.

After logging in, access the JSP Container Properties page through Administration->JSP Properties links.

See the following for instructions on accessing the console:

- Accessing Application Server Control Console in Standalone OC4J

- Accessing Application Server Control Console in Oracle Application Server

#### 3.1.2.1 Accessing Application Server Control Console in Standalone OC4J

The Application Server Control Console is installed and configured automatically when you install the OC4J software. It is started by default when OC4J is started.

The console is accessed through the `default` Web site, which is configured to listen for HTTP requests on port 8888. To access the console, simply type the following URL in a Web browser:

    http://<hostname>:8888/em

#### 3.1.2.2 Accessing Application Server Control Console in Oracle Application Server

The Application Server Control Console is installed and configured automatically when you install OC4J using the Oracle Universal Installer.

The console is started with all other installed Oracle Application Server components using the OPMN command-line tool, `opmnctl`, which is installed in the `ORACLE_HOME/opmn/bin` directory on each server node. Start all installed components by issuing the following command:

    cd ORACLE_HOME/opmn/bin
    opmnctl startall

In a typical Oracle Application Server installation, all Web applications, including Application Server Control Console, are accessed through Oracle HTTP Server (OHS). Use the following URL to access the console:

    http://<ohs_host_address>:<port>/em

- `<ohs_host_address>` is the address of the OHS host machine.; for example, `server07.company.com`

- `<port>` is an HTTP listener port assigned to OHS by OPMN. Run the following `opmnctl` command on the OHS host machine to get the list of assigned listener ports from OPMN:

      opmnctl status -l

  Supply the port designated as `http1` in the OPMN status output as the value for `<port>`:

      HTTP_Server | HTTP_Server | 6412 | Alive | 1970872013 | 1
      6396 | 0:48:01 | https1:4443,http2:722,http1:7779

### 3.1.3 Setting JSP Parameters in the XML Configuration Files

In an OC4J development environment, you can set JSP configuration parameters directly in the global and module-specific configuration files.

For more information about `global-web-application.xml` and `orion-web.xml`, see the Oracle Containers for J2EE Servlet Developer's Guide.

#### 3.1.3.1 Setting Servlet Initialization Paramters

An instance of the front-end servlet class - `oracle.jsp.runtimev2.JspServlet` - is created for each Web module instantiated within an OC4J instance. Note that this servlet class is the only servlet supported by OC4J.

The default parameters used to initialize each servlet instance are specified in `<init-param>` subelements of the the `<servlet>` element within the `global-web-application.xml` configuration file.

Note that you can override any of the default servlet parameters at the Web application level by specifying corresponding `<init-param>` elements in the J2EE standard `web.xml` deployment descriptor installed with the Web module. The default location for this file is the `ORACLE_HOME/home/j2ee/<appName>/<webModuleName>/WEB-INF` directory.

The following example illustrates how to set `<init-param>` elements containing servlet initialization paramaters within the `<servlet>` element for the JSP front-end servlet. This sample enables the `precompile_check` flag, sets the `main_mode` flag to run without checking timestamps, and runs the Java compiler in verbose mode.

    <servlet>
       <servlet-name>jsp</servlet-name>
       <servlet-class>oracle.jsp.runtimev2.JspServlet</servlet-class>
       <init-param>
          <param-name>precompile_check</param-name>
          <param-value>true</param-value>
       </init-param>
       <init-param>
          <param-name>main_mode</param-name>
          <param-value>justrun</param-value>
       </init-param>
       <init-param>
          <param-name>javaccmd</param-name>
          <param-value>javac -verbose</param-value>
       </init-param>
    </servlet>

#### 3.1.3.2 Setting JSP Configuration Parameters

The parameters that control such functionality as JSP timeout and whether TLD caching is enabled are set as attributes of the root `<orion-web-app>` element in either `global-web-application.xml` or a Web module's `orion-web.xml` file. As with servlet initialization parameters, attributes set in `orion-web.xml` override the corresponding global definition in `global-web-application.xml`. The file for a deployed Web module is located in the `ORACLE_HOME/j2ee/home/application-deployments/<appName>/<webModuleName>` directory by default.

The following example shows how to set attributes of the root `<orion-web-app>` element within an XML file:

    <orion-web-app development="false" jsp-timeout="30" ... >
     ...
    </orion-web-app>

## 3.2 Configuring JSP Compila tion in OC4J

The Java compiler can be invoked to execute in-process - within in the same JVM process as OC4J - or out-of-process, within in a separate JVM process.

By default, OC4J uses out-of-process compilation, and the compiler is invoked as a separate executable. The default compiler used is `javac` from the Sun Microsystems JDK.

You can configure OC4J to use a different compiler, or to compile in-process, by adding a `<java-compiler>` element with desired settings to the OC4J `server.xml` file. See the Oracle Containers for J2EE Configuration and Administration Guide for details.

## 3.3 Configuring Runtime JSP Retranslation and Reloading in OC4J

OC4J allows new JavaServer Pages (JSPs) to be added to an actively running Web module - as well as existing JSPs to be modified - without requiring an application redeployment or restart.

To use this feature, simply drop a new or updated JSP into the appropriate directory within the exploded WAR file structure in the OC4J instance, which is `ORACLE_HOME/j2ee/<instance>/applications/<appName>/<webModuleName>/`. OC4J will translate the page and load (or reload) it into the runtime.

This feature is controlled by the `main_mode` servlet initialization parameter. Possible settings are:

- `recompile` (default) to retranslate JSP pages that have changed

- `reload` to reload classes that were generated by the Web container and have changed (such as page implementation classes)

- `justrun` to run without any retranslation or reloading, which may provide optimal performance in production environments

See "Summary of JSP Configuration Parameters" for additional information on the `main_mode` parameter.

Notes: Because of the usage of in-memory values for class file last-modified times, removing a page implementation class file from the file system will not by itself cause retranslation of the associated JSP page source. The page implementation class file will be regenerated when the memory cache is lost. This happens whenever a request is directed to this page after the server is restarted or after another page in this application has been retranslated. In OC4J, if a statically included page is updated (that is, a page included through an `include` directive), the page that includes it will be automatically retranslated the next time it is invoked.

For information about classloading behavior at the servlet layer, see the Oracle Containers for J2EE Servlet Developer's Guide.

## 3.4 Key JSP-Related Support File s Provided with OC4J

This section summarizes JAR and ZIP files that are used by the Web container or JSP applications. These files are installed on your system and into your classpath with OC4J.

- `ojsp.jar`: classes for the Web container

- `ojsputil.jar`: classes for tag libraries and utilities provided with OC4J

- `xmlparserv2.jar`: for XML parsing; required for the `web.xml` deployment descriptor and any tag library descriptor files and XML-related tag functionality

- `ojdbc14.jar` / `classes12.jar` / `classes111.jar`: for the Oracle JDBC drivers (for JDK 1.4, 1.2 or higher, respectively)

- `runtime12.jar` / `runtime12ee.jar` / `runtime11.jar` / `runtime.jar` / `runtime-nonoracle.jar`: for the Oracle SQLJ runtime (for JDK 1.2.x or higher with Oracle9i or higher JDBC, JDK 1.2.x or higher enterprise edition with Oracle9i or higher JDBC, or any JDK environment with non-Oracle JDBC drivers, respectively)

- `jndi.jar`: for JNDI service for lookup of resources such as JDBC data sources and Enterprise JavaBeans

- `jta.jar`: for the Java Transaction API

There are also files relating to particular areas, such as particular tag libraries. These include the following:

- `mail.jar`: for e-mail functionality within applications (standard `javax.mail` package)

- `activation.jar`: Java activation files for e-mail functionality

- `cache.jar`: for the Oracle Application Server Java Object Cache (which is the default back-end repository for the OC4J Web Object Cache)