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 Compilation 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 Files 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)