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 |
|
![]() |
![]() |
This chapter contains step-by-step instructions for upgrading OC4J. It contains the following major sections:
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:
Section 3.1.1, "Upgrading to the OC4J 10g (9.0.4) JSP Environment"
Section 3.1.2, "Upgrading from JServ to the OC4J 10g (9.0.4) Servlet Environment"
Section 3.1.5, "Using the Compatibility Test Suite (CTS) Flag for Backward Compatibility"
Section 3.1.6, "Upgrade Considerations for Enterprise Java Beans"
Section 3.1.7, "JDK 1.4 Issues: Cannot Invoke Classes Not In Packages"
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 thedcmctl utility to notify Enterprise Manager that there have been changes, as follows:
See the Oracle Application Server Containers for J2EE User's Guide for general information about using Enterprise Manager and |
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:
Section 3.1.1.2, "Key Issues for JSP Pages: The Servlet 2.3 Versus Servlet 2.0 Environment"
Section 3.1.1.3, "Issues for Upgrading from the Release 1 (1.0.2.2.x) Orion JSP Container"
Section 3.1.1.5, "JspScopeListener Issues for Upgrading from OracleJSP in Release 1 (1.0.2.2.x)"
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. |
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.
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".
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.
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>
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.
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() %> --------------------------
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" %>
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\")%>"/>
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"
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.
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.
|
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
.
This is the root element of the ojsp-global-include.xml
file. It has no attributes.
Subelements:
<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".
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".
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".
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>
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 |
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.
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.
There are a few relatively minor upgrade considerations regarding the ojspc
pre-translation utility in Oracle Application Server 10g (9.0.4).
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.
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:
(optionally) an orion-application.xml
configuration file, in /META-INF
a standard WAR file
The WAR file includes the following:
(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.
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.
This section covers additional JSP upgrade considerations.
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".
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"); %>
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.
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.
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.
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:
Section 3.1.2.2, "Enterprise Applications Versus Web Applications"
Section 3.1.2.7, "Class Loaders and Automatic Class Reloading"
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 theweb.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.
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.
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.
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
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 thedcmctl 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.
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.
This section discusses the typical OC4J Web application structure and how to configure file locations in OC4J compared to JServ.
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.
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.
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
:
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.
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.)
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.
This section covers a variety of servlet setup issues, reviewing configuration steps for JServ and providing the equivalent steps for OC4J.
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
.
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.
JServ (mod_jserv
) and OC4J (mod_oc4j
) each have "mount" commands to establish application root locations, or "mount points".
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/HelloWorldServletOC4J 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 theOc4jMount 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
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 classexample.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
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.
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.
This section compares servlet pre-start features between the OC4J 9.0.4 implementation and JServ.
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.
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
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.
This section discusses servlet class loaders, and class reloading during servlet execution.
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
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 globalapplication.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.
This section discusses session behavior and related configuration in JServ and OC4J.
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.)
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.
This section compares the JServ and OC4J mechanisms for setting up log files.
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
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.
This section describes issues and configuration for load balancing and fault tolerance in JServ and OC4J.
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.
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.
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.
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.
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.gifJServ 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.propertiesEntries 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 /rootEntries 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.propertiesEntries 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/classesURLs 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
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.
/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.
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 standardapplication.xml file containing application-specific settings. Do not confuse this with the OC4J global application.xml file mentioned earlier, which contains server-wide settings.
|
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
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, includingdata-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".
|
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).
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.
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 thedcmctl utility so that Enterprise Manager is aware of the changes, as described at the beginning of Section 3.1, "Upgrade Considerations for OC4J Applications".
|
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:
|
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.)
|
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 |
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 |
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.
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.
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.
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.xm l
|
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 .
|
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.
Copy <
source_MT_OH
>/j2ee/home/config/principals.xml
to <
destination_MT_OH
>/j2ee/home/config
.
Copy <
source_MT_OH
>/j2ee/home/config/data-sources.xml
to <
destination_MT_OH
>/j2ee/home/config
.
Examine the <
source_MT_OH
>/j2ee/home/config/server.xml
file, noting the paths to each application EAR file you will upgrade.
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.
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
.
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
.
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
.
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
Follow the steps below to verify that the OC4J applications that were upgraded are functioning correctly.
Start the Oracle Application Server with these commands:
<
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).
<
destination_MT_OH
>/bin/emctl start iasconsole
The Oracle Enterprise Manager Application Server Control is started.
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.
Click the link.
The System Components page appears.
Verify that the components are running (a green upward arrow appears in the Status column).
Verify that the configuration information for the components in use is reflected in the 10g (9.0.4) Oracle home.
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).