Skip Headers

Oracle® Application Server 10g Upgrading from Release 1 (1.0.2.2.x) to 10g (9.0.4)
10g (9.0.4)
Part No. B13674-02
  Go To Documentation Library
Home
Go To Table Of Contents
Contents
Go To Index
Index

Previous Next  

3 Upgrading to OracleAS Containers for J2EE (OC4J)

This chapter contains step-by-step instructions for upgrading OC4J. It contains the following major sections:

3.1 Upgrade Considerations for OC4J Applications

When you upgrade applications from Oracle9iAS Release 1 (1.0.2.2.x) to Oracle Application Server, certain components of the applications may require manual adjustments, or may have characteristics of which you should be aware.

The key consideration in upgrading from Oracle9iAS Release 1 (1.0.2.2.x) to Oracle Application Server 10g (9.0.4) is the adaptation from an Apache JServ servlet 2.0 environment to the OC4J servlet 2.3 environment.

This section discusses relevant upgrade considerations, covering the following topics:


Note:

Whenever XML configuration files are mentioned, be aware that in an Oracle Application Server 10g (9.0.4) environment, as opposed to an Oracle9iAS Release 1 (1.0.2.2.x) or OC4J standalone environment, you should generally not edit configuration files directly. Use Oracle Enterprise Manager 10g for configuration. If you must edit configuration files, then use the dcmctl utility to notify Enterprise Manager that there have been changes, as follows:

dcmctl updateconfig -ct oc4j

See the Oracle Application Server Containers for J2EE User's Guide for general information about using Enterprise Manager and dcmctl with OC4J.


3.1.1 Upgrading to the OC4J 10g (9.0.4) JSP Environment

This section covers the key considerations for Oracle Application Server customers in upgrading JSP applications from Oracle9iAS Release 1 (1.0.2.2.x) to Oracle Application Server 10g (9.0.4). In addition to differences between the servlet 2.0 and servlet 2.3 environments, there are differences in the JSP container.The following topics are covered:


Note:

See Section 3.1.2, "Upgrading from JServ to the OC4J 10g (9.0.4) Servlet Environment"" for relevant information about application environment, servlet context and servlet path mapping, application root configuration, OC4J configuration, and deployment.

3.1.1.1 OracleJSP Container Versus Orion JSP Container in Oracle9iAS Release 1 (1.0.2.2.x)

In Oracle9iAS Release 1 (1.0.2.2.x), the first release to include OC4J, there were two JSP containers:

  • The container developed by Oracle and formerly known as "OracleJSP"

  • The container licensed from Ironflare AB and formerly known as the "Orion JSP container"

The OracleJSP container offered a number of advantages, including useful value-added features and enhancements such as for globalization and SQLJ support. The Orion container also offered advantages, including superior speed, but had disadvantages as well. It did not always exhibit standard behavior when compared to the JSP 1.1 reference implementation (Tomcat), and its support for internationalization and globalization was not as complete.

In Oracle9iAS Release 2 (9.0.2) and higher, these two containers are integrated into a single JSP container, referred to as the "OC4J JSP container". This container offers the best features of both original versions and runs efficiently as a servlet in the OC4J servlet container. The integrated container primarily consists of the OracleJSP translator and the Orion JSP runtime, running with a simplified dispatcher and the OC4J core runtime classes.

3.1.1.2 Key Issues for JSP Pages: The Servlet 2.3 Versus Servlet 2.0 Environment

In Oracle9iAS Release 1 (1.0.2.2.x), JServ was the primary servlet environment. There are significant differences between the OC4J 9.0.4 servlet environment, which is a servlet 2.3 implementation, and the JServ servlet environment, which is a servlet 2.0 implementation. The following is a summary of highlights, particularly with respect to JSP implementations:

  • Standard application environment versus globals.jsa: A well-defined concept of a Web application exists in the servlet 2.3 definition, but did not exist in the servlet 2.0 definition. The servlet standard and OC4J implementation now define the concept of the document root of a Web application, and how to package an application. See Section 3.1.1.4, "The Application Environment: Upgrading from OracleJSP globals.jsa in Release 1 (1.0.2.2.x)" for more information. For JServ, the OracleJSP implementation (but not the Orion JSP implementation) in Oracle9iAS Release 1 (1.0.2.2.x) emulated the application framework through the globals.jsa mechanism. Use of a globals.jsa file is not necessary in Oracle Application Server 10g (9.0.4) and is not supported in OC4J.

  • Request dispatcher: The concept of the request dispatcher was introduced in the servlet 2.1 specification. This mechanism allows a JSP page or servlet to include content from another page or servlet or to forward execution to another page or servlet. For JServ, the OracleJSP implementation (but not the Orion JSP implementation) in Oracle9iAS Release 1 (1.0.2.2.x) emulated request dispatcher functionality. For OC4J in Oracle Application Server 10g (9.0.4), this emulation is no longer necessary.

  • Attribute storage: Beginning with the servlet 2.1 specification, request-level and application-level attribute storage is possible. Developers can use HTTP request objects and servlet context (application-level) objects to store and retrieve state information. For JServ, the OracleJSP implementation (but not the Orion JSP implementation) in Oracle9iAS Release 1 (1.0.2.2.x) emulated this functionality. For OC4J in Oracle Application Server 10g (9.0.4), this emulation is not necessary.

  • Servlet filtering: The concept of servlet filtering was introduced in the servlet 2.3 specification. This mechanism allows verification and modification of HTTP request and response objects by developers. This might be used, for example, for common headers and footers or customized authentication or authorization. This functionality was not available in Oracle9iAS Release 1 (1.0.2.2.x) but is available in Oracle Application Server 10g (9.0.4).

  • Globalization: The servlet 2.3 specification provides globalization support for HTTP parameters through the standard setCharacterEncoding() method of the HTTP request object. The OracleJSP implementation (but not the Orion JSP implementation) in Oracle9iAS Release 1 (1.0.2.2.x) supported globalization through the translate_params configuration parameter. Later OC4J JSP implementations also supported globalization through the setReqCharacterEncoding() method of a public utility class. You should now migrate your applications to setCharacterEncoding(). See Section 3.1.1.12.1, "The setCharacterEncoding() Method".

3.1.1.3 Issues for Upgrading from the Release 1 (1.0.2.2.x) Orion JSP Container

The Orion container was the default JSP container in Oracle9iAS Release 1 (1.0.2.2.x). If that is the container you used, there are a number of considerations when upgrading to the OC4J JSP container in Oracle Application Server 10g (9.0.4). Following is a summary.

3.1.1.3.1 tatglib-location Setting

Consider the following tag library definition in the web.xml file:

<taglib>
   <taglib-uri>/hello</taglib-uri>
   <taglib-location>WEB-INF/lib/taglib.tld</taglib-location>
</taglib>

Note there is no opening "/" in the taglib-location setting. The OC4J 9.0.4 implementation of the JSP container resolves this to the following:

/WEB-INF/WEB-INF/lib/taglib.tld

This is compliant with the JSP specification. The Orion JSP container resolves it to the following (which was presumably the intent of the developer):

/WEB-INF/lib/taglib.tld

It is advisable to change the taglib-location setting to the following, adding the opening "/":

<taglib-location>/WEB-INF/lib/taglib.tld</taglib-location>

3.1.1.3.2 HTML Comments

The Orion JSP container sometimes ignored the content of HTML comments, denoted by <!-- ... --> (as opposed to <%-- ... --%> for JSP comments). As a result, the content within the HTML comment was not rendered in the browser.

The OC4J JSP container does not interpret HTML comments, but also does not ignore them. The container passes them through to the browser, which is behavior that complies with the JSP specification. This makes it feasible for developers to add JavaScript to an HTML comment.

3.1.1.3.3 Use of an Include Directive to Include a Page with an Unclosed Tag

The JSP specification does not specify whether an include directive should accept a page header without a proper closing tag. The Orion JSP container would accept such a header, but the OC4J JSP engine and the Tomcat reference implementation do not. Consider the following example:

--------------------------
a.jsp
<jsp:useBean id="b" class="pkgA.BeanB" >
<% // init the bean %>
--------------------------
--------------------------
b.jsp
<%@ include file="a.jsp" %>
</jsp:useBean>
<%= new java.util.Date() %>
--------------------------

This would be accepted by the Orion JSP container. To upgrade this to the OC4J JSP container, modify the syntax as follows:

--------------------------
a.jsp
<jsp:useBean id="b" class="pkgA.BeanB" >
<% // init the bean %>
</jsp:useBean>
--------------------------

--------------------------
b.jsp
<%@ include file="a.jsp" %>
<%= new java.util.Date() %>
--------------------------

3.1.1.3.4 Include Directive Syntax

The Orion JSP container accepted the following incorrect syntax:

<%@ include file="value" />

This does not follow the specification and is not accepted by the OC4J JSP container. The correct include directive syntax is:

<%@ include file="value" %>

3.1.1.3.5 Quotes in Tag Attribute Settings

According to the JSP 1.2 specification, tag attribute settings must always be quoted. Quotes within a setting must use an escape character. This was not clarified in previous JSP specifications, and the Orion JSP container accepted settings that were not properly quoted.

The following is incorrect, but was accepted by the Orion container:

<jsp:tag prop=<%=bean.getProperty("name")%> />

The following is correct and is now required by the OC4J JSP container (note the additional quotes and escapes):

<jsp:tag prop="<%=bean.getProperty(\"name\")%>"/>

3.1.1.4 The Application Environment: Upgrading from OracleJSP globals.jsa in Release 1 (1.0.2.2.x)

The servlet 2.0 specification did not have a clearly defined concept of a Web application and there was no defined relationship between servlet contexts and applications, as there is in later servlet specifications. In a servlet 2.0 environment such as JServ, there is only one servlet context object per JVM. A servlet 2.0 environment also has only one session object.

The OracleJSP 1.0.2.2 implementation, however, offered the use of globals.jsa files (a non-standard Oracle extension) to provide support for multiple applications and multiple sessions in a Web server, particularly for use in the servlet 2.0 environment. Where a distinct servlet context object would not otherwise be available for each application, the presence of a globals.jsa file for an application allowed the OracleJSP container to provide the application with a distinct ServletContext object.

Because OC4J in Oracle Application Server 10g (9.0.4) offers a servlet 2.3 environment with standard application support, use of globals.jsa is no longer supported. If an existing application uses globals.jsa, you should migrate away from this usage. The following substitutions for globals.jsa functionality are recommended:

  • Instead of using globals.jsa as an application marker, use standard WAR packaging to denote the application structure.

  • Instead of using globals.jsa start-session, end-session, start-application, and end-application events, use standard servlet 2.3 listener functionality. For example, equivalent capabilities are offered through the standard javax.servlet.ServletContextListener and javax.servlet.http.HttpSessionListener interfaces.

  • Instead of using globals.jsa for global variable declarations, put the declarations in a single source file and use "global include" functionality of the OC4J JSP engine, introduced in release 9.0.2. See Section 3.1.1.7, "JSP Global Includes"

3.1.1.5 JspScopeListener Issues for Upgrading from OracleJSP in Release 1 (1.0.2.2.x)

