Skip Headers
Oracle® Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide
10g Release 2 (10.1.2)
B14014-02
  Go To Documentation Library
Library
Go To Product List
Product
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

3 Getting Started

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

Before getting started, it is assumed that you can do the following on your system:

The following sections are included in this chapter:

Some Initial Considerations

The following sections discuss some considerations you should be aware of before you begin coding or using JSP pages:

Application Root Functionality

The servlet specification (since servlet 2.2) provides for each Web application to have its own servlet context. Each servlet context is associated with a directory path in the server file system, which is the base path for modules of the Web application. This is the application root. Each Web application has its own application root. For a Web application in a standard servlet environment, servlets, JSP pages, and static files such as HTML files are all based out of this application root. (By contrast, in servlet 2.0 environments the application root for servlets and JSP pages is distinct from the document root for static files.)

Note that a servlet URL has the following general form:

http://host:port/contextpath/servletpath

When a servlet context is created, a mapping is specified between the application root and the context path portion of a URL. The servlet path is defined in the application web.xml file. The <servlet> element within web.xml associates a servlet class with a servlet name. The <servlet-mapping> element within web.xml associates a URL pattern with a named servlet. When a servlet is executed, the servlet container will compare a specified URL pattern with known servlet paths, and pick the servlet path that matches. See the Oracle Application Server Containers for J2EE Servlet Developer's Guide for more information.

For example, consider an application with the application root /home/dir/mybankapp/mybankwebapp, which is mapped to the context path /mybank. Further assume the application includes a servlet whose servlet path is loginservlet. You can invoke this servlet as follows:

http://host:port/mybank/loginservlet

The application root directory name itself is not visible to the user.

To continue this example for an HTML page in this application, the following URL points to the file /home/dir/mybankapp/mybankwebapp/dir1/abc.html:

http://host:port/mybank/dir1/abc.html

For each servlet environment there is also a default servlet context. For this context, the context path is simply "/", which is mapped to the default servlet context application root. For example, assume the application root for the default context is /home/dir/defaultapp/defaultwebapp, and a servlet with the servlet path myservlet uses the default context. Its URL would be as follows:

http://host:port/myservlet

The default context is also used if there is no match for the context path specified in a URL.

Continuing this example for an HTML file, the following URL points to the file /home/dir/defaultapp/defaultwebapp/dir2/def.html:

http://host:port/dir2/def.html

Classpath Functionality

The JSP container uses standard locations on the Web server to look for translated JSP pages, as well as.class files and .jar files for any required classes such as JavaBeans. The container will find files in these locations without any Web server classpath configuration.

The locations for dependency classes are as follows and are relative to the application root:

/WEB-INF/classes/...
/WEB-INF/lib 

The location for JSP page implementation classes (translated pages) is as follows:

.../_pages/...

The /WEB-INF/classes directory is for individual Java .class files. You should store these classes in subdirectories under the classes directory, according to Java package naming conventions. For example, consider a JavaBean called LottoBean whose code defines it to be in the oracle.jsp.sample.lottery package. The JSP container will look for LottoBean.class in the following location relative to the application root:

/WEB-INF/classes/oracle/jsp/sample/lottery/LottoBean.class

The lib directory is for JAR (.jar) files. Because Java package structure is specified in the JAR file structure, the JAR files are all directly in the lib directory, not in subdirectories. As an example, LottoBean.class might be stored in lottery.jar, located as follows relative to the application root:

/WEB-INF/lib/lottery.jar

The _pages directory is under the J2EE home directory in OC4J and depends on the value of the jsp-cache-directory configuration parameter. See "JSP Translator Output File Locations" for information.


Important:

Implementation details, such as the default location of the _pages directory, are subject to change in future releases.

Runtime Retranslation or Reloading

During runtime, any retranslation of JSP pages or reloading of JSP page implementation classes is controlled by the JSP main_mode configuration parameter. Possible settings are recompile (default) to retranslate JSP pages that have changed, reload to reload classes that were generated by the JSP container and have changed (such as page implementation classes), or justrun to run without any timestamp-checking, for optimal performance in production environments. See "JSP Configuration Parameter Descriptions" for additional information.


Notes:

  • This discussion is not relevant for pretranslation scenarios.

  • The OC4J JSP container does not have its own classloader.

  • 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 Application Server Containers for J2EE Servlet Developer's Guide.

JSP Compilation Considerations

Java compilation can be either in-process, running in the same process as OC4J, or out-of-process, running in a separate process.

By default, OC4J as a whole uses out-of-process compilation, and the compiler is invoked as a separate executable. The default compiler executable is javac from the Sun Microsystems JDK; however, you can configure OC4J to use a different compiler. In OC4J standalone, you can accomplish this by adding a <java-compiler> element, with desired settings, to the OC4J server.xml file. In an Oracle Application Server environment, use Oracle Enterprise Manager 10g to change this configuration.

For improved JSP performance, however, the OC4J JSP container uses in-process compilation by default, assuming that the tools.jar file of the Sun Microsystems JDK is installed and in the classpath. With in-process compilation, the compiler class is invoked directly. You can use a <library> element in the server.xml file to ensure that tools.jar is in the classpath.

There are also two related JSP configuration parameters: use_old_compiler and javaccmd:

  • You can set use_old_compiler to false to force the JSP container to use the same compiler as the rest of OC4J—out-of-process compilation with javac by default, or compilation according to a <java-compiler> element in server.xml. The use_old_compiler flag is set to true by default if tools.jar is in the classpath, resulting in in-process compilation unless javaccmd is set.

  • If you want to use an out-of-process compiler, but not the compiler that the rest of OC4J uses, then set use_old_compiler to true and use the javaccmd parameter to specify the desired compiler. (The javaccmd parameter is ignored if use_old_compiler is set to false.)


    Notes:


JSP Security Considerations

With respect to application security, be aware that you should verify that the debug_mode parameter has its default false setting if you want to suppress the display of the physical file path when nonexistent JSP files are requested. This parameter is described in "JSP Configuration Parameter Descriptions".

JSP Performance Considerations

The following sections summarize JSP, OC4J, and Oracle Application Server features for performance optimization and monitoring:

Programmatic Considerations for Optimization

You might consider the following when creating your JSP pages:

  • Unbuffer JSP pages. By default, a JSP page uses an area of memory known as a page buffer. This buffer (8 KB by default) is required if the page uses dynamic globalization support content type settings, forwards, or error pages. If it does not use any of these features, you can disable the buffer in a page directive:

    <%@ page buffer="none" %>
    
    

    This will improve the performance of the page by reducing memory usage and saving the output step of copying the buffer.

  • Avoid using HTTP session objects if they are not required. If a JSP page does not require an HTTP session (essentially, does not require storage or retrieval of session attributes), then you can specify that no session is to be used. Specify this with a page directive such as the following:

    <%@ page session="false" %>
    
    

    This will improve the performance of the page by eliminating the overhead of session creation or retrieval.

    Note that although servlets by default do not use a session, JSP pages by default do use a session. For background information, see "Servlet Sessions".

  • In addition to general Oracle Application Server caching features such as OracleAS Web Cache and Java Object Cache, there are caching features that are specific to JSP pages and are available through custom tag libraries provided with OC4J. For a brief overview of these features—the JESI tag library and the Web Object Cache—see "Overview of Tags and API for Caching Support". For additional information, refer to the Oracle Application Server Containers for J2EE JSP Tag Libraries and Utilities Reference.

Configuration Optimizations

There are a number of JSP and OC4J configuration parameters that affect performance:

  • In a production environment, where JSP pages do not change, you should configure the JSP container to not check timestamps (which it would otherwise do to see if any pages require retranslation). You can specify this by setting the Oracle JSP configuration parameter main_mode to the value justrun. See "JSP Configuration Parameter Descriptions" for information about this parameter.

  • You can also improve performance with tag libraries by specifying that tag handler instances be reused within each JSP page. For optimal results, especially for JSP pages with very large numbers of custom tags, specify that the logic and patterns of tag handler reuse be determined at translation time instead of runtime. You can specify this through the Oracle JSP configuration parameter tags_reuse_default. See "Disabling or Enabling Runtime or Compile-Time Tag Handler Reuse".

  • There are a number of additional Oracle JSP configuration parameters that can affect performance, either favorably or unfavorably. See "JSP Configuration Parameter Descriptions" for information about check_page_scope, precompile_check, reduce_tag_code, and static_text_in_chars.

  • Features have been added to make tag library usage more efficient. The key feature is persistent caching for tag library descriptor (TLD) files, which you can enable through the OC4J configuration parameter jsp-cache-tlds. See "Oracle Extensions for Tag Library Sharing and Persistent TLD Caching".

  • The OC4J configuration parameters simple-jsp-mapping and enable-jsp-dispatcher-shortcut can significantly affect performance. See "JSP-Related OC4J Configuration Parameter Descriptions" for information about these parameters.

The ojspc Utility for Pretranslation

You might consider using the ojspc utility to pretranslate JSP pages. This avoids the performance cost of translating pages as they are first accessed by users. See "JSP Pretranslation" for additional discussion of the advantages of pretranslation. See "The ojspc Pretranslation Utility" for details about the utility itself.

Additional OC4J and Oracle Application Server Performance Features

Note the following OC4J and Oracle Application Server features for performance optimization and monitoring:

Default Package Imports

Beginning with Oracle9iAS Release 2 (9.0.3), the OC4J JSP container by default imports the following packages into any JSP page, in accordance with the JSP specification. No page directive import settings are required:

