Skip Headers

Oracle9iAS Containers for J2EE Support for JavaServer Pages Reference
Release 2 (9.0.2)

Part Number A95882-01
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Go to previous page Go to next page

3
Getting Started

This chapter covers basic issues in your JSP environment, including key support files, key OC4J configuration files, configuration of the JSP container, and other initial considerations such as application root and classpath functionality.

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

The following topics are covered here:

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

This section covers the following topics regarding configuration of the JSP environment:

JSP Container Setup

The JSP container is appropriately pre-configured 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>
       <servlet-mapping>
           <servlet-name>jsp</servlet-name>
           <url-pattern>/*.sqljsp</url-pattern>
       </servlet-mapping>
      <servlet-mapping>
           <servlet-name>jsp</servlet-name>
           <url-pattern>/*.SQLJSP</url-pattern>
      </servlet-mapping>

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

See the Oracle9iAS 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, starting with a summary table and then providing more complete descriptions.

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 pre-translating, and whether the parameter is for runtime or compile-time use.


Notes:

See "The ojspc Pre-Translation Utility" for a description of the ojspc options.


Table 3-1 JSP Configuration Parameters, OC4J Environment  
Parameter Related ojspc Options Description Default Runtime / Compile-
Time

debug_mode

(n/a)

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

true

runtime

emit_debuginfo

-debug

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

javaccmd

-noCompile

Use this if you want to specify a javac command line, or if you want to specify an alternative Java compiler, optionally with command-line settings (for development). If you specify an alternative compiler, it will be spawned in a separate JVM (javac runs in the same JVM). A null setting means use the JDK javac with default settings.

null

compile-time

main_mode

(n/a)

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

recompile

runtime

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

(n/a)

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

sqljcmd

-S

Use this if you want to specify a SQLJ command line, or if you want to specify an alternative SQLJ translator, optionally with command-line settings (for development). If you specify an alternative translator, it will be spawned in a separate JVM. A null setting means use the Oracle SQLJ version provided with Oracle9iAS, with its default option settings.

null

compile-time

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

(n/a)

This specifies a default setting for JSP tag handler pooling (true to enable by default; false to disable by default). You can override this default setting for any particular JSP page.

true

runtime

xml_validate

-xmlValidate

This specifies whether XML validation is performed on the web.xml file and TLD files.

false

compile-time

Configuration Parameter Descriptions

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

debug_mode

(boolean; default: true)

Use the default true setting to print a stack trace whenever a runtime exception occurs. Set it to false to disable this feature.


Note:

When debug_mode is false and a file is not found, the full path of the missing file is not displayed.


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.


Notes:

  • Oracle9i JDeveloper enables emit_debuginfo.

  • For pre-translating pages, the ojspc -debug option is equivalent.


external_resource

(boolean; default: false)

Set this flag to true to instruct the JSP 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, with the .res suffix. With Oracle9iAS 9.0.2, 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 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 in JSP Pages".


Note:

For pre-translating pages, the ojspc -extres option is equivalent.


javaccmd

(compiler executable; default: null)

This parameter is useful in either of the following circumstances:

Specifying an alternative compiler results in that executable being spawned as a separate process in a separate JVM, instead of within the same JVM as the JSP container. 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.


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 pre-translating pages, the ojspc -noCompile option allows similar functionality. It results in no compilation by javac, so you can compile the translated classes manually, using any desired compiler.


main_mode

(mode switch for reloading or recompilation; default: recompile)

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

Here are the supported settings:

old_include_from_top

(backward compatibility for include; default: false)

This is for backward compatibility with Oracle JSP versions prior to Oracle9iAS release 2, for functionality of include directives. If set to true, page locations in nested include directives are relative to the top-level page. If set to false, page locations are relative to the immediate parent page, as per the JSP 1.2 specification.


Note:

For pre-translating pages, the ojspc -oldIncludeFromTop option is equivalent.


precompile_check

(jsp_precompile checking; 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 pre-translated 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 Pre-Translation Without Execution", and the Sun Microsystems JavaServer Pages Specification, Version 1.1.

reduce_tag_code

(flag for size reduction of custom tag code; default: false)

The Oracle9iAS release 2 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 pre-translating pages, the ojspc -reduceTagCode option is equivalent.


req_time_introspection

(flag for request-time introspection; 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, this parameter is ignored and there is no request-time introspection.

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 and Tag-Extra-Info Classes" for information about use of VariableInfo.)


Note:

For pre-translating pages, the ojspc -reqTimeIntrospection option is equivalent.


sqljcmd

(SQLJ translator executable and options; default: null)

This parameter is useful in any of the following circumstances:

Specifying a SQLJ translator executable results in its being spawned as a separate process in a separate JVM, instead of within the same JVM as the JSP container.

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, to run SQLJ with online semantics checking as user scott/tiger and with the -ser2class option enabled, set sqljcmd to the following value:

sqlj -user=scott/tiger -ser2class=true

Appropriate SQLJ libraries 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, the translator ZIP or JAR file and the appropriate SQLJ runtime ZIP or JAR file must be in the classpath. See "Key Support Files Provided with OC4J".


Notes:

For pre-translating pages, the ojspc -S option provides related functionality.


static_text_in_chars

(flag to generate static text as characters; 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"); %>

Place this statement as close to the beginning of the page as possible.

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


Note:

For pre-translating pages, the ojspc -staticTextInChars option is equivalent.


tags_reuse_default

(default setting for tag handler pooling; default: true)

You can specify whether JSP tag handler instances are pooled by setting an attribute in the JSP page context. See "Disabling or Enabling Tag Handler Instance Pooling" for information about this.

If there is no setting in the page context, then the behavior is determined by the tags_reuse_default setting, or is according to a setting of true (the "default default") if tags_reuse_default is not specified.

xml_validate

(XML validation of web.xml and TLD files; default: false)

This flag specifies whether XML validation is performed on the application web.xml file and any tag library description (TLD) files. Because the Tomcat JSP reference implementation does not perform XML validation, xml_validate is false by default.


Note:

For pre-translating pages, the ojspc -xmlValidate option is equivalent.


Setting JSP Configuration Parameters in OC4J

In the OC4J environment, you can set JSP configuration parameters in the global-web-application.xml file, inside the servlet tag for the JSP front-end servlet. In the portion of this file shown in "JSP Container Setup", the settings would go where the init params place holder appears.

The following example lists servlet tag and subtag 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.

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 /j2ee/home/config directory:

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 information about the use of these files, see the Oracle9iAS Containers for J2EE User's Guide and the Oracle9iAS Containers for J2EE Servlet Developer's Guide. For additional information, see "Overview of EAR/WAR Deployment".

Some Initial Considerations

This section discusses some initial considerations you should be aware of before running or deploying JSP pages:

Application Root Functionality

The servlet 2.2 and 2.3 specifications provide 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 servlet 2.2 or 2.3 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 doc 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 Oracle9iAS 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 end-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, and has the ability to automatically reload classes in these locations, depending on configuration settings.

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 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 following directory in OC4J:

/j2ee/home/application-deployments/app-name/web-app-name/temp

The app-name is determined through an <application> element in the OC4J server.xml file; the web-app-name, which corresponds to the WAR file name, is mapped to the app-name through a <web-app> element in the OC4J default-web-site.xml file. See the Oracle9iAS Containers for J2EE User's Guide and the Oracle9iAS Containers for J2EE Servlet Developer's Guide for more information.

Generated page implementation classes for translated JSP pages are placed in subdirectories under the _pages directory according to the locations of the original .jsp files. See "Generated Files and Locations" for information.


Important:

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



Go to previous page Go to next page
Oracle
Copyright © 2000, 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index