The OC4J JspScopeListener interface tracks page-scope, request-scope, session-scope, and application-scope events. To conform with servlet 2.3 standards, however, there are changes from how this mechanism was used in Oracle9iAS Release 1 (1.0.2.2.x).

For page-scope objects, no special steps or configuration are necessary if you use the OC4J JSP container. There is an Oracle-specific runtime implementation to support page scope.

If you use JspScopeListener for session-scope events, you should now implement the standard HttpSessionBindingListener interface as well as the JspScopeListener interface. This is necessary because the servlet 2.3 standard uses the servlet container instead of the JSP container to provide notification for session-based events. Delegate the valueUnbound() method of HttpSessionBindingListener to a common method shared by the outOfScope() method of the JspScopeListener interface.

JspScopeListener now supports request-scope objects through a servlet filter. The filtering applies to any servlets matching a specified URL pattern. Event-handling for request-scope objects requires an entry such as the following in the web.xml file for your application. To ensure proper operation of the JspScopeListener functionality, this setting must be after any other filter settings.

<filter> 
   <filter-name>Request Filter</filter-name>
   <filter-class>oracle.jsp.event.impl.RequestScopeFilter</filter-class>
</filter> 
<!-- Define filter mappings for the defined filters --> 
<filter-mapping> 
   <filter-name>Request Filter</filter-name> 
   <url-pattern>/jsp/*</url-pattern> 
</filter-mapping> 

JspScopeListener now supports application-scope objects through a servlet context listener implementation class, in compliance with the servlet 2.3 specification. Event-handling for application-scope objects requires an entry such as the following in the web.xml file for your application. To ensure proper operation of the JspScopeListener functionality, this setting must be after any other listener settings.

<listener> 
   <listener-class>oracle.jsp.event.impl.AppScopeListener</listener-class>
</listener> 

Be aware that you should directly manipulate configuration files only in an OC4J standalone environment. In Oracle Application Server, use Oracle Enterprise Manager 10g for configuration.

For additional information and examples, see the Oracle Application Server Containers for J2EE JSP Tag Libraries and Utilities Reference.

3.1.1.6 JSP Classpath Functionality

The OC4J JSP container in Oracle Application Server 10g (9.0.4) uses standard locations on the Web server in searching for translated JSP pages and any .class files and .jar files that they require. 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. These classes should be stored 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 the Java package structure is specified in the .jar file structure, the .jar files are all placed directly in the /WEB-INF/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

By default, the _pages directory is under the following directory in OC4J:

/j2ee/home/application-deployments/<app name>/<web app name>/persistence

The app name is determined through the <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 the <web-app> element in the OC4J default-web-site.xml file (or http-web-site.xml in OC4J standalone). See the Oracle Application Server Containers for J2EE Servlet Developer's Guide for 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.


Note:

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

3.1.1.7 JSP Global Includes

In Oracle9iAS Release 2 (9.0.2) and later, the OC4J JSP container provides a feature called global includes. You can use this feature to specify one or more files to statically include into JSP pages in (or under) a specified directory, through virtual JSP include directives. During translation, the JSP container looks for a configuration file, /WEB-INF/ojsp-global-include.xml, that specifies the included files and the directories for the pages.

This enhancement is particularly useful in upgrading applications that had used globals.jsa or translate_params functionality in Oracle9iAS Release 1 (1.0.2.2.x).

Globally included files can be used for the following, for example:

  • global bean declarations (formerly supported through globals.jsa)

  • common page headers or footers

  • translate_params equivalent code (for globalization)

The ojsp-global-include.xml File

The ojsp-global-include.xml file specifies the names of files to include, whether they should be included at the tops or bottoms of JSP pages, and the locations of JSP pages to which the global includes should apply. This section describes the elements of ojsp-global-include.xml.

3.1.1.7.1 <ojsp-global-include>

This is the root element of the ojsp-global-include.xml file. It has no attributes.

Subelements:

<include>

3.1.1.7.2 <include...>

Use this subelement of <ojsp-global-include> to specify a file to be included, and whether it should be included at the top or bottom of JSP pages.

Subelements:

<into>

Attributes:

  • file: Specify the file to be included, such as /header.html or /WEB-INF/globalbeandeclarations.jsph. The file name must start with a slash ("/"). In other words, it must be context-relative, not page-relative.

  • position: Specify whether the file is to be included at the top or bottom of JSP pages. Supported values are "top" (default) and "bottom".

3.1.1.7.3 <into...>

Use this subelement of <include> to specify a location (a directory, and possibly subdirectories) of JSP pages into which the specified file is to be included. This element has no subelements.

Attributes:

  • directory: Specify a directory. Any JSP pages in this directory, and optionally its subdirectories, will statically include the file specified in the file attribute of the <include> element. The directory setting must start with a slash ("/"), such as /dir1. The setting can also include a slash after the directory name, such as /dir1/, or a slash will be appended internally during translation.

  • subdir: Use this to specify whether JSP pages in all subdirectories of the directory should also have the file statically include. Supported values are "true" (default) and "false".

3.1.1.7.4 Global Include Examples

This section provides examples of global includes.

Example 3-1 Header/Footer: ojsp-global-include.xml File

<?xml version="1.0" standalone='yes'?>
<!DOCTYPE ojsp-global-include SYSTEM 'ojsp-global-include.dtd'>

<ojsp-global-include>
  <include file="/header.html">
     <into directory="/dir1" />
  </include>
  <include file="/footer1.html" position="bottom">
     <into directory="/dir1" subdir="false" />
     <into directory="/dir1/part1/" subdir="false" />
  <include file="/footer2.html" position="bottom">
  </include>
     <into directory="/dir1/part2/" subdir="false" />
  </include>
</ojsp-global-include>

This example accomplishes three objectives:

  • The header.html file is included at the top of any JSP page in or under the dir1 directory. The result would be the same as if each .jsp file in or under this directory had the following include directive at the top of the page:

    <%@ include file="/header.html" %>

  • The footer1.html file is included at the bottom of any JSP page in the dir1 directory or its part1 subdirectory. The result would be the same as if each .jsp file in those directories had the following include directive at the bottom of the page:

    <%@ include file="/footer1.html" %>

  • The footer2.html file is included at the bottom of any JSP page in the part2 subdirectory of dir1. The result would be the same as if each .jsp file in that directory had the following include directive at the bottom of the page:

    <%@ include file="/footer2.html" %>


    Note:

    If multiple header or multiple footer files are included into a single JSP page, the order of inclusion is according to the order of <include> elements in the ojsp-global-include.xml file.

Example 3-2 translate_params Equivalent Code: ojsp-global-include.xml File

<?xml version="1.0" standalone='yes'?>
<!DOCTYPE ojsp-global-include SYSTEM 'ojsp-global-include.dtd'>

<ojsp-global-include>
  <include file="/WEB-INF/nls/params.jspf">
     <into directory="/" />
  </include> 
</ojsp-global-include>

Further assume that the params.jspf file contains the following:

<% request.setCharacterEncoding(response.getCharacterEncoding(); %>

The params.jspf file is included at the top of any JSP page in or under the application root directory. In other words, it is included in any JSP page in the application. The result would be the same as if each .jsp file in or under this directory had the following include directive at the top of the page:

<%@ include file="/WEB-INF/nls/parms.jspf" %>

Alternatively, the globally included file could consist of scriptlet code performing one of the following actions:

  • Hardcode the request character set:

    <% request.setCharacterEncoding("desired_charset"); %>

  • Use the character set of the response as the character set of the request, where the character set of the response is determined dynamically by Java logic:

    <% String yourCharSet = yourLogicToDetermineCharset();
       response.setContentType("text/html; charset="+yourCharSet);
       request.setCharacterEncoding(response.getCharacterEncoding());
       // NOTE: The relative ordering of response.setContentType()
       // and request.setCharacterEncoding() is important.
    %>
    
    

    Also see Section 3.1.1.12.1, "The setCharacterEncoding() Method".

3.1.1.8 JSP Configuration: Upgrading from the OracleJSP Implementation in Release 1 (1.0.2.2.x)

In Oracle9iAS Release 2 (9.0.2) and later, the oracle.jsp.runtimev2.JspServlet front-end servlet is used instead of the oracle.jsp.JspServlet front-end servlet that was used in the 1.0.2.2 OracleJSP implementation.

Mapping of this class as the JSP servlet is handled automatically in the OC4J global-web-application.xml file, as in the following entry:

<servlet>
   <servlet-name>jsp</servlet-name>
   <servlet-class>oracle.jsp.runtimev2.JspServlet</servlet-class>
   ...
      init params
   ...
</servlet>

This file also includes <servlet-mapping> elements where file name extensions (.jsp, .JSP, .sqljsp, .SQLJSP, and .jspx) are mapped to this front-end servlet.

Configuration parameters ("init params", see above) can also be specified in global-web-application.xml, as in the following example:

<init-param>
   <param-name>precompile_check</param-name>
   <param-value>true</param-value>
</init-param>

3.1.1.8.1 Support for Previous OracleJSP Configuration Parameters

Table 3-1 summarizes JSP configuration parameters supported in the front-end servlet for the JServ environment, and notes which are still relevant and supported.

Table 3-1 Configuration Parameter Support: JServ to OC4J

Supported Config Params in JServ Supported Config Params in OC4J Comments
alias_translation
not necessary in OC4J
bypass_source
migrated to main_mode parameter
classpath
not necessary in OC4J
debug_mode debug_mode no change
developer_mode
migrated to main_mode parameter
emit_debuginfo emit_debuginfo no change
external_resource external_resource no change
javaccmd javaccmd no change
send_error
unnecessary in OC4J
session_sharing
unnecessary in OC4J
sqljcmd sqljcmd no change
translate_params
Unnecessary in OC4J; use standard servlet request setCharacterEncoding() method.Note: See "translate_params Equivalent Code: ojsp-global-include.xml File".
unsafe_reload
unnecessary in OC4J

3.1.1.8.2 JSP Configuration Parameters in Release 2 (9.0.2) and Higher

The following JSP configuration parameters were added in Oracle9iAS Release 2 (9.0.2):

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

  • old_include_from_top: Set this boolean to true for page locations in nested include directives to be relative to the top-level page, for backward compatibility with OracleJSP behavior in Oracle9iAS Release 1 (1.0.2.2.x).

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

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

  • req_time_introspection: Set this boolean to true to enable request-time JavaBean introspection if compile-time introspection is not possible. If compile-time introspection is possible and succeeds, this parameter is ignored and there is no request-time introspection.

  • static_text_in_chars: Set this boolean to true to instruct the JSP translator to generate static text in JSP pages as characters instead of bytes. Also see Section 3.1.1.12.2, "Static Text as Characters".

  • tags_reuse_default: This specifies a default setting for JSP tag handler pooling (true to enable by default; false to disable by default). This default setting can be overridden for any particular JSP page. Also see Section 3.1.1.12.4, "Tag Handler Reuse".

  • xml_validate: Set this boolean to specify whether XML validation is to be performed on the web.xml file and TLD files.

See Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide for additional information.

3.1.1.8.3 JSP Configuration Parameters in Release 2 (9.0.3) and Higher for Backward Compatibility

When upgrading to Oracle Application Server 10g (9.0.4) and using JSP pages, use appropriate settings for the following important JSP configuration parameters:

  • check_page_scope

  • forgive_dup_dir_attr

These are set as initialization parameters for the JSP front-end servlet, either in the global-web-application.xml file or in the application web.xml file. Here is an example:

<servlet>
   <servlet-name>jsp</servlet-name>
   <servlet-class>oracle.jsp.runtimev2.JspServlet</servlet-class>
   <init-param>
      <param-name>check_page_scope</param-name>
      <param-value>true</param-value>
   </init-param>
   ...
</servlet>

Manipulate configuration files directly only if you are in an OC4J standalone environment. In Oracle Application Server use Oracle Enterprise Manager 10g for configuration.

See the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide for more information about JSP configuration parameters.

  • check_page_scope (boolean; default: false): This parameter is supported in Oracle9iAS Release 2 (9.0.3) and higher. For OC4J environments, set it to true to enable Oracle-specific page-scope checking by the JspScopeListener utility.

    This parameter is not relevant for non-OC4J environments. For JServ, Oracle-specific page-scope checking is always enabled. See the Oracle Application Server Containers for J2EE JSP Tag Libraries and Utilities Reference for information about JspScopeListener.

  • forgive_dup_dir_attr (boolean; default: false): This parameter is supported in Oracle9iAS Release 2 (9.0.3) and higher. Set it to true to avoid translation errors in a JSP 1.2 environment such as OC4J 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 1.2 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.

    The JSP 1.1 specification did not specify such a limitation. OC4J offers the forgive_dup_dir_attr parameter for backward compatibility.

3.1.1.9 Potential Issues with the ojspc Utility

There are a few relatively minor upgrade considerations regarding the ojspc pre-translation utility in Oracle Application Server 10g (9.0.4).

3.1.1.9.1 Running ojspc for the OC4J Environment

The ojspc front-end script that sets up the classpath for pre-translation has been modified since Oracle9iAS Release 1 (1.0.2.2.x). Most users running ojspc for OC4J should not encounter problems using the different ojspc defaults; however, there are two potential issues to consider:

  • If your application relies on the pre-JSP 1.2 behavior of the include directive, you can set -oldIncludeFromTop=true for compatibility with this behavior. This ojspc option has the same functionality as the old_include_from_top JSP configuration parameter.

  • In OC4J, static text is now generated in bytes by default, whereas it was generated in characters in Oracle9iAS Release 1 (1.0.2.2.x), in the JServ environment. You can set -staticTextInChars=true if you want the old behavior. This ojspc option has the same functionality as the static_text_in_chars JSP configuration parameter.

See Section 3.1.1.8.2, "JSP Configuration Parameters in Release 2 (9.0.2) and Higher" for information about the old_include_from_top and static_text_in_chars parameters.

3.1.1.9.2 Running ojspc_jserv for the JServ Environment

If you want to use ojspc for pre-translation for the JServ environment in Oracle Application Server 10g (9.0.4), use the ojspc_jserv script (ojspc_jserv.bat on Windows) instead of the ojspc (or ojspc.bat) script.

3.1.1.10 Packaging and Deployment

In Oracle Application Server 10g (9.0.4), deployment is through the standard J2EE EAR (Enterprise archive) file, with the WAR (Web archive) file included inside the EAR file.

For OC4J, deploy each application through a standard EAR file. The name of the application and the name and location of the EAR file are specified through an <application> element in the OC4J /j2ee/home/config/server.xml file. In a standalone environment, you can accomplish this through the admin.jar utility. In an Oracle Application Server environment, use Enterprise Manager.

The EAR file includes the following:

  • a standard application.xml configuration file, in /META-INF

  • (optionally) an orion-application.xml configuration file, in /META-INF

  • a standard WAR file

The WAR file includes the following:

  • a standard web.xml configuration file, in /WEB-INF

  • (optionally) an orion-web.xml configuration file, in /WEB-INF

  • all JSP pages and Java classes (servlets, JavaBeans, and other classes) necessary to run the application, under /WEB-INF/classes and in JAR files in /WEB-INF/lib

For details about deployment in Oracle Application Server 10g, refer to the Oracle Application Server Containers for J2EE User's Guide or Oracle Application Server Containers for J2EE Stand Alone User's Guide, as applicable.

3.1.1.11 Enabling Extra Imports

In Oracle9iAS Release 2 (9.0.3) and higher, the OC4J JSP container by default imports the packages listed below into any JSP page, in compliance 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.*

For backward compatibility, you can use the JSP extra_imports configuration parameter as a workaround. Alternatively, you can add desired imports through page directives or global includes (see Section 3.1.1.7, "JSP Global Includes"). See the Oracle Application Server Containers for J2EE Support for JavaServer Pages Developer's Guide for information about these topics.

3.1.1.12 Other JSP Considerations

This section covers additional JSP upgrade considerations.

3.1.1.12.1 The setCharacterEncoding() Method

Effective with the servlet 2.3 specification, the setCharacterEncoding() method is available in the javax.servlet.ServletRequest class as the standard mechanism for specifying a non-default character encoding for reading HTTP requests. The signature of this method is as follows:

void setCharacterEncoding(java.lang.String enc)

throws java.io.UnsupportedEncodingException

The enc parameter is a string specifying the name of the desired character encoding, overriding the default character encoding. Call this method before reading request parameters or reading input through the getReader() method (also of the ServletRequest class).

There is also a corresponding getter method:

String getCharacterEncoding()

In OC4J implementations using pre-2.3 servlet environments, including the implementation in Oracle9iAS Release 1 (1.0.2.2.x), the setCharacterEncoding() method was not available. For such environments, particularly the JServ servlet 2.0 environment, the OracleJSP implementation provided alternative mechanisms as non-standard extensions: the oracle.jsp.util.PublicUtil.setReqCharacterEncoding() method and the translate_params configuration parameter.

In using the application server 9.0.4 implementation, you should upgrade to the setCharacterEncoding() method wherever possible. In summary:

  • Use setCharacterEncoding() for IANA encodings.

  • Use setReqCharacterEncoding() for non-IANA encodings. (The setCharacterEncoding() method does not support such encodings.)

  • Avoid using the translate_params configuration parameter. For information about global includes, which you can use to replace translate_params functionality with setCharacterEncoding() calls (among many other uses), see Section 3.1.1.7, "JSP Global Includes".

3.1.1.12.2 Static Text as Characters

In JServ, which was the primary servlet environment under Oracle9iAS Release 1 (1.0.2.2.x), static text is output in character format. In OC4J, static text is output as bytes by default, for faster throughput.

Some globalization functionality and flexibility is unavailable if static text is generated as bytes. For this reason, the OC4J JSP container supports the configuration parameter static_text_in_chars if you want to revert to character format for any reason.

Enable this flag, for example, 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"); %>

3.1.1.12.3 Proper Handling of jsp:param Settings

Consider the following jsp:include tag and nested jsp:param tag:

<jsp:include page="..." >
   <jsp:param name="..." value="..." />
</jsp:include>

With the OC4J JSP container in Oracle Application Server 10g (9.0.4), there is no need to manually encode the name and value settings for the jsp:param tag. Just use the appropriate Java strings; encoding is handled automatically. This was not the case with the Orion JSP container in Oracle9iAS Release 1 (1.0.2.2.x), where manual encoding was required.

3.1.1.12.4 Tag Handler Reuse

In Oracle Application Server 10g (9.0.4), you can specify whether JSP tag handler instances are pooled in a particular JSP page (always in the application scope) by setting the oracle.jsp.tags.reuse attribute in the JSP page context. Set it to true to enable pooling, or to false to disable pooling. For example:

pageContext.setAttribute("oracle.jsp.tags.reuse", new Boolean(true));

You can use separate settings in different pages, or even in different sections of the same page.

The default is according to the setting of the tags_reuse_default JSP configuration parameter. This default is true in OC4J but false in JServ.

3.1.1.12.5 Session Key Seed Generation

OC4J in Oracle Application Server 10g (9.0.4) has a more secure session key seed generation process. When the first HttpSession object is created in an OC4J instance, there are a number of threads created to generate the session key seed. Therefore, users experience a longer delay during the first compilation or serving of a JSP page that uses session objects, compared to when using the OC4J in Oracle9iAS Release 1 (1.0.2.2.x). After the seed is generated, the process of compiling and serving JSP pages is as fast as before.

3.1.2 Upgrading from JServ to the OC4J 10g (9.0.4) Servlet Environment

This section covers the major considerations for upgrading servlet applications from Oracle9iAS Release 1 (1.0.2.2.x) to Oracle Application Server 10g (9.0.4). This involves adapting from a servlet 2.0 environment, such as Apache JServ in the 1.0.2.2 implementation, to a servlet 2.3 environment, such as Oracle Application Server Containers for J2EE in the 9.0.4 implementation.

Included is information about application environment and servlet zones, class and file locations, mount points, servlet aliases, initialization parameters, environment and JVM settings, prestarting, class loading, logging, servlet sessions, load balancing, and fault tolerance. The section contains the following topics:

Most sections present information for JServ as a reference, followed by the corresponding information for OC4J.


Note:

The material in this section assumes that the reader has knowledge of the Sun Microsystems Java Servlet Specification, versions 2.2 and 2.3, including WAR files, EAR files, and the web.xml file is assumed. Prior knowledge of OC4J configuration files is also helpful.

For more information about the topics discussed here, refer to the Oracle Application Server Containers for J2EE Servlet Developer's Guide and the Oracle Application Server Containers for J2EE User's Guide.

3.1.2.1 The Web Application Environment

In Oracle9iAS Release 1 (1.0.2.2.x), Apache JServ, a servlet 2.0 environment, was the primary servlet environment. The servlet 2.0 specification did not have a clearly defined concept of a Web application and there was no defined relationship between servlet contexts and Web applications, as there is in later servlet specifications. In a servlet 2.0 environment such as JServ, there is only one servlet context object per JVM. A servlet 2.0 environment also has only one session object.

In Oracle Application Server 10g (9.0.4), OC4J is the primary application environment. OC4J includes a servlet 2.3 container with standard Web application support.

This section discusses the Web application environment, contrasting servlet 2.0 features and servlet 2.3 features.

3.1.2.1.1 Servlet Context and Servlet Path Mapping

The servlet 2.2 and 2.3 specifications provide for each Web application to have its own servlet context, unlike in the servlet 2.0 JServ environment. This section reviews the servlet 2.2 and 2.3 functionality.

Each servlet context is associated with a directory path, the application root, in the server file system that is the base path for modules of the Web application. 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 all share 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 URL for a servlet is typically of the form:

http://<host>[:<port>]/<context path>/<servlet path>

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, and the <servlet-mapping> element within web.xml associates a URL pattern with a servlet name. When a request reaches a Web application, the servlet container will compare the path in the request with known URL patterns defined in web.xml, and invoke the servlet according to a matched URL pattern. See the Oracle Application Server Containers for J2EE Servlet Developer's Guide for more information.

3.1.2.1.2 Servlet Zones Versus Web Applications

JServ has the concept of servlet zones, somewhat comparable to the Web application concept in servlet 2.2 and higher specifications. This section compares basic zone setup in JServ to basic application setup in OC4J.

Basics of JServ Zone Specification  A servlet zone is somewhat similar in concept to a Web application. The use of zones helps developers separate the overall JServ environment into separate groups of servlets, according to conditions such as work load, usage, and security privileges. In JServ, servlets are grouped and managed based on servlet zones, not based on the servlet container itself. It is mandatory to have at least one servlet zone.

Servlet zones are specified in the jserv.properties file. In addition, each zone has its own configuration file, known as a "zone properties file", typically with a naming convention such as zonexxx.properties.

Here is an example of zone settings in jserv.properties:

zones = zone1,zone2

The locations of the corresponding zone properties files are also specified in jserv.properties, as in the following example:

zone1.properties =/servlet/zone1/zone1.properties

zone2.properties =/servlet2/zone2/zone2.properties

Basics of OC4J Application Specification  In OC4J, Web applications can be considered equivalent to zones. It is also true that in OC4J, servlets are grouped and managed on a per-application basis. Additionally, OC4J has the concept of a default global application that is the parent of all applications, and also defines a default Web application. Following is an overview of key OC4J configuration files for Web applications.

These are global files for all OC4J applications, typically in the OC4J /j2ee/home/config directory:

  • default-web-site.xml (or http-web-site.xml for OC4J standalone): This includes a <web-app> element for each Web application for the default Web site, mapping the application name to the "Web application name". The Web application name corresponds to the WAR deployment file name. Additional Web site XML files, as specified for additional Web sites in the server.xml file, have the same functionality.

  • global-web-application.xml: This is a global configuration file for OC4J Web applications, establishing default configurations, and including setup and configuration of the JSP front-end servlet, JspServlet.

  • application.xml: This is a configuration file for the global OC4J J2EE application.

  • data-sources.xml: This specifies data sources for database connections.


    Note:

    n an Oracle Application Server environment, use Oracle Enterprise Manager 10g for configuration. If you must update configuration files directly, use the dcmctl utility to make Enterprise Manager aware of the changes, as described at the beginning of Section 3.1, "Upgrade Considerations for OC4J Applications".

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, 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 application.xml file or the global-web-application.xml file, respectively.

For more 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.

3.1.2.2 Enterprise Applications Versus Web Applications

According to the servlet 2.0 specification, and therefore in the JServ environment of the 1.0.2.2 application server implementation, Web applications stood on their own and were deployed through standalone WAR files. According to the J2EE 1.3 and servlet 2.3 specifications, and therefore in the OC4J environment of the 9.0.4 application server implementation, a Web application is typically part of a J2EE enterprise application, which may also include other components, such as EJBs. Reflecting this structure, the WAR file for a Web application is contained within the EAR file for the enterprise application of which the Web application is a part. The enterprise application and all its components, including Web applications, are deployed through the EAR file.

Enterprise applications and EAR files are discussed in the Java2 Platform Enterprise Edition Specification, version 1.3.

3.1.2.3 Application Structure and File Location

This section discusses the typical OC4J Web application structure and how to configure file locations in OC4J compared to JServ.

3.1.2.3.1 JServ File Repositories

The locations, or repositories, of servlets under a servlet zone are specified through repositories commands in the zone properties file. (See Section 3.1.2.1.2, "Servlet Zones Versus Web Applications", sub-topic "Basics of JServ Zone Specification", for information about zone properties files.) JServ loads classes from locations specified in repository entries. Here are some examples:

repositories=/private/mydir/net.jar

repositories=/private/mydir/tmp/net.zip

repositories=/private/mydir/applications

As shown, class files can be read directly from directories or from archive files (ZIP or JAR). See Section 3.1.2.7.1, "Class Loading in JServ" for more information about repositories and class loading.

3.1.2.3.2 OC4J Application Structure and File Locations

This section shows the typical (and recommended) Web application structure under the application root directory. Much of it applies generally to servlet 2.2 and 2.3 environments:

WEB-INF/
   web.xml
   orion-web.xml
   classes/
      package/
         xxx.class
   lib/
      xxx.jar
xxx.jsp
xxx.html

In OC4J, the root directory is app name/web app name. The application name is defined in the server.xml file and mapped to a Web application name in the default-web-site.xml file or other Web site XML file.

According to this structure, servlet classes go under the app name/web app name/WEB-INF/classes directory, in subdirectories according to package names as appropriate. For example, if you have HelloWorldServlet in the examples package, then the class file should be located as follows:

app name/web app name/WEB-INF/classes/examples/HelloWorldServlet

Place HTML files, JSP pages, and other resource files in the application root directory.

Place required library files, such as JAR files, in the following directory:

app name/web app name/WEB-INF/lib

Note that in OC4J as well as in JServ, class files can be read either directly from a directory or from an archive file (ZIP or JAR).

You can also specify a codebase, placing additional required files in a desired location, then adding that location to your classpath through the <classpath> subelement of the <orion-web-app> element in the orion-web.xml file, as in the following example:

<classpath path="/private/test/test.jar" />

In an Oracle Application Server environment, configure this using Oracle Enterprise Manager 10g.

3.1.2.4 OC4J Deployment

This section covers the basics of deployment in the OC4J 9.0.4 implementation.

In an Oracle Application Server environment, you configure and deploy applications using Oracle Enterprise Manager 10g. Also note that you will typically use an Enterprise archive (EAR) file for OC4J deployment.

Consider the following example, the procedure for creating an EAR file for a simple application with a servlet HelloServlet and a JSP page Hello.jsp:

  1. Create and configure the web.xml file to specify application-specific settings. Also configure the orion-web.xml file, if desired. Use Enterprise Manager if you are in an Oracle Application Server environment.

  2. Create a Web archive (WAR) file, helloapp.war.

    The helloapp.war file contains the following:

    META-INF/MANIFEST.MF
    WEB-INF/
    WEB-INF/classes/
    WEB-INF/classes/HelloServlet.class
    WEB-INF/orion-web.xml
    WEB-INF/web.xml
    Hello.jsp
    
    

    (The META-INF/MANIFST.MF file is created by the JAR utility. There is no need to modify it.)

  3. Create an EAR file, helloapp.ear, for deploying the application. The EAR file contains:

    META-INF/
    META-INF/MANIFEST.MF
    WEB-INF/application.xml
    WEB-INF/orion-applcation.xml
    helloapp.war
    
    

    The application.xml file is required when deploying an EAR file, but the orion-application.xml file is optional.

    Using this helloapp.ear file, you can deploy the Web application using Oracle Enterprise Manager 10g.

3.1.2.5 Servlet and Environment Setup

This section covers a variety of servlet setup issues, reviewing configuration steps for JServ and providing the equivalent steps for OC4J.

3.1.2.5.1 JVM Parameters and Environment Variables

This section describes how to set JVM and environment variables for OC4J and JServ.

Setting Environment Variables in JServ  In jserv.properties, you can set environment variables for the JVM to use, including Oracle environment settings.

The following examples are for Oracle settings:

wrapper.env=LD_LIBRARY_PATH=...

wrapper.env=ORACLE_HOME=...

wrapper.env=ORACLE_SID=...

There are also settings for the Java and system environment:

  • Use the following to set the classpath:

    wrapper.classpath=...

  • Use the following to set the file path:

    wrapper.path=...

  • Use the following to set the full path of the Java interpreter (if it is not visible in the path):

    wrapper.bin=...

  • Use wrapper.bin.parameters for JVM loading parameters, such as for heap or stack size. Following is an example:

    wrapper.bin.parameters=-Xms64m

  • Use wrapper.env.copy or wrapper.env.copyall to copy environment parameters from the caller to the JVM. The following examples copy all environment parameters, and a particular environment parameter (myparam), respectively:

    wrapper.env.copyall

    wrapper.env.copy=myparam

In addition, JServ has the following security parameters:

security.maxConnections, security.allowedaddresses, and security.authentication.

Setting Environment Variables in OC4J  The method used to set environment variables in OC4J depends on how it is started.

In particular, if OC4J is started from Oracle Enterprise Manager 10g (that is, via the process management module OPMN), then parameters are specified through the <ORACLE_HOME>/opmn/conf/opmn.xml configuration file. In particular, the following subelements of the <oc4j> element are relevant:

  • The <java-bin> subelement specifies a path to the Java executable. If this element is not specified, <ORACLE_HOME>/jdk/bin/java is used by default.

  • The <java-option> subelement specifies the command line parameters required by the JVM.

The <java-bin> subelement is equivalent to wrapper.bin in JServ. The <java-option> subelement is equivalent to wrapper.bin.parameters in JServ.

You should generally use Enterprise Manager to configure these parameters. If you must update the configuration file directly, use the dcmctl utility to make Enterprise Manager aware of the changes, as described at the beginning of Section 3.1, "Upgrade Considerations for OC4J Applications".

Here is an example (showing only the relevant portions of <oc4j> element syntax):

<oc4j numProcs="1"  maxRetry="4" ... > 
      <java-bin path="/private/my-sun/jdk/bin/java" />
     <java-option value="-Xmls32m -Xmx64m -Xss128K
                         -Doracle.ons.oraclehome=/private/oracle" />
...
</oc4j>

The opmn.xml file also specifies Oracle environment variables, through the <environment> element, such as in the following example:

<environment> 
   <prop name="PATH" value="/private/home/ias/lib"/> 
   <prop name="CLASSPATH" value="/private/home/ias/bin" />
   <prop name="LD_LIBRARY_PATH" value="/private/home/lib" />
</environment>

These settings specify the environment for the new process when it is spawned.

See the Oracle Application Server 10g Administrator's Guide for information about OPMN.

In an OC4J standalone environment, you can set parameters through the oc4j.properties file and use the -properties option in the Java command line to point to the location of the file.

3.1.2.5.2 Mount Settings

JServ (mod_jserv) and OC4J (mod_oc4j) each have "mount" commands to establish application root locations, or "mount points".

JServ Mount Settings  In JServ, mount points are used to define the root locations for different servlet zones. If the protocol, host, or port are not specified, then they are picked from default entries in the jserv.conf file, which is included into the httpd.conf file. Consider the following sample mount commands:
ApJServMount /servlets /root
ApJServMount /servlets/admin ajpv11://myhost:9009/admin

These commands have the following effect:

The URL below, as a result of the first ApJServMount command, requests the servlet HelloWorldServlet in the servlet zone root:

http://myhost.mycompany.com/servlets/HelloWorldServlet

The URL below, as a result of the second ApJServMount command, is handled through port 9009, using Apache JServ Protocol (AJP) version 1.1.

http://myhost.mycompany.com/servlets/admin/HelloWorldServlet

OC4J Mount Settings   In the OC4J and Oracle HTTP Server environment, you can specify mount points through the <ORACLE_HOME>/Apache/modoc4j/conf/mod_oc4j.conf file. You can specify additional relevant Java-side settings, such as host and port, through default-web-site.xml settings. While the default-web-site.xml file is mentioned in this section, be aware that in an Oracle Application Server environment, you should perform the configuration using Oracle Enterprise Manager 10g rather than by editing this file.

Refer to "JServ Mount Settings" for comparisons. Consider the following JServ example again:

ApJServMount /servlets/admin ajpv11://myhost:9009/admin

You can make equivalent protocol and host settings through the <web-site> element in default-web-site.xml as follows:

<web-site port="9009" protocol="ajp13" ...>
...
</web-site>

Also note that within the <web-site> element, you can use <web-app> subelements to specify information about individual applications on the site, such as the corresponding Web application name and application root. Here is an example:

<web-app application="ojspdemos" name="ojspdemos-web" 
            root="/ojspdemos" />

On the target host, myhost, OC4J would find the Web application according to application settings in default-web-site.xml.

Based on the preceding Oc4jMount command, the following request would be routed to an OC4J process that listens at myhost on port 9009 using Apache JServ Protocol (AJP) version 1.3:

http://myhost.mycompany.com/servlets/admin/HelloWorld

OC4J would find the application according to application settings in default-web-site.xml on myhost.


Note:

The host and port specified in the Oc4jMount command should be the same as the host and port specified for ajp13 protocol in the default-web-site.xml file.

If Oracle Enterprise Manager 10g (that is, the OPMN process) starts OC4J, then in mod_oc4j.conf you can add the following, in which case OPMN will scan all possible ports for a suitable and available AJP port to use. Requests of the form /servlets/admin/* will be directed to one of the OC4J JVMs in the default "home" OC4J instance.

Oc4jMount /servlets/admin/* 

This is in conjunction with the following default settings in the default-web-site.xml file:

<web-site port="0" protocol="ajp13" ...>
...
</web-site>

You can also specify a particular OC4J instance, or load balancing between clusters, or load balancing between Oracle Application Server instances, as in the following examples:

Oc4jMount /servlets/admin/* oc4j_inst1

Oc4jMount /servlets/admin/*  cluster://ias_cluster_1:home,ias_cluster_2:home

Oc4jMount /servlets/admin/* instance://ias_inst_1:home_1,ias_inst_2:home_2

For more information about Oc4jMount commands, refer to the Oracle HTTP Server Administrator's Guide. For more information about default-web-site.xml and other Web site XML files, see the Oracle Application Server Containers for J2EE Servlet Developer's Guide

3.1.2.5.3 Servlet Aliases and URL Mapping

This section compares the methods of specifying servlet aliases and URL mapping in JServ and in OC4J.

Aliases and URL Mapping in JServ  In JServ, servlet aliases are specified in the appropriate zone properties file. For example, for a servlet class example.extensionmapping.InputServlet, you can specify the alias inputservlet to avoid having to specify the full path when you invoke the servlet. This is done as follows:

servlet.inputservlet.code = example.extensionmapping.InputServlet

URL extension mappings, like mount points, are defined in the jserv.conf file. Following is an example:

ApJServAction .inp /servlets/example.extensionmapping.InputServlet

This results in URL patterns ending in ".inp" being mapped to InputServlet.

Also, for example, assume the following mount command:

ApJServMount /servlets /root

The following URL, because of this ApJServMount command and the ApJServAction command, is passed to example.extensionmapping.InputServlet in the servlet zone root.

http://myhost.mycompany.com/EmployeeInput.inp

Aliases and Extension Mapping in OC4J  In OC4J, servlet aliases and URL mappings are specified through entries such as the following in the global-web-application.xml file:
<servlet>
   <servlet-name>inputservlet</servlet-name>
   <servlet-class>example.extensionmapping.InputServlet</servlet-class>
</servlet>
...
<servlet-mapping>
   <servlet-name>inputservlet</servlet-name>
   <url-pattern>/*.inp</url-pattern>
</servlet-mapping>

The servlet name (alias) can be anything—it simply serves as a reference name to associate the servlet class with the URL extension that is specified in the <servlet-mapping> element.

In an Oracle Application Server environment, do not edit global-web-application.xml directly. Perform configuration through Oracle Enterprise Manager 10g.

3.1.2.5.4 Initialization Parameters

This section details the differences between JServ and OC4J in setting servlet initialization parameters.

Setting Initialization Parameters in JServ  JServ supports servlet-based initialization parameter settings ("initArgs") as well as zone-wide default parameter settings. These settings are specified in the appropriate zone properties file.

For example, for a servlet foo1, you would define a servlet-based setting for the name parameter as follows:

servlet.foo1.initArgs=name=scott

A zone-wide default setting, shared by all servlets in the zone, is specified as in the following example. This specifies a default setting for the company parameter:

servlets.default.initArgs=company=oracle

A servlet-based setting overrides a zone-wide (default) setting for the same named parameter.

Setting Initialization Parameters in OC4J  In OC4J, servlet-based initialization parameter settings are specified through subelements of the <servlet> element in the standard web.xml file. The following example is equivalent to the example for foo1 in the preceding section (but also specifies the servlet class):
<servlet>
   <servlet-name>foo</servlet-name>
   <servlet-class>FooServlet</servlet-class>
   <init-param>
        <param-name>name</param-name>
        <param-value>scott</param-value>
   </init-param>
</servlet>

No equivalent for zone-wide settings in JServ exists in OC4J—there is no mechanism for application-wide default settings. However, <context-param> settings are conceptually similar. For each Web application, there is a servlet context. Attributes for the context can be set in the application web.xml file, as in the following example.

<context-param>
    <param-name>company</param-name>
    <param-value>oracle</param-value>
</context-param>

Also similar, in a servlet 2.3 environment, is the use of servlet filters. You can use filters to enforce a global behavior across groupings of servlets based on URL patterns. This is described in the Java Servlet Specification, version 2.3.

3.1.2.6 Servlet Pre-Starting

This section compares servlet pre-start features between the OC4J 9.0.4 implementation and JServ.

3.1.2.6.1 Pre-Started Servlets

In both JServ and OC4J, servlets can be pre-started. Rather than having servlet instances created only after the first request arrives, they can be created in advance and pre-started by the servlet container when the container starts up. This reduces the time taken for servicing the first request.

3.1.2.6.2 Pre-Start and Timeout Settings in JServ

In JServ, servlets to pre-start are specified in the appropriate zone properties file, as in the following example:

servlets.startup=oracle.sample.test1.HelloWorld,foo1

This prestarts HelloWorld and foo1.

Alternatively, you can use an alias name instead of the complete name.

JServ zone properties files also support the following parameters, which have no equivalents in OC4J:

  • Parameters to specify the timeout period for initialization (after which the servlet container will stop trying to initialize) and the timeout period after which a servlet is destroyed:

    init.timeout

    destroy.timeout

  • Parameters for the single-threaded model, to specify the number of servlet instances to be created if the servlet implements the javax.servlet.SingleThreadModel interface:

    SingleThreadModelServlet.initialCapacity

    SingleThreadModelServlet.incrementCapacity

    SingleThreadModelServlet.maximumCapacity

3.1.2.6.3 Pre-Start Settings in OC4J

In a servlet 2.3 environment such as OC4J, servlets can be pre-started according to the <load-on-startup> subelement of the <servlet> element in the application web.xml file, as in the following example:

<servlet>
   <servlet-name>HelloWorld</servlet-name>
   <servlet-class>oracle.sample.test1.HelloWorld</servlet-class>
   <load-on-startup/>
</servlet>

In OC4J, there must also be a setting of auto-start="true" in the appropriate <application> element in the server.xml file, and a setting of load-on-startup="true" in the relevant <web-app> subelement of the <web-site> element of the appropriate Web site XML file. This is described in the Oracle Application Server Containers for J2EE Servlet Developer's Guide.

3.1.2.7 Class Loaders and Automatic Class Reloading

This section discusses servlet class loaders, and class reloading during servlet execution.

3.1.2.7.1 Class Loading in JServ

This section discusses class loaders and class reloading in the JServ environment. There is a separate class loader for each of the following:

  • system classes: classes found on the system classpath

    For automatic JServ startup, the system classpath is determined by the wrapper.classpath setting in the jserv.properties file. For manual JServ startup, the system classpath is determined by the CLASSPATH setting for the particular JServ instance.

    Classes loaded from the system classpath (including servlet classes) cannot be automatically reloaded without restarting the server.

  • zone classes: classes found on the zone classpath

    The zone classpath is specified through the repositories parameter in the zone properties file.

Be aware of the following:

  • Classes loaded from the system classpath are shared across all zones in the same JVM.

  • Each servlet zone has its own instance of a custom class loader, for classes in the zone classpath.

  • Classes loaded from the zone classpath are not shared between zones. Furthermore, for a class that is available in different zones, its static variables cannot be shared across zones, even when the zones are in the same JVM. For static variables to be sharable, the class must be in the system classpath, and therefore loaded by the system class loader.

Classes in the zone classpath, and therefore loaded by the zone class loader, can be automatically reloaded if they are modified. This is useful if you are in the process of developing your application, and is determined by the following setting in the zone properties file:

autoreload.classes=true

3.1.2.7.2 Class Loading in OC4J

OC4J classpath and class loader configuration that is equivalent to that of JServ is determined as follows:

  • For server-wide class loading, classpath settings are specified through the <library> element of the OC4J global j2ee/home/config/application.xml file, as in the following example:

    <library path="/tmp/net.jar" />

    Relative or absolute paths to directories can be specified, and these directories are scanned for JAR or ZIP files to include in the classpath at startup. By default in the OC4J 9.0.4 implementation, the application.xml file specifies the inclusion of files from the j2ee/home/applib directory. (A <library> element exists for this path in the default global application.xml file).


    Note:

    Do not confuse the OC4J global application.xml file with the standard application.xml file for each application.

  • For application-based class loading, the default classpath consists of the directories WEB-INF/classes (for class files, in subdirectories according to package names) and WEB-INF/lib (for JAR and ZIP libraries).

    Additional classpath information can be specified through the <classpath> element of the orion-web.xml file, as in the following example:

    <classpath path="/private/test/test.jar" />

However, do not update configuration files directly in an Oracle Application Server environment. Use Oracle Enterprise Manager 10g for configuration.

In an OC4J standalone development environment, you can specify automatic recompilation and reloading of servlets in OC4J by setting the development attribute to true in the <orion-web-app> element of the j2ee/home/config/global-web-application.xml file or the application orion-web.xml file (which takes precedence over global-web-application.xml for a particular application).

In this case, classes in the target directory are automatically reloaded whenever they are modified, or whenever an application-level XML file is modified. This is useful when you are in the process of developing your application.

By default, when automatically reloading, source files (.java) are picked up from the target directory WEB-INF/src if it exists. If the src directory does not exist, then source files are picked up from the WEB-INF/classes directory instead. You can specify an alternative target directory through the source-directory attribute of the <orion-web-app> element in the application orion-web.xml file, as in the following abbreviated example:

<orion-web-app ... source-directory="/private/scott/myservletsource" ...>
   ...
</orion-web-app>

In this case, files are picked up from the specified directory only, not from the src or classes directory.

3.1.2.8 Session Tracking and Behavior

This section discusses session behavior and related configuration in JServ and OC4J.

3.1.2.8.1 Session Tracking and Behavior in JServ

JServ provides the following parameters in the zone properties file for specifying session behavior:

  • session.useCookies — Specifies whether to use cookies for sessions (default is true). If false, then the encodeUrl() method of the response object is the only means of session-tracking.

  • session.timeout — Specifies the number of milliseconds to wait before invalidating a session (default is 1800000, which is 30 minutes).

  • session.checkFrequency — Specifies how frequently (in seconds) to check for timed-out sessions. (The default is 30.)

3.1.2.8.2 Session Tracking and Behavior in OC4J

For session tracking in OC4J, the servlet container will first attempt to accomplish tracking through cookies. If cookies are disabled, session tracking can be maintained only by using the encodeURL() method of the response object explicitly in the servlet. (The encodeURL() method replaces the servlet 2.0 encodeUrl() method, which has been deprecated.)

It is also possible to specify the number of minutes for OC4J to wait before a session is invalidated. (The default is 20.) The <session-timeout> subelement of the <session-config> element in the application web.xml file can specify this, as follows:

<session-config>
   <session-timeout>30</session-timeout>
</session-config>

Additionally, the following setting in the global-web-application.xml or orion-web.xml file disables the use of session cookies:

<session-tracking cookies="disabled" ... >
   ...
</session-tracking>

However, do not update configuration files manually in an Oracle Application Server environment—use Oracle Enterprise Manager 10g for configuration.

Cookies are enabled by default. This is equivalent to the functionality of session.useCookies in JServ. As in the JServ case, with cookies disabled you must explicitly use the encodeURL() method of the response object for session-tracking.

3.1.2.9 Message and Error Logging

This section compares the JServ and OC4J mechanisms for setting up log files.

3.1.2.9.1 Message Logging for JServ

Message logging parameters such as the log file name, timestamp format, and other settings are specified through the jserv.properties file. This can help with debugging.

Following are the key parameters:

  • log — Specifies whether or not to log messages (log=true by default).

  • log.file — Specifies the file where log messages are written. (An absolute path name is recommended.)

  • log.timestamp — Specifies that messages are to be preceded by a timestamp (log.timestamp=true by default).

  • log.dateFormat — Specifies the date format in the timestamps. The setting is dd/MM/yyyy HH:mm:ss:SSS.zz by default.

  • log.queue.maxage — Specifies the maximum time (in milliseconds) that a message can be in the queue.

  • log.queue.maxsize — Specifies the maximum number of messages in the queue.

In addition, you can use the following parameters to enable different levels of logging:

  • log.channel

  • log.channel.info

  • log.channel.ServletException

  • log.channel.jservException

  • log.channel.warning

  • log.channel.servletLog

  • log.channel.critical

  • log.channel.debug

3.1.2.9.2 Message Logging for OC4J

Several logs are available in OC4J in Oracle Application Server 10g. Because they are not specific to servlets, they are documented elsewhere, but this section provides a summary list and appropriate cross-references. For each log, you have the option of using text-based logging or Oracle Diagnostic Logging (ODL). For ODL, log file names always take the form logN.xml, where N is an integer. For text-based logging, you must specify the log file names.

For each log there is a configuration element in the appropriate OC4J configuration file to enable text-based logging, and a separate element to enable ODL logging. The presence of a logging configuration element enables the associated type of logging.

OC4J supports the following logs:

  • Application log: There is a log for each application deployed, as configured in orion-application.xml. For text-based logging, a typical name is application.log.

  • Global application log: There is a log for global logging for all applications, including the default application, as configured in the OC4J global application.xml file. For text-based logging, a typical name is global-application.log.

  • JMS log: There is a log for Java Message Service (JMS) functionality, as configured in jms.xml. For text-based logging, a typical name is jms.log.

  • RMI log: There is a log for remote method invocation functionality, as configured in rmi.xml. For text-based logging, a typical name is rmi.log.

  • Server log: There is a server-wide log, as configured in server.xml. For text-based logging, a typical name is server.log.

  • Web site access log: There is a Web site access log (one log file for each Web site to log all accesses of the site), as configured in default-web-site.xml. For text-based logging, a typical name is http-access.log.


    Note:

    For Web site access logging, you can use only one type of logging, not both.

Configuration of the Web access log is covered in the Oracle Application Server Containers for J2EE Servlet Developer's Guide. The Oracle Application Server Containers for J2EE User's Guide has information about how to enable logging to the other OC4J files.

In addition to the OC4J log files discussed previously, Oracle Application Server supports the following log files:

  • OPMN log file (one log file for each OC4J instance, for Oracle Process Management and Notification functionality)

  • ons.log (OPMN notification system log, configured in opmn.xml)

  • ipm.log (OPMN process management log, configured in opmn.xml)

OPMN manages Oracle HTTP Server and OC4J processes within an application server instance. For information about this, refer to the Oracle Application Server 10g Administrator's Guide.

3.1.2.10 Load Balancing and Fault Tolerance

This section describes issues and configuration for load balancing and fault tolerance in JServ and OC4J.

3.1.2.10.1 Request Routing and Load Balancing in JServ

JServ supports request routing by appending the appropriate JServ instance ID to the session ID when an HttpSession object is used.

When an HTTP request is received before a session is started, an arbitrary JServ instance is chosen from the available instances to service the request, and a cookie with the JServ instance ID is sent back to the Web browser (or other HTTP client). Later, when the next request comes from the same session, it is forwarded to the same JServ instance by matching the JServ ID. (If the original JServ instance is down, the request will be forwarded automatically to an alternative instance.)

Given this functionality, HttpSession objects in JServ are non-distributable—the session object cannot be distributed between different JServ instances. As a result, a long-lived HTTP session in JServ decreases the flexibility of load balancing. Also, the session data is lost if the corresponding JServ JVM crashes. Fault tolerance is low, because there is no session failover functionality.

3.1.2.10.2 Load Balancing and Fault Tolerance in OC4J

OC4J supports clusters of OC4J instances, and clusters can be customized to the specific needs of the users. Through OC4J load balancing, more user traffic can be handled by distributing the request workload to multiple servers within the cluster. OC4J can be configured to replicate the state of each individual node to the cluster. (The state information is not saved to any persistent storage, but is in memory.) Through OC4J fault tolerance, in case of the failure of a server, a client can automatically be redirected to an alternative server in the cluster. Oracle HTTP Server performs this failover.

In OC4J, HTTP sessions are replicated to other OC4J JVM instances within a load-balanced cluster island. This preserves session state in case of JVM failure, and is a feature that is not available in JServ.

Assuming proper configuration, when the request is routed through another JVM in the cluster island, the session state is available in the other JVM as well. Furthermore, the session state is still available even in individual JVM failure scenarios. The Web application proceeds smoothly.

For this functionality, the Web application must be marked as "distributable" through the <distributable> element of the application web.xml file. Objects in a distributable HttpSession instance must be serializable or remoteable for the replication to work properly.

See the Oracle Application Server 10g Performance Guide for more information about OC4J load balancing and fault tolerance.

3.1.2.10.3 Clarification on loadbalancer.jar

It is advisable to use loadbalancer.jar as a utility to test distribution of load in development and test environments only. It was not designed for production environments and should not be used in production environments.

In production environments, use Oracle HTTP Server, OPMN, and mod_oc4j for load balancing.

3.1.2.11 Example: JServ to OC4J Upgrade

This section provides an example of upgrading a Web application from Apache JServ to OC4J, noting both the original JServ configuration settings and the OC4J configuration settings. This example does not necessarily reflect a typical or optimal scenario; it is merely for illustrative purposes.

The example includes two servlets (source files HelloWorldServlet.java and SessionServlet.java), two JSP pages (Hello.jsp and snoop.jsp), and accompanying .gif and index.html files.

3.1.2.11.1 JServ Configuration

This section describes the pre-upgrade JServ directory structure and configuration files.

JServ Directory Structure  The JServ directory structure is shown below:
/private/scott-sun/upgrade-example/
                   index.html
                   classes/
                            HelloWorldServlet.java
                            SessionServlet.java
                   jsps/
                            Hello.jsp
                            snoop.jsp
                   examples/
                            index.html
                            images/
                                   blk_line_bullet_35.gif
                                   red_arrow_bullet_35.gif

JServ Configuration Files  The following JServ configuration files would have related entries. (The entries for each file are described in the subsections immediately following.)
APACHE_HOME/apache/conf/jserv/jserv.conf
                              jserv.properties
                              zone.properties

Entries in the jserv.conf File  In this example, the jserv.conf file includes the following entries:
Alias  /migdemos /private/scott-sun/upgrade-example
ApJServMount /servlet  /root

Entries in the jserv.properties File  In this example, the jserv.properties file includes the following entries:
zones=root

# Configuration file for each servlet zone (one per servlet zone)
# Syntax: [servlet zone name as on the zones list].properties=
#                                      [full path to configFile] (String)
# Default: NONE
# Note: if the file could not be opened, try using absolute paths.
root.properties=/private/scott-sun/apache/conf/jserv/zone.properties

Entries in the zone.properties File  In this example, the zone.properties file includes the following entries:
# List of Repositories
#######################

# The list of servlet repositories controlled by this servlet zone
# Syntax: repositories=[repository],[repository]...
# Default: NONE
# Note: The classes you want to be reloaded upon modification should be put
# here.
repositories=/private/scott-sun/upgrade-example/classes

URLs for Invocation in JServ  Assuming the preceding configuration, you could use the following URLs (specifying the appropriate port) to directly invoke the various pages.

To invoke the servlets:

http://scott-sun:port/servlet/HelloWorldServlet
http://scott-sun:port/servlet/SessionServlet

To invoke the JSP pages:

http://scott-sun:port/migdemos/jsps/Hello.jsp
http://scott-sun:port/migdemos/jsps/snoop.jsp

To invoke the index HTML pages:

http://scott-sun:port/migdemos/index.html
http://scott-sun:port/migdemos/examples/index.html

3.1.2.11.2 OC4J Configuration

This section describes the OC4J directory structure and configuration files. For this discussion, assume an OC4J standalone environment for initial development.

Initially, of course, the EAR file (upgrade-example.ear) and WAR file (upgrade-example.war) would not yet exist. You would create them after the rest of the directory structure had been established. They are shown here within the directory structure, with contents nested beneath them, for illustrative purposes.

OC4J Directory Structure  The OC4J directory structure is shown below:
/private/scott-sun/upgrade-example/
                     upgrade-example.ear

                       META-INF/
                                application.xml
                       upgrade-example.war
                           index.html
                           WEB-INF/
                                   web.xml
                                   orion-web.xml

                                   classes/
                                            HelloWorldServlet.java
                                            SessionServlet.java

                                   jsps/
                                            Hello.jsp
                                            snoop.jsp

                                   examples/
                                             index.html

                                             images/
                                                    blk_line_bullet_35.gif
                                                    red_arrow_bullet_35.gif

The WAR file has the following structure:

META-INF/
META-INF/MANIFEST.MF
WEB-INF/
WEB-INF/classes/
WEB-INF/classes/HelloWorldServlet.java
WEB-INF/classes/SessionServlet.java
WEB-INF/web.xml
WEB-INF/orion-web.xml
jsps/
jsps/Hello.jsp
jsps/snoop.jsp
examples/
examples/index.html
examples/images/
examples/images/blk_line_bullet_35.gif
examples/images/red_arrow_bullet_35.gif
index.html

The EAR file has the following structure:

META-INF/
META-INF/MANIFEST.MF
META-INF/application.xml
upgrade-example.war

Deploy the EAR file according to OC4J deployment conventions. See the Oracle Application Server Containers for J2EE User's Guide and the Oracle Application Server Containers for J2EE Servlet Developer's Guide for more information.

Some points to consider for OC4J upgrade and deployment:

  • OC4J does not require that servlets be recompiled, but it might be useful to recompile in order to discover any deprecated servlet 2.0 methods in use. (The servelts with deprecated methods would still run in OC4J.)

  • In a servlet 2.0 environment, there are no separate servlet contexts—all servlets are grouped together. In a servlet 2.2 or 2.3 environment, you are deploying into a particular servlet context, per the WAR file. Interdependencies between servlets that work effectively together in JServ, but are in different contexts in OC4J, will cause runtime problems in OC4J.

  • Place application-specific library or utility JAR files in the WEB-INF/lib directory.

  • In Oracle Application Server 10g (9.0.4) in particular, place system-wide library or utility JAR files in the j2ee/home/applib directory, where they will be accessible to all applications.

System-wide path settings, such as for class file and JAR file locations, are specified in the global application.xml file. This is where, for example, j2ee/home/applib is set as a server-wide library location.

Entries in the application.xml File  In this example, the application.xml file includes the following entries:
<?xml version="1.0"?>
<!DOCTYPE application PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE Application 1.
2//EN" "http://java.sun.com/j2ee/dtds/application_1_2.dtd">
<application>
  <display-name>OC4J demo application</display-name>
  <description>
     Collection of servlet samples.
  </description>
  <module>
    <web>
      <web-uri>upgrade-example.war</web-uri>
      <context-root>/migdemos</context-root>
    </web>
  </module>
</application>


Note:

Each application has its own standard application.xml file containing application-specific settings. Do not confuse this with the OC4J global application.xml file mentioned earlier, which contains server-wide settings.

Entries in the orion-web.xml File  In this example, the orion-web.xml file includes the following entries:
<?xml version="1.0"?>
<!DOCTYPE orion-web-app PUBLIC "-//Evermind//DTD Web Application 2.3//EN"
"http://xmlns.oracle.com/ias/dtds/orion-web.dtd">

<orion-web-app
        deployment-version="OracleAS 9.0.4"
        servlet-webdir="/servlet"
>
</orion-web-app>

Entries in the web.xml File  In this example, the web.xml file includes the following entries:
<?xml version="1.0"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN
" "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">

<web-app>
        <!-- A demo servlet, add servlets below -->
        <servlet>
                <servlet-name>HelloServlet</servlet-name>
                <servlet-class>HelloWorldServlet</servlet-class>
        </servlet>
        <welcome-file-list>
                <welcome-file>index.html</welcome-file>
        </welcome-file-list>
</web-app>

URLs for Invocation in OC4J  Assuming the preceding configuration, you could use the following URLs (specifying the appropriate port) to directly invoke the various pages.

To invoke the servlets:

http://scott-sun:port/migdemos/servlet/HelloWorldServlet
http://scott-sun:port/migdemos/servlet/SessionServlet

(The servlet-webdir setting in orion-web.xml is relevant here.)

To invoke the JSP pages:

http://scott-sun:port/migdemos/jsps/Hello.jsp
http://scott-sun:port/migdemos/jsps/snoop.jsp

To invoke the index HTML pages:

http://scott-sun:port/migdemos/index.html
http://scott-sun:port/migdemos/examples/index.html

3.1.3 Oracle Data Source Considerations

There are a number of considerations in upgrading from Oracle9iAS Release 1 (1.0.2.2.x) to Oracle Application Server 10g (9.0.4) regarding data sources, including features supported in the 9.0.4 implementation that were not supported in the 1.0.2.2 implementation. Consider the points that follow.


Note:

Refer to the 10g (9.0.4) release of the Oracle Application Server Containers for J2EE Services Guide for detailed information about current data source features.

  • For emulated data sources, always use ejb-location to specify the JNDI name. Also be aware that although location and xa-location are ignored, they still must be present in the <data-source> element of data-sources.xml, for reasons relating to backward compatibility. (The requirement of specifying xa-location was not clarified in the Oracle9iAS Release 1 (1.0.2.2.x) documentation.)

  • Non-emulated data sources and two-phase commit, which were not supported in the 1.0.2.2 implementation, are supported in the 10g (9.0.4) implementation. Specify only location; do not use ejb-location, pooled-location, or xa-location for non-emulated data sources.

  • Native data sources are also supported in the 10g (9.0.4) implementation.

  • For EJB CMP functionality, you can now associate a database schema with a data source. This is configured in a database schema XML file—referenced through the schema attribute of the <data-source> element—that you can customize for the database you are using, as desired. (When using CMP, the EJB container is responsible for creating the database schema necessary to persist a bean. Associating a data source with a database schema XML file allows you to influence the SQL that is ultimately generated by the container. This can help you solve problems such as accommodating additional data types supported in your application but not in your database.)

  • The data source implementation now supports Real Application Clusters (RAC), through the rac-enabled attribute of the <data-source> element.

  • The data source implementation now supports High Availability, through features described in the Oracle Application Server 10g (9.0.4) documentation.

  • Password specification in data-sources.xml can now be obfuscated.

  • All attributes of the <data-source> element are supported in the 9.0.4 implementation.

  • The Merant drivers mentioned in the Oracle9iAS Release 1 (1.0.2.2.x) documentation have been renamed "DataDirect".


Note:

In an Oracle Application Server environment, use Enterprise Manager to configure data sources. If you modify any XML configuration files directly, including data-sources.xml, you must use the dcmctl utility to ensure that Enterprise Manager is aware of any changes. This is described at the beginning of Section 3.1, "Upgrade Considerations for OC4J Applications".

3.1.4 OracleAS JAAS Provider Considerations

This section discusses considerations for customers who will use Oracle Application Server Java Authentication and Authorization Service in Oracle Application Server 10g (9.0.4).

3.1.4.1 Upgrading the principals.xml File to OracleAS JAAS Provider

In Oracle9iAS Release 1 (1.0.2.2.x) OC4J security services, the principals.xml file defined users and groups for mapping to roles defined in application deployment descriptors.

In Oracle Application Server 10g (9.0.4), security services are provided through the Java Authentication and Authorization Service (JAAS). For information about JAAS, see the Oracle Application Server 10g Security Guide. The principals.xml file is still supported for backward compatibility.

The JAAS Admintool is provided for security administrators to manage users, realms, roles and policies. It has a command switch that allows you to migrate principals.xml to a JAAS realm, which is generally advisable. The syntax is:

java -jar jazn.jar -convert <filename> <realm>

where

filename is the name and location of the OC4J principals.xml file and realm is the realm defined in the JAAS. For example:

java -jar jazn.jar -convert /home/config/principals.xml MyCompanyRealm

All permissions granted to a principals.xml group are granted to the respective JAAS role. Users that were deactivated are not upgraded. See Chapter 5 of the Oracle Application Server 10g Security Guide for additional usage information.

3.1.5 Using the Compatibility Test Suite (CTS) Flag for Backward Compatibility

In Oracle Application Server 10g (9.0.4), OC4J by default complies with the J2EE 1.3 specification. In some cases, this results in behavior that differs from that seen with previous OC4J implementations. To allow for backward compatibility, OC4J supports a CTS compliance flag that you can set to false to revert to previous OC4J behavior in the following components:

  • Oracle JMS

  • Oracle JDBC

  • Oracle XML parser for JAXP/XDK

The compliance behavior of OC4J is determined by the flag oracle.cts.useCtsFlags, with a default value of true. If any of the upgrade issues are critical in a particular application, you can disable CTS compliance and revert to old behavior for an OC4J instance by setting the flag value to false in an OC4J properties file and providing the location of the properties file to OC4J.

For example, the file <destination_MT_OH>/j2ee/home/config/oc4j.properties might contain the setting:

oracle.cts.useCtsFlags=false

Supply the name and location of a properties file to OC4J through an <oc4j-option> element in the <destination_MT_OH>/opmn/conf/opmn.xml file, as in the following example:

<oc4j>
...
 <oc4j-option value="-p
 destination_MT_OH/j2ee/home/config/oc4j.properties"/>...
</oc4j>

This is equivalent to starting OC4J as follows in standalone mode with the following command:

java -jar oc4j.jar -p <destination_MT_ OH>/j2ee/home/config/oc4j.properties


Note:

In an Oracle Application Server environment, use Enterprise Manager to make any configuration changes. If you must update any configuration files directly, use the dcmctl utility so that Enterprise Manager is aware of the changes, as described at the beginning of Section 3.1, "Upgrade Considerations for OC4J Applications".

3.1.5.1 CTS Compatibility and Oracle JMS (OJMS)

In the Oracle Application Server 10g (9.0.4) implementation of (OJMS), which complies with J2EE 1.3, some behavior differs from OJMS behavior in Oracle9iAS Release 1 (1.0.2.2.x). (There are no such upgrade considerations between Oracle9iAS Release 2 (9.0.2) and Oracle Application Server 10g (9.0.4).) The differences are identified in Table 3-2.

Table 3-2 OJMS Behavior in Oracle9iAS Release 1 (1.0.2.2.x) and Oracle Application Server 10g (9.0.4)

Item Behavior in Oracle9iAS Release 1 (1.0.2.2.x) OJMS Implementation Behavior in Oracle Application Server 10g (9.0.4) OJMS Implementation
JMSExpiration The JMSExpiration header value in a dequeued message is the duration until expiration of the message, in milliseconds. If a message never expires, the value is -1. The JMSExpiration header value in a dequeued message is the sum of the JMS timestamp when the message was enqueued, and the time-to-live. This value is expressed in milliseconds from midnight, January 1, 1970 to the current Greenwich Mean Time. If a message never expires, the value is 0.
JMSPriority In this implementation, java.lang.Integer.MIN_VALUE is the highest priority, Integer.MAX_VALUE is the lowest priority, and 1 is the default priority. In this implementation, 9 is the highest priority, 0 is the lowest priority, and 4 is the default priority.
Durable Subscribers Durable Topic Subscribers with the same name are allowed if they are subscribed to different topics. Durable Topic Subscribers with the same name are not allowed under any circumstances.
Strongly typed JMS selectors Not subject to the restrictions listed for 10g (9.0.4), or to the limited subset of SQL92 syntax for selector expression syntax. In compliance with the JMS 1.02b specification and J2EE 1.3 compliance requirements, the OJMS 9.0.4 implementation uses only a certain subset of SQL92 syntax for selector expression syntax, with the following mandated restrictions:
  • Selector expressions are strongly typed, meaning operators and operands in arithmetic comparisons must be of the same type. Automatic type conversions for the purpose of comparison, such as converting the string "1" to the integer 1, are prohibited.

  • String and boolean comparisons are restricted to "=", "<", and ">". Two strings are equal only if they contain the exact same sequence of characters.

  • The "!=" operator is prohibited.


3.1.5.2 CTS Compatibility and JDBC

In the Oracle Application Server 10g (9.0.4) implementation of Oracle JDBC, which complies with J2EE 1.3, some behavior differs from JDBC behavior in previous releases. The differences are identified in Table 3-3.

Table 3-3 JDBC Behavior in Oracle9iAS Release 1 (1.0.2.2.x) and Oracle Application Server 10g (9.0.4)

Item Behavior in Oracle9iAS Release 1 (1.0.2.2.x) JDBC Implementation Behavior in Oracle Application Server 10g (9.0.4) JDBC Implementation
Java types for NUMBER columns getObject() returns a BigDecimal value for any NUMBER column. (This is also true for Release 2 (9.0.2).) The getObject() method of a result set (java.sql.ResultSet instance) returns a java.lang.Double value for a NUMBER column with precision, or a java.math.BigDecimal value for a NUMBER column without precision.
Metadata for NUMBER columns getColumnTypeName() returns "NUMBER" for any NUMBER column, and getColumnType() returns Types.NUMBER for any NUMBER column. (This is also true for Release 2 (9.0.2.) The getColumnTypeName() method of a result set metadata object (java.sql.ResultSetMetaData instance) returns "FLOAT" for a NUMBER column with precision, or "NUMBER" for a NUMBER column without precision. The getColumnType() method returns java.sql.Types.FLOAT for a NUMBER column with precision, or Types.NUMBER for a NUMBER column without precision.
Java types for DATE and TIMESTAMP columns getObject() returns a java.sql.Timestamp value for a DATE column. (TIMESTAMP columns were not supported.) The getObject() method of a result set returns a java.sql.Date value for a DATE column, and a java.sql.Timestamp value for a TIMESTAMP column.
Exceptions for inappropriate SQL statements Inappropriate SQL statements do not result in exceptions. If an executeQuery() call in a statement object contains anything but a SELECT statement (such as if it instead contains an INSERT or UPDATE statement), the JDBC driver properly throws an exception. Similarly, if an executeUpdate() call contains a SELECT statement, the driver properly throws an exception. (An UPDATE, INSERT, or DELETE statement is expected.)

3.1.5.3 CTS Compatibility and the JAXP/XDK XML Parser

In the Oracle Application Server 10g (9.0.4) implementation of the XML parser for JAXP/XDK, which complies with J2EE 1.3, some behavior differs from XML parser behavior in previous releases. The key differences are described in Table 3-4:

Table 3-4 JAX/XDK XML Parser Behavior in Oracle9iAS Release 1 (1.0.2.2.x) and Oracle9iAS Release 2 (9.0.2) versus Oracle Application Server 10g (9.0.4)

Item Behavior in Oracle9iAS Release 1 (1.0.2.2.x) and Oracle9iAS Release 2 (9.0.2) XML Parser Implementation Behavior in Oracle Application Server 10g (9.0.4) XML Parser Implementation
getNamespaceURI() null return values The getNamespaceURI() method returns '""' if the namespace is not defined for an element or attribute. The getNamespaceURI() method returns null if the namespace is not defined for an element or attribute.
getLocalName() null return values The getLocalName() method returns '""' if the element or attribute was created using a DOM level 1 API call to createElement() or createAttribute(). The getLocalName() method returns null if the element or attribute was created using a DOM level 1 API call to createElement() or createAttribute().
getPrefix() null return values The getPrefix() method returns '""' if the element or attribute was created using a DOM level 1 API call to createElement() or createAttribute(). The getPrefix() method returns null if the element or attribute was created using a DOM level 1 API call to createElement() or createAttribute().

Note: The getNamespaceURI(), getLocalName(), and getPrefix() methods exist with the above changes in the XMLElement and XMLAttr classes of the oracle.xml.parser.v2 package.

SAX exceptions Error handlers throw an XMLParseException in error conditions. Registered error handlers throw a SAXException or SAXParseException in error conditions.
I/O exceptions An IOException is wrapped in an XMLParseException. An IOException is thrown as is in I/O error conditions.
Insignificant white space Insignificant white space was preserved only by explicit request, by the method call XMLParser.setPreserveWhitespace(true). The default behavior of the XML parser regarding the preservation of insignificant white space depends on the presence of a DTD in the XML document being parsed. If a DTD is present, then insignificant white space is not preserved.

To ensure the same behavior with the 9.0.4 implementation as with the 1.0.2.2 or 9.0.2 implementation, add the XMLParser.setPreserveWhitespace() call to the code.


3.1.6 Upgrade Considerations for Enterprise Java Beans

In Oracle Application Server 10g (9.0.4), OC4J complies with the J2EE 1.3 specification and implements the Enterprise Java Beans (EJB) 2.0 specification in its entirety. Therefore, if you are upgrading to the OC4J 9.0.4 implementation, applications using EJB features in the areas of container-managed persistence and container-managed relationships will require modification.

See Oracle Application Server Containers for J2EE Enterprise JavaBeans Developer's Guide, Appendix C.

3.1.7 JDK 1.4 Issues: Cannot Invoke Classes Not In Packages

Among the upgrade considerations in moving to a Sun Microsystems JDK 1.4 environment, which is the environment that is shipped with Oracle Application Server 10g (9.0.4), 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 earlier environment will no longer work in an OC4J 9.0.4 / JDK 1.4 environment.

Until you update your application so that all JavaBeans and other invoked classes are within packages, you have the alternative of reverting back to a JDK 1.3.1 environment to avoid this issue.


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 through a <java-compiler> element in 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 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

The link "Incompatibilities Between Java 2 Platform, Standard Edition, v1.4.0 and v1.3" specifically addresses this issue.

3.2 OC4J Upgrade Items

An upgrade item is an aspect of configuration that is acted upon during upgrade: a file, executable, or a setting that you must add, change, or delete/replace in the 10g (9.0.4) installation. OC4J upgrade items are described in Table 3-5.

Table 3-5 OC4J Upgrade Items

Upgrade Item Location in Release 1 (1.0.2.2.x) Oracle home Location in 10g (9.0.4) Oracle home Notes
data-sources.xml j2ee/home/config j2ee/home/config Contains data sources for database connections.
principals.xml j2ee/home/config j2ee/home/config The principals.xml file defines users and groups for mapping to roles that are defined in application deployment descriptors. It is still supported for backward compatibility, so you may continue using it; upgrade it as described in Section 3.3, "OC4J Upgrade Tasks".

Otherwise, to use the OracleAS JAAS Provider instead, follow the instructions in Section 3.1.4.1, "Upgrading the principals.xml File to OracleAS JAAS Provider".

J2EE applications (*.ear files)

See Section 3.1, "Upgrade Considerations for OC4J Applications" for details on upgrading applications, including the structure and deployment of EAR files.

j2ee/home/applications j2ee/home/applications The server.xml file identifies the applications defined in the OC4J home instance. To upgrade these applications, you deploy them into Oracle Application Server 10g (9.0.4).
jms.xml file queues, topics, and connection factories j2ee/home/config/jms.xml j2ee/home/config/jms.xml
application.xml file entries (e.g., library paths, Java options, OC4J options) j2ee/<name of OC4J instance>/config/application.xml j2ee/<name of OC4J instance>/config/application.xml
opmn.xml file customizations made for OC4J instances that were created by the installer opmn/conf/opmn.xml opmn/conf/opmn.xml Examples of such instances are home, OC4J_WIRELESS, OC4J_DEMOS, OC4J_PORTAL, and OC4J_BI_FORMS.

3.3 OC4J Upgrade Tasks

After you have read Section 3.1, "Upgrade Considerations for OC4J Applications" beginning, addressing any issues that apply to the applications you will upgrade, and have created new application EAR files, you are ready to perform the OC4J upgrade.

  1. Copy <source_MT_OH>/j2ee/home/config/principals.xml to <destination_MT_OH>/j2ee/home/config.

  2. Copy <source_MT_OH>/j2ee/home/config/data-sources.xml to <destination_MT_OH>/j2ee/home/config.

  3. Examine the <source_MT_OH>/j2ee/home/config/server.xml file, noting the paths to each application EAR file you will upgrade.

  4. Deploy each application to the corresponding OC4J home instance, using Oracle Enterprise Manager 10g or the dcmctl deployApplication command.

    • For instructions on using Oracle Enterprise Manager 10g to deploy an application, see Oracle Application Server Containers for J2EE User's Guide

    • For instructions on using the dcmctl utility to deploy an application, see Distributed Configuration Management Reference Guide.

  5. Copy any queues, topics, and connection factories from <source_MT_OH>j2ee/home/config/jms.xml to <destination_MT_OH>j2ee/home/config/jms.xml.

  6. Copy any library paths, Java options, and OC4J options from <source_MT_OH>/j2ee/<name of OC4J instance>/config/application.xml to <destination_MT_OH>j2ee/<name of OC4J instance>/config/application.xml.

  7. Copy any customizations that were made to OC4J instances created by the installer from <source_MT_OH>/ompn/conf/opmn.xml to <destination_MT_OH>/opmn/conf/opmn.xml.

  8. Ensure that the context root defined in <source_MT_OH>/j2ee/home/config/default-web-site.xml is the same as that defined in <destination_MT_OH>/j2ee/home/config/default-web-site.xml. If the context root values are different, then you can do one of the following:

    • Edit <destination_MT_OH>/j2ee/home/config/default-web-site.xml to use the same value defined in <source_MT_OH>/j2ee/home/config/default-web-site.xml. In addition, edit <destination_MT_OH>/Apache/Apache/conf/mod_oc4j.conf to use the context root defined in default-web-site.xml. The problem arises because the original context root defined in the EAR file is different from that used in <source_MT_OH>/j2ee/home/config/default-web-site.xml. You must also use the dcmctl updateconfig command so that the change is reflected in the repository.

    • Use the context root defined in <destination_MT_OH>/j2ee/home/config/default-web-site.xml (which is the original context root defined in the EAR file) to access the application. This means that you will have to change the URL used in Oracle9iAS Release 1 (1.0.2.2.x) to access the application. For example, to access the PetStore demo in Oracle9iAS Release 1 (1.0.2.2.x), the URL is:

      http://<host>:<port>/petstore

      After upgrading to Oracle Application Server 10g (9.0.4), you would use this URL to access the application:

      http://<host>:<port>/estore

3.4 Validating the OC4J Upgrade

Follow the steps below to verify that the OC4J applications that were upgraded are functioning correctly.

  1. Start the Oracle Application Server with these commands:

    1. <destination_MT_OH>/opmn/bin/opmnctl startall

      Oracle Process Management and Notification and all of the processes it manages are started (i.e., Distributed Configuration Management, Oracle HTTP Server, OC4J instances, Oracle Application Server Web Cache, Oracle Application Server Forms Services, and Oracle Application Server Reports Services).

    2. <destination_MT_OH>/bin/emctl start iasconsole

      The Oracle Enterprise Manager Application Server Control is started.

  2. In a browser, access the Oracle Enterprise Manager Application Server Control in the 10g (9.0.4) middle tier Oracle home by entering its URL. Ensure that you provide the correct host name and port number. For example:

    http://midtierhost.mycompany.com:1810

    The Oracle Enterprise Manager page appears. A link for the middle tier instance appears in the Standalone Instances section.

  3. Click the link.

    The System Components page appears.

  4. Verify that the components are running (a green upward arrow appears in the Status column).

  5. Verify that the configuration information for the components in use is reflected in the 10g (9.0.4) Oracle home.

  6. Access each application URL, and verify that the application can perform all of the functions specified in its configuration (you should have a prepared system test for each application).