javax.servlet.*
javax.servlet.http.*
javax.servlet.jsp.*

In earlier releases, the following packages were also imported by default:

java.io.*
java.util.*
java.lang.reflect.*
java.beans.*

The default list of packages to import was reduced to minimize the chance of a conflict between any unqualified class name you might use and a class by the same name in any of the imported packages.

However, this might result in migration problems for applications you have used with previous versions of OC4J. Such applications might no longer compile successfully. If you need imports beyond the default list, you have two choices:

JSP File Naming Conventions

The file name extension .jsp for JSP pages is required by the servlet specification. The servlet 2.3 specification does not, however, distinguish between complete pages that are independently translatable and page segments that are not (such as files brought in through an include directive).

The JSP 1.2 specification recommends the following:

  • Use the .jsp extension for top-level pages, dynamically included pages, and pages that are forwarded to—pages that are translatable on their own.

  • Do not use .jsp for page segments brought in through include directives—files that are not translatable on their own. No particular extension is mandated for such files, but .jsph, .jspf, or .jsf is recommended.

Removal of tools.jar from OC4J Standalone

The OC4J 9.0.3 standalone implementation provided the tools.jar file from the Sun Microsystems JDK 1.3.1. This file includes the java front-end executable and javac compiler executable, for example, among many other components.

The OC4J 10.1.2 standalone implementation no longer provides the tools.jar file. Therefore, you must install a JDK that OC4J supports before installing OC4J itself. The JDK versions that OC4J supports for the OC4J 10.1.2 implementation are JDK 1.3.1 (for OC4J standalone only) and JDK 1.4. Oracle Application Server 10g Release 2 (10.1.2) includes JDK 1.4, so you should typically use this JDK version for OC4J standalone as well. However, there are migration issues to consider, particularly the JDK 1.4 requirement that all invoked classes must be in packages. See "JDK 1.4 Considerations: Cannot Invoke Classes Not in Packages" below.


Notes:

OC4J standalone uses javac from the same directory in which java is accessed through the command "java -jar oc4j.jar", ensuring use of the appropriate javac version.

JDK 1.4 Considerations: Cannot Invoke Classes Not in Packages

Among the migration considerations in moving to a Sun Microsystems JDK 1.4 environment, which is the environment that is shipped with Oracle Application Server 10g Release 2 (10.1.2), there is one of particular importance to servlet and JSP developers.

As stated by Sun Microsystems, "The compiler now rejects import statements that import a type from the unnamed namespace." This was to address security concerns and ambiguities with previous JDK versions. Essentially, this means that you cannot invoke a class (a method of a class) that is not within a package. Any attempt to do so will result in a fatal error at compilation time.

This especially affects JSP developers who invoke JavaBeans from their JSP pages, as such beans are often outside of any package (although the JSP 2.0 specification now requires beans to be within packages, in order to satisfy the new compiler requirements). Where JavaBeans outside of packages are invoked, JSP applications that were built and executed in an OC4J 9.0.3 / JDK 1.3.1 environment will no longer work in an OC4J 10.1.2 / JDK 1.4 environment.

Until you update your application so that all JavaBeans and other invoked classes are within packages, you can avoid this issue by reverting back to a JDK 1.3.1 environment for OC4J standalone. Note that JDK 1.3.x is not supported in a full Oracle Application Server 10.1.2 environment.


Notes:

  • The javac -source compiler option is intended to allow JDK 1.3.1 code to be processed seamlessly by the JDK 1.4 compiler, but this option does not account for the "classes not in packages" issue.

  • Only the JDK 1.3.1 and JDK 1.4 compilers are supported and certified by OC4J. It is possible to specify an alternative compiler by adding a <java-compiler> element to the server.xml file, and this might provide a workaround for the "classes not in packages" issue, but no other compilers are certified or supported by Oracle for use with OC4J. (Furthermore, do not update the server.xml file directly in an Oracle Application Server environment. Use the Oracle Enterprise Manager 10g.)


For more information about the "classes not in packages" issue and other JDK 1.4 compatibility issues, refer to the following Web site:

http://java.sun.com/j2se/1.4/compatibility.html

In particular, click the link "Incompatibilities Between Java 2 Platform, Standard Edition, v1.4.0 and v1.3".

Key Support Files Provided with OC4J

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

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

JSP Configuration in OC4J

The following sections cover topics regarding configuration of the JSP environment:

JSP Container Setup

The JSP container is appropriately preconfigured in OC4J. The following settings appear in the OC4J global-web-application.xml file to map the name of the front-end JSP servlet, and to map the appropriate file name extensions for JSP pages:

