Oracle JavaServer Pages Developer's Guide and Reference
Release 8.1.7

Part Number A83726-01

Library

Product

Contents

Index

Go to previous page Go to beginning of chapter Go to next page

OracleJSP Configuration

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

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

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

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

OracleJSP Configuration Parameters (Non-OSE)

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

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

Configuration Parameters Summary Table

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

Be aware of the following:

Configuration Parameter Descriptions

This section describes the OracleJSP configuration parameters in more detail.

alias_translation

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

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

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

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

bypass_source

(boolean; OracleJSP default: false)

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

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

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


Notes:

  • The bypass_source option is useful in deployment environments that have the generated classes only, not the source. (For related discussion, see "Deployment of Binary Files Only".)

  • Oracle JDeveloper enables bypass_source so that you can translate and run a JSP page before you have saved the JSP source to a file.

 

classpath

(fully qualified path; OracleJSP default: null)

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

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

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

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


Notes:

  • OracleJSP runtime automatic class reloading applies only to classes in the OracleJSP classpath. This includes paths specified through this classpath parameter. (See "Dynamic Class Reloading" for information about this feature.)

  • When you are pre-translating pages to run in the Oracle Servlet Engine, the ojspc -addclasspath option offers some related, though different, functionality. See "Option Descriptions for ojspc".

 

developer_mode

(boolean; OracleJSP default: true)

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

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

emit_debuginfo

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

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


Notes:

  • Oracle JDeveloper enables emit_debuginfo.

  • When you are pre-translating pages to run in the Oracle Servlet Engine, the ojspc -debug option is equivalent. See "Option Descriptions for ojspc".

 

external_resource

(boolean; OracleJSP default: false)

Set this flag to true to instruct the OracleJSP translator to place generated static content (the Java print commands that output static HTML code) into a Java resource file instead of into the service method of the generated page implementation class.

The resource file name is based on the JSP page name. For release 8.1.7, it will be the same name as the JSP name, but with the .res suffix. (Translation of MyPage.jsp, for example, would create MyPage.res in addition to normal output. The exact implementation may change in future releases, however.)

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

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


Note:

When you are pre-translating pages to run in the Oracle Servlet Engine, the ojspc -extres option is equivalent.

The ojspc -hotload option is also relevant, performing the -extres functionality along with additional steps to allow hotloading into Oracle8i. See "Option Descriptions for ojspc".  


javaccmd

(compiler executable; OracleJSP default: null)

This parameter is useful in either of the following circumstances:

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

The following javaccmd setting enables the javac -verbose option:

javaccmd=javac -verbose

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


Notes:

  • The specified Java compiler must be installed in the classpath and any front-end utility (if applicable) must be installed in the system path.

  • When you are pre-translating pages to run in the Oracle Servlet Engine, the ojspc -noCompile option allows similar functionality. It results in no compilation by javac, so you can compile the translated classes manually using your desired compiler. See "Option Descriptions for ojspc".

 

page_repository_root

(fully qualified directory path; OracleJSP default: null)

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

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

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


Notes:

  • The specified directory, _pages subdirectory, and any appropriate subdirectories under these are created automatically if they do not already exist.

  • When you are pre-translating pages to run in the Oracle Servlet Engine, the ojspc options -srcdir and -d provide related functionality. See "Option Descriptions for ojspc".

 

session_sharing

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

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

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

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

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

sqljcmd

(SQLJ translator executable; OracleJSP default: null)

This parameter is useful in any of the following circumstances:

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

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

Following is an example of a sqljcmd setting:

sqljcmd=sqlj -user=scott/tiger -ser2class

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


Notes:

  • Appropriate SQLJ files must be in the classpath, and any front-end utility (such as sqlj in the example) must be in the system path. (For Oracle SQLJ, translator.zip and the appropriate SQLJ runtime ZIP file must be in the classpath. See "Summary of Files".)

  • Presumably the great majority of OracleJSP developers will use Oracle SQLJ (as opposed to some other SQLJ product) if they use SQLJ code in their JSP pages; however, this option is useful if you want to use a different Oracle SQLJ version (for example, one intended for use with Oracle JDBC 8.0.x/7.3.x drivers instead of Oracle8i drivers) or if you want to set SQLJ options.

 

translate_params

(boolean; OracleJSP default: false)

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

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

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

unsafe_reload

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

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

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

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


Important:

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


OracleJSP Configuration Parameter Settings

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

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

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

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

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

Setting OracleJSP Parameters in Apache/JServ

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

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

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

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

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

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


Note:

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


Setting OracleJSP Parameters in JSWDK

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

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


Note:

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


Setting OracleJSP Parameters in Tomcat

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


Note:

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


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

Oracle Servlet Engine JSP Configuration

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

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

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



Go to previous page
Go to beginning of chapter
Go to next page
Oracle
Copyright © 1996-2000, Oracle Corporation.

All Rights Reserved.

Library

Product

Contents

Index