<orion-web-app ... >
   ...
   <web-app>
       ...
      <servlet>
         <servlet-name>jsp</servlet-name>
         <servlet-class>oracle.jsp.runtimev2.JspServlet</servlet-class>
         ...
            init_params
         ...
      </servlet>
      ...
      <servlet-mapping>
         <servlet-name>jsp</servlet-name>
         <url-pattern>/*.jsp</url-pattern>
      </servlet-mapping>
      <servlet-mapping>
          <servlet-name>jsp</servlet-name>
          <url-pattern>/*.JSP</url-pattern>
       </servlet-mapping>

      ...
   </web-app>
   ...
</orion-web-app>

See the Oracle Application Server Containers for J2EE Servlet Developer's Guide for more information about the global-web-application.xml file.

JSP Configuration Parameters

The JSP front-end servlet in OC4J, oracle.jsp.runtimev2.JspServlet, supports a number of configuration parameters to control JSP operation. This section describes those parameters. The following subsections provide a summary table, detailed descriptions, and documentation of how to set them in the OC4J global-web-application.xml or orion-web.xml file:

JSP Configuration Parameter Summary Table

Table 3-1 summarizes the configuration parameters supported by JspServlet. For each parameter, the table notes any equivalent ojspc translation options for pages you are pretranslating, and whether the parameter is for runtime or compile-time use.


Notes:

See "Option Descriptions for ojspc" for information about any ojspc options.

Table 3-1 JSP Configuration Parameters, OC4J Environment

Parameter Related ojspc Option Description Default Runtime / Compile- Time

check_page_scope

(None)

Set this boolean to true to enable page-scope checking by JspScopeListener (OC4J only).

Important: JspScopeListener is deprecated in the OC4J 10.1.2 implementation, and will be desupported in future implementations.

false

Runtime

debug_mode

(None)

Set this boolean to true to print the stack trace when a runtime exception occurs.

false

Runtime

emit_debuginfo

(None)

Set this boolean to true to generate a line map to the original .jsp file for debugging (for development).

false

Compile- time

external_resource

-extres

Set this boolean to true to place all static content of the page into a separate Java resource file during translation.

false

Compile- time

extra_imports

-extraImports

Use this to add imports beyond the JSP defaults.

null

Compile- time

forgive_dup_dir_attr

-forgiveDupDirAttr

Set this boolean to true to avoid JSP 1.2 translation errors if you have duplicate settings for the same directive attribute within a single JSP translation unit.

false

Compile- time

javaccmd

-noCompile

Use this if you want to specify a javac command line or an alternative Java compiler. If you use this option, the compiler will be run in a separate process from OC4J. The javaccmd parameter is ignored if use_old_compiler is set to false.

null

Compile- time

main_mode

(None)

This determines whether JSP-generated classes are automatically reloaded or JSP pages are automatically retranslated, in case of changes. Possible settings are justrun, reload, and recompile.

recompile

Runtime

no_tld_xml_validate

-noTldXmlValidate

Set this boolean to true to not perform XML validation of TLD files. By default, validation of TLD files is performed.

false

Compile- time

old_include_from_top

-oldIncludeFromTop

Set this boolean 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.

false

Compile- time

precompile_check

(None)

Set this boolean to true to check the HTTP request for a standard jsp_precompile setting.

false

Runtime

reduce_tag_code

-reduceTagCode

Set this boolean to true for further reduction in the size of generated code for custom tag usage.

false

Compile- time

req_time_introspection

-reqTimeIntrospection

Set this boolean to true to enable request-time JavaBean introspection whenever compile-time introspection is not possible.

false

Compile- time

setproperty_onerr_continue

(None)

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="*".

false

Runtime

static_text_in_chars

-staticTextInChars

Set this boolean to true to instruct the JSP translator to generate static text in JSP pages as characters instead of bytes.

false

Compile- time

tags_reuse_default

-tagReuse

This specifies the mode for JSP tag handler reuse: runtime for the runtime model, compiletime or compiletime_with_release for the compile-time model, or none to disable tag handler reuse.

runtime

Either

use_old_compiler

(None)

Set this boolean to false to force the JSP container to use the same compiler as the rest of OC4J. Otherwise, by default, OC4J uses in-process compilation (or compilation according to the javaccmd setting, if applicable).

true, if tools.jar in classpath

Compile- time

well_known_taglib_loc

(None)

If TLD caching is not enabled, this specifies a directory where tag library JAR files can be placed for sharing across multiple Web applications. The default location is j2ee/home/jsp/lib/taglib under the ORACLE_HOME directory.

(See description column.)

Compile- time

xml_validate

-xmlValidate

Set this boolean to true to perform XML validation of the web.xml file. By default, validation of web.xml is not performed.

false

Compile- time


JSP Configuration Parameter Descriptions

This section describes the JSP configuration parameters for OC4J in more detail.

check_page_scope

(boolean; default: false)

For OC4J environments, set this parameter to true to enable Oracle-specific page-scope checking by the JspScopeListener utility. It is false by default for performance reasons.

This parameter is not relevant for non-OC4J environments, where the Oracle-specific implementation is not used and you must use the checkPageScope custom tag for JspScopeListener page-scope functionality. See the Oracle Application Server Containers for J2EE JSP Tag Libraries and Utilities Reference for detailed information about the JspScopeListener utility.


Important:

JspScopeListener is deprecated in the OC4J 10.1.2 implementation, and will be desupported in future implementations.

debug_mode

(boolean; default: false)

Use the true setting to print a stack trace whenever a runtime exception occurs. A false setting disables this feature.


Important:

When debug_mode 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.

emit_debuginfo

(boolean; default: false)

During development, set this flag to true to instruct the JSP translator to generate a line map to the original .jsp file for debugging. Otherwise, lines will be mapped to the generated page implementation class .java file.


Note:

Oracle JDeveloper enables emit_debuginfo.

external_resource

(boolean; default: false)

Set this flag to true to instruct the JSP translator 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, with the .res suffix. With Oracle Application Server 10g Release 2 (10.1.2), translation of MyPage.jsp, for example, would create _MyPage.res in addition to normal output. (The exact implementation might change in future releases.)

The translator places the resource file into 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. For more information, see "Workarounds for Large Static Content or Significant Tag Library Usage".


Note:

For pretranslating pages, the ojspc -extres option is equivalent.

extra_imports

(import list; default: null)

As described in "Default Package Imports", the default list of packages that are imported into each JSP page is smaller than the list prior to the OC4J 9.0.3 implementation. 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 extra_imports configuration parameter. See "Setting JSP Configuration Parameters in OC4J" for general syntax, and be aware that the names can be either comma-delimited or space-delimited. Either of the following is okay, for example:

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

Notes:

  • For pretranslating pages, the ojspc -extraImports option is equivalent.

  • As an alternative to using extra_imports, you can use global includes. See "Oracle JSP Global Includes".


forgive_dup_dir_attr

(boolean; default: false)

Set this boolean to true to avoid translation errors in a JSP 1.2 (or higher) environment 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 forgive_dup_dir_attr parameter for backward compatibility.


Note:

For pretranslating pages, the ojspc -forgiveDupDirAttr option is equivalent.

javaccmd

(compiler executable and options; default: null)

If use_old_compiler is set to true, you can use javaccmd, typically during development, to specify a Java compiler command line for use during JSP translation. This would be useful if you want to specify particular javac settings or an alternative compiler (optionally including command-line settings). You can fully specify the path for the executable, or specify only the executable and let the JSP container look for it in the system path.

For example, set javaccmd to the value javac -verbose to run the compiler in verbose mode.

Be aware of the following:

  • The javaccmd is ignored if use_old_compiler is set to false.

  • Using javaccmd results in the compiler running in a separate process from OC4J.

See "JSP Compilation Considerations" for related information.


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.

  • For pretranslating pages, the ojspc -noCompile option allows similar functionality. It results in no compilation by javac, so you can compile the translated classes manually through any desired compiler.


main_mode

(mode for reloading or retranslation; default: recompile)

This is a flag to direct the mode of operation of the JSP container, particularly for automatic retranslation of JSP pages and reloading of JSP-generated Java classes that have changed.

Here are the supported settings:

  • justrun: The runtime dispatcher will not perform any timestamp checking, so there is no retranslation of JSP pages or reloading of JSP-generated Java classes. This mode is the most efficient mode for a deployment environment, where code will not change.

  • reload: The dispatcher 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 page source, from a development environment to a production environment.

  • recompile (default): The dispatcher will check the timestamp of the JSP page, retranslate it and reload it if has been modified since loading, and execute reload functionality as well.

no_tld_xml_validate

(boolean; default: false)

Set this to true to disable XML validation of the 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:

For pretranslating pages, the ojspc -noTldXmlValidate option is equivalent.

old_include_from_top

(boolean; default: false)

This is for backward compatibility with Oracle JSP versions prior to Oracle9iAS Release 2, for functionality of include directives. If this parameter is set to true, page locations in nested include directives are relative to the top-level page. If it is set to false, page locations are relative to the immediate parent page, which complies with the JSP specification.


Note:

For pretranslating pages, the ojspc -oldIncludeFromTop option is equivalent.

precompile_check

(boolean; default: false)

Set this to true to check the HTTP request for a standard jsp_precompile setting. 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.

For more information about jsp_precompile, see "Standard JSP Pretranslation without Execution", and the Sun Microsystems JavaServer Pages Specification.

reduce_tag_code

(boolean; default: false)

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


Note:

For pretranslating pages, the ojspc -reduceTagCode option is equivalent.

req_time_introspection

(boolean; default: false)

A true setting enables 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 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 request-time (runtime). In this case, if req_time_introspection 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. 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" /> 
<% } %>


Note:

For pretranslating pages, the ojspc -reqTimeIntrospection option is equivalent.

setproperty_onerr_continue

(boolean; default: false)

Set this boolean to true to continue iterating over request parameters and setting corresponding bean properties when an error is encountered during a jsp:setProperty statement when property="*".

See the description of jsp:setProperty, under "Standard Actions: JSP Tags", for related information.

static_text_in_chars

(boolean; default: false)

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

(See "Dynamic Content Type Settings" for related information.)

The false default setting improves performance in outputting static text blocks.


Note:

For pretranslating pages, the ojspc -staticTextInChars option is equivalent.

tags_reuse_default

(mode for tag handler reuse; default: runtime)

Use this parameter 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 tags_reuse_default value to compiletime or compiletime_with_release.

    • If you switch from the runtime model (tags_reuse_default value of runtime) to the compile-time model (tags_reuse_default 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 runtime, and a setting of false is supported and is equivalent to none.

    • For pretranslating pages, the ojspc -tagReuse option is equivalent.


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

use_old_compiler

(boolean; default: true if tools.jar is in classpath)

You can set use_old_compiler to false to force the JSP container to use the same compiler as the rest of OC4J—out-of-process compilation with javac by default, or compilation according to a <java-compiler> element in server.xml. The use_old_compiler flag is set to true by default if tools.jar is in the classpath, resulting in in-process compilation unless javaccmd is set. (You can use a <library> element in the server.xml file to ensure that tools.jar is in the classpath.)

See "JSP Compilation Considerations" for related information.


Notes:

  • If tools.jar is not in the classpath, then use_old_compiler is forced to a false setting.

  • If you want to use an out-of-process compiler, but not the compiler that the rest of OC4J uses, then set use_old_compiler to true and use the javaccmd parameter to specify the desired compiler.


well_known_taglib_loc

(location for shared tag libraries; default: see description)

If persistent TLD caching is not enabled, you can use well_known_taglib_loc to specify a single directory to use as the "well-known location" where tag library JAR files can be placed for sharing across multiple Web applications. See "TLD Caching and Well-Known Tag Library Locations" for important related information.

Specify a relative directory location. This would be under ORACLE_HOME if ORACLE_HOME is defined, or under the current directory, from which the OC4J process was started, if ORACLE_HOME is not defined. The default value is as follows:

  • ORACLE_HOME/j2ee/home/jsp/lib/taglib/ if ORACLE_HOME is defined.

or:

  • ./jsp/lib/taglib if ORACLE_HOME is not defined.

xml_validate

(boolean; default: false)

Set this to true to enable XML validation of the application web.xml file. Because the Tomcat reference implementation does not perform XML validation, xml_validate is false by default.


Note:

For pretranslating pages, the ojspc -xmlValidate option is equivalent.

Setting JSP Configuration Parameters in OC4J

In an OC4J standalone development environment, you can set JSP configuration parameters directly in global-web-application.xml, web.xml, or orion-web.xml, inside the <servlet> element for the JSP front-end servlet. In the portion of global-web-application.xml shown in "JSP Container Setup", the settings would go where the init_params placeholder appears.


Note:

In an Oracle Application Server production environment, use Enterprise Manager for configuration. You can use the Application Server Control Console Web Module Advanced Properties Page in Enterprise Manager to update the global-web-application.xml or orion-web.xml file. This Application Server Control Console is discussed in the Oracle Application Server Containers for J2EE Servlet Developer's Guide.

The following example lists <servlet> element and subelement settings 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>

You can override any settings in the global-web-application.xml file with settings in the web.xml file for a particular application, and you can make deployment-specific overrides of web.xml settings through settings in orion-web.xml. For information about global-web-application.xml and orion-web.xml, see the Oracle Application Server Containers for J2EE Servlet Developer's Guide.

OC4J Configuration Parameters for JSP

There are also OC4J configuration parameters—as opposed to parameters for the JspServlet front-end servlet of the JSP container—which affect JSP pages. This section documents JSP-related attributes of the root <orion-web-app> element of the OC4J global-web-application.xml file or orion-web.xml file. For more information about these files, see the Oracle Application Server Containers for J2EE Servlet Developer's Guide.

JSP-Related OC4J Configuration Parameter Descriptions

The following <orion-web-app> attributes, in the OC4J global-web-application.xml file or orion-web.xml file, affect JSP performance and functionality:

  • jsp-print-null: 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".

  • jsp-timeout: Specify an integer value, in seconds, after which any JSP page will be removed from memory if it has not been requested. This frees up resources in situations where some pages are called infrequently. The default value is 0, for no timeout.

  • jsp-cache-directory: The JSP cache directory is used as a base directory for output files from the JSP translator. (See "JSP Translator Output File Locations".) It is also used as a base directory for application-level TLD caching. (See "TLD Cache Features and Files".) The default value is "./persistence", relative to the deployment directory of the application.

  • jsp-cache-tlds: This flag indicates whether persistent TLD caching is enabled for JSP pages. TLD caching is implemented both at a global level, for TLD files in "well-known" tag library locations, and at an application level, for TLD files under the WEB-INF directory. Use a "true" or "on" setting, which is the default, to search for TLD files among all application files. A setting of "standard" searches for TLD files only in /WEB-INF and subdirectories other than /WEB-INF/classes or /WEB-INF/lib. A setting of "false" or "off" disables this feature. Well-known locations are according to the jsp-taglib-locations attribute. See "TLD Caching and Well-Known Tag Library Locations" for related information.

  • jsp-taglib-locations: If persistent TLD caching is enabled, through the jsp-cache-tlds attribute, you can use jsp-taglib-locations to specify a semicolon-delimited list of one or more directories to use as "well-known" locations. Tag library JAR files can be placed in these locations for sharing across multiple Web applications and for TLD caching. See "TLD Caching and Well-Known Tag Library Locations" for important related information.

    You can specify any combination of absolute directory paths or relative directory paths. Relative paths would be under ORACLE_HOME if ORACLE_HOME is defined, or under the current directory, from which the OC4J process was started, if ORACLE_HOME is not defined. The default value is as follows:

    • ORACLE_HOME/j2ee/home/jsp/lib/taglib/ if ORACLE_HOME is defined.

    or:

    • ./jsp/lib/taglib if ORACLE_HOME is not defined.


      Important:

      Use the jsp-taglib-locations attribute only in global-web-application.xml, not in orion-web.xml.

  • simple-jsp-mapping: Set this 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 "false".

  • enable-jsp-dispatcher-shortcut: A "true" setting, which is the case by default, results in significant performance improvements by the OC4J JSP container, especially in conjunction with a "true" setting for the simple-jsp-mapping attribute. This is particularly true for JSP pages with numerous jsp:include statements. Use of the "true" setting assumes, however, that if you define JSP files with <jsp-file> elements in web.xml, then you have corresponding <url-pattern> specifications for those files, as in the following example:

    <servlet>
       <servlet-name>foo</servlet-name>
       <jsp-file>bar.jsp</jsp-file>
    </servlet>
    ...
    <servlet-mapping>
       <servlet-name>foo</servlet-name>
       <url-pattern>/mypath</url-pattern>
    </servlet-mapping>
    
    

    If you use <jsp-file> without a corresponding <url-pattern> setting (which is not a typical scenario), then set enable-jsp-dispatcher-shortcut="false".


    Note:

    The autoreload-jsp-pages and autoreload-jsp-beans attributes of the <orion-web-app> element are not supported by the OC4J JSP container in Oracle Application Server 10g Release 2 (10.1.2). You can use the JSP main_mode configuration parameter, described in "JSP Configuration Parameter Descriptions", for functionality equivalent to that of autoreload-jsp-pages.

Setting JSP-Related OC4J Configuration Parameters

To set configuration values that would apply to all applications in an OC4J instance, use the <orion-web-app> element of the OC4J global-web-application.xml file. To set configuration values for a particular application deployment, overriding settings in global-web-application.xml, use the <orion-web-app> element of the deployment-specific orion-web.xml file.

Here is an example:

<orion-web-app ... jsp-print-null="false" ... >
...
</orion-web-app>

Note that the <orion-web-app> element has numerous attributes and subelements. For a complete discussion, see the Oracle Application Server Containers for J2EE Servlet Developer's Guide.


Note:

Update these files directly only if you are in an OC4J standalone environment. In an Oracle Application Server environment, use Enterprise Manager for configuration. In Oracle Application Server 10g Release 2 (10.1.2), JSP <orion-web-app> attributes are not yet supported by the Application Server Control Console JSP Properties Page in Enterprise Manager, but you can make settings through the Application Server Control Console Web Module Advanced Properties Page. This page is described in the Oracle Application Server Containers for J2EE Servlet Developer's Guide.

Key OC4J Configuration Files

Be aware of the following key configuration files in the OC4J environment.

Global files for all OC4J applications, in the OC4J configuration files directory:

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

In addition to the global application.xml file, there is a standard application.xml file, and optionally an orion-application.xml file, for each application. These files are in the application EAR file.

Also, in an application WAR file, which is inside the application EAR file, there is a standard web.xml file and optionally an orion-web.xml file. These are for application-specific and deployment-specific configuration settings, overriding global-web-application.xml settings or providing additional settings as appropriate. The global-web-application.xml and orion-web.xml files support the same elements, which is a superset of those supported by the web.xml file.

If the orion-application.xml and orion-web.xml files are not present in the archive files, they will be generated during initial deployment according to settings in the global-web-application.xml file.

For additional information, see "Overview of EAR/WAR Deployment". For complete information about the use of these files, see the Oracle Application Server Containers for J2EE User's Guide and the Oracle Application Server Containers for J2EE Servlet Developer's Guide.

JSP Configuration in Oracle Enterprise Manager 10g

In an Oracle Application Server environment, such as for production deployment, use Enterprise Manager for OC4J configuration. This includes configuration of the front-end JSP servlet for the OC4J JSP container.

Oracle Enterprise Manager 10g Application Server Control Console is the administration console for an Oracle Application Server instance. It enables you to monitor real-time performance, manage Oracle Application Server components and instances, and configure these components and instances. This includes any instances of OC4J. In particular, Application Server Control Console includes the JSP Properties Page. Application Server Control Console comes with your Oracle Application Server installation. Log in as the ias_admin user.

Application Server Control Console JSP Properties Page

Figure 3-1 shows the key portion of the Application Server Control Console JSP Properties Page for an OC4J instance.

Figure 3-1 Application Server Control Console JSP Properties Page

Description of Figure 3-1  follows
Description of "Figure 3-1 Application Server Control Console JSP Properties Page"

When you first access an Oracle Application Server instance through Application Server Control Console in Enterprise Manager, you reach the Oracle Application Server Instance Home Page. You can drill down to the JSP Properties Page as follows:

  1. From the Oracle Application Server Instance Home Page, select the name of an OC4J instance in the System Components table. Things brings you to the OC4J Home Page for the OC4J instance.

  2. From the OC4J Home Page, click Administration. This brings you to the OC4J Administration Page.

  3. From the OC4J Administration Page, click JSP Container Properties under Instance Properties. This brings you to the JSP Properties Page

For further information about using Enterprise Manager, see the Oracle Application Server Containers for J2EE Servlet Developer's Guide for an overview of Web application deployment and configuration or the Oracle Application Server Containers for J2EE User's Guide for information about any OC4J-related deployment and configuration.

Configuration Parameters Supported by the JSP Properties Page

Table 3-2 shows the correspondence between JSP container properties shown in the Application Server Control Console JSP Properties Page in Enterprise Manager, and configuration parameters of the JSP container front-end servlet as described in "JSP Configuration Parameters". See that section for the meanings of the settings.

Possible settings are shown with defaults in bold. Note that Application Server Control Console defaults are appropriate for a production environment, so are not necessarily the same as defaults otherwise, which are appropriate for a development environment.

Table 3-2 Application Server Control Console Properties, JSP Parameters

Application Server Control Console JSP Container Property Possible Settings JSP Configuration Parameter Possible Settings

Debug Mode

No

Yes

debug_mode

false

true

External Resource for Static Content

No

Yes

external_resource

false

true

Generate Static Text as Bytes

No

Yes

static_text_in_chars

false

true

Tags Reuse Default

No

Yes

tags_reuse_default

none

runtime

Reduce Code Size for Custom Tags

No

Yes

reduce_tag_code

false

true

Emit Debug Info

No

Yes

emit_debuginfo

false

true

When a JSP Page Changes

Recompile JSP

Reload Classes

Do Nothing

main_mode

recompile

reload

justrun

Precompile Check

No

Yes

precompile_check

false

true

Validate XML

No

Yes

xml_validate

false

true

Alternate Java Compiler

Command string (null by default)

javaccmd

Command string (null by default)



Notes:

  • As of Oracle Application Server 10g Release 2 (10.1.2), Application Server Control Console supports only runtime (not compile-time) tag handler reuse. In other words, tags_reuse_default settings of compiletime or compiletime_with_release are not yet directly supported through Application Server Control Console.

  • The Application Server Control Console JSP container property "Generate Static Text as Bytes" corresponds to the JSP configuration parameter static_text_in_chars, but with opposite orientation. Their defaults are equivalent.


Configuration Parameters Not Supported by the JSP Properties Page

As of Oracle Application Server 10g Release 2 (10.1.2), the following configuration parameters are not yet supported through the Application Server Control Console JSP Properties Page:

  • JSP front-end servlet parameters: check_page_scope, extra_imports, forgive_dup_dir_attr, no_tld_xml_validate, old_include_from_top, req_time_introspection, and well_known_taglib_loc.

  • JSP-related attributes of the <orion-web-app> element in global-web-application.xml or orion-web.xml: jsp-print-null and jsp-timeout, jsp-cache-directory, jsp-cache-tlds, jsp-taglib-locations, simple-jsp-mapping, and enable-jsp-dispatcher-shortcut.

Instead, you must update them in orion-web.xml or other appropriate XML file (such as web.xml or global-web-application.xml). Edit orion-web.xml or global-web-application.xml through the Application Server Control Console Web Module Advanced Properties Page, as described in the Oracle Application Server Containers for J2EE Servlet Developer's Guide. Also see "Setting JSP Configuration Parameters in OC4J" and "Setting JSP-Related OC4J Configuration Parameters" for related information.