|
Oracle® Application Server Release Notes
10g Release 2 (10.1.2) for hp-ux PA-RISC (64-bit) B15511-05 |
|
 Previous |
 Next |
|
Oracle® Application Server Release Notes
10g Release 2 (10.1.2) for hp-ux PA-RISC (64-bit) B15511-05 |
|
|
Previous |
Next |
This chapter discusses release notes for Oracle Application Server Containers for J2EE (OC4J). It includes the following topics:
You can access Oracle manuals mentioned in this document at the following URL:
http://www.oracle.com/technology/index.html
This section describes configuration issues and their workarounds for Oracle Application Server Containers for J2EE (OC4J).
This section covers the following topic(s):
Section 5.1.1, "Notes on Oracle JDBC-OCI driver upgrade in the Oracle Application Server"
Section 5.1.3, "Disabling OC4J Access Logging Per Web Application"
For information on configuring OC4J, see the Configuration Guide for OC4J at:
http://www.oracle.com/technology/index.html
It is not possible to upgrade to an arbitrary Oracle JDBC-OCI driver version due to client library compatibility constraints. Upgrading to OCI driver versions with matching Oracle Client libraries, which are installed within the Oracle Application Server 10g (10.1.2) is supported. For example, Oracle JDBC 9.0.1.4.0 and 9.0.1.5.0 are supported, but the Oracle JDBC 9.2.x drivers is not.
Where the use of JDBC-OCI within the Oracle Application Server is supported, it is also necessary for the opmn.xml entry for each OC4J instance to propagate appropriate ORACLE_HOME and library path values to its startup environment.
The environment variable ORACLE_HOME is common to all platforms, but the name of the environment variable that specifies the library path is different depending on the operating systems:
LD_LIBRARY_PATH for Solaris
SLIB_PATH for AIX
SHLIB_PATH for HP-UX
PATH for Windows
The generic syntax for specifying the library paths in opmn.xml looks like this:
<prop name="<LIB_PATH_VARIABLE>" value="<LIB_PATH_VARIABLE_VALUE>"/>
where <LIB_PATH_VARIABLE> should be replaced with the appropriate platform-specific variable name that specifies the library path, and
<LIB_PATH_VARIABLE_VALUE>
should be replaced with that variable's value.
Here is an example, assuming the Solaris OS:
<process-type id="OC4J_SECURITY" module-id="OC4J">
<environment>
<variable id="ORACLE_HOME"
value="/u01/app/oracle/product/inf10120"/>
<variable
id="LD_LIBRARY_PATH"
value="/u01/app/oracle/product/inf10120/lib"
/>
</environment>
...
If the OC4J default JVM heap size is too small for applications that you deploy, then you may see Out Of Memory errors from your OC4J processes. If you review the log files for the OC4J Instance in the directory$ORACLE_HOME/opmn/logs, you may find errors similar to the following:
java.lang.OutOfMemoryError
To work around this problem, increase the specified heap memory by changing the Java command line options for the OC4J Instance.
Using Application Server Control Console, go to the OC4J instance homepage and perform the following steps:
Stop the OC4J Instance.
Drill down to the Server Properties page.
In the Command Line Options area of the Server Properties page, under the heading Multiple VM Configuration, set the Java Options.
For example, enter the following to set the JVM heap sizes to 512 Megabytes:
-Xmx512m
Use the Apply button to apply the changes.
Start the OC4J instance.
For more information, see the Oracle Application Server 10g Performance Guide.
In the OC4J 10.1.2 implementation, there is new functionality in Web site XML files to disable OC4J access logging (used to log requests to the Web site) on a per-module basis.
In general, text-based access logging is enabled for a Web site through the <access-log> subelement of the <web-site> element in the Web site XML file (such as default-web-site.xml or http-web-site.xml). Alternatively, Oracle Diagnostic Logging ("ODL-based access logging") is enabled for a Web site through the <odl-access-log> subelement of the <web-site> element.
As of the 10.1.2 release, you can disable text-based logging or ODL-based logging (as applicable) for a particular Web application (module) through the new access-log attribute of the <web-app> element for that Web application. The <web-app> element is another subelement of <web-site>. A setting of access-log="false" for a Web application overrides any <access-log> or <odl-access-log> element to disable logging during the operation of that Web application.
The following example disables logging for the dms0 module of the default application, but leaves text-based logging enabled for the admin_web module:
<web-site ... > ... <web-app application="default" name="dms0" root="/dms0" access-log="false" /> <web-app application="default" name="admin_web" root="/adminoc4j" /> <access-log path="../log/http-web-access.log" /> ... </web-site>
|
Notes: The default setting is access-log="true". With this setting, functionality is the same as for previous releases, with logging being determined solely through the presence or absence of an <access-log> or <odl-access-log> element.If there is no <access-log> or <odl-access-log> element in a Web site XML file, then logging is disabled anyway and access-log="false" for an application has no additional effect. |
See the 10.1.2 release of the Oracle Application Server Containers for J2EE Servlet Developer's Guide for related information about access logging.
This section describes release notes for servlets. It covers the following topic(s):
The following Servlet issues have been resolved in the 10.1.2 implementation:
Bug 3861451: The suffix of a JSP resource was not processed in a case-sensitive manner when "jsp" was added to the MIME types list. This has been corrected so that all suffixes are treated in a case-sensitive manner.
Bug 3860075: A NullPointerException was thrown in the JAZNFilter.getFilterProperty() method when a filter was recompiled or the source file timestamp was updated.
Bug 3696009: When OC4J was set up behind Web cache, but applications accessed OC4J directly (bypassing Web cache), the getRequestURL() method returned the Web cache host and port instead of the OC4J host and port.
Bug 3287183: The Struts application threw an exception upon OC4J shutdown.
Bug 3050265: The /servlet invocation feature, for invoking a servlet by class name, was available in the OC4J default configuration, resulting in a possibly unintended security hole. This feature is no longer available by default, and should be used only in a development mode.
This section describes release notes for EJB. It covers the following topics:
A corrected version of the Oracle Application Server Containers for J2EE Enterprise JavaBeans Developer's Guide has been issued. See the release note at Section 5.5.1.1, "Corrected Version of the EJB Developer's Guide" for details.
The following orion-ejb-jar.xml attributes are deprecated in releases 9.0.4.1 and 10.1.2:
max-instances-per-pk
min-instances-per-pk
disable-wrapper-cache
disable-wrapper-cache
In addition, the following locking-mode attribute setting is deprecated:
locking-mode="old_pessimistic"
OutOfMemory exceptions occur when deploying EAR files with a large number of EJBs.
As part of the deployment process, wrapper code classes are generated for each EJB. The size of these classes is proportional to the number of business methods on the bean. As a performance optimization, OC4J compiles all wrapper code classes in one compiler invocation. An error can occur if the amount of generated wrapper code is too much for available memory.
A workaround is to direct the deployment process to compile each EJB module's wrapper code individually. You can do this by starting OC4J with the ejbdeploy.batch system property and setting it to false, as in the following example:
-Dejbdeploy.batch=false
|
Note: This workaround should only be used when this specific exception occurs.This workaround may result in an increased deployment time for the application. |
EJB wrapper code compilation fails when running in zh_CN.GB18030 locale. When running in zh_CN.GB18030 locale, parts of the EJB wrapper source code may be generated with missing characters. This causes compilation errors. The missing characters in the generated source code are due to a Sun bug documented at:
http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4954023
The workaround is to use a different locale. See the Sun bug for details.
This section describes release notes for OC4J services. OC4J Services include: Java Naming and Directory Interface (JNDI), Java Message Service (JMS), Data Sources, Oracle Remote Method Invocation (ORMI), J2EE Interoperability (IIOP), Java Transaction API (JTA), J2EE Connector Architecture (J2CA), and Java Object Cache.
The section contains the following release note(s):
OC4J only creates IPv4 sockets. Even on dual network stack machines (with both IPv4 and IPv6 stacks available) OC4J creates only IPv4 sockets. This may cause a problem if client-issued requests are from a IPv6 system. This is indicated by connection-refused messages from the server to the IPv6 client. To avoid this problem, start the client process with the system property java.net.preferIPv4Stack=true. This forces the client to only issue IPv4 requests, allowing it to communicate with the server.
It should be noted that the ORMI protocol is not secure. Any and all communication over ORMI is not encrypted including security credentials. Customers that want to encrypt ORMI traffic are advised to use ORMI over HTTPS, which will encrypt all communication between the client and the server.
This tutorial describes the steps necessary to enable IIOP applications in OC4J. After completing this exercise you should be able to:
Access a remote EJB over IIOP
Secure EJB invocations with IIOP over SSL
Secure corbaname lookups by remote clients with IIOP over SSL
To minimize deployment and configuration changes, the tutorial uses the demo "helloworld" EJB application available through the installation and on Oracle's OTN site:
http://www.oracle.com/technology/sample_code/tech/java/ejb_corba/index.html
Building and deploying the helloworld application with a default OC4J installation results in an application that is only accessible over ORMI. To enable IIOP for a given application you must make the following changes to OC4J's server configuration and the client application. The required changes include:
Configure the IIOPServerExtensionProvider
Change the java.naming.provider.url
Deploy the application using the -iiopClientJar argument
The following sections describe the steps in more detail.
Getting Started
Expand the EJB demos to your development environment. The helloworld application should be under <install-dir>/demo/ejb/helloworld with the following structure:
|-------dist |-------etc | |-------application-client.xml | |-------application.xml | |-------ejb-jar.xml | |-------jndi.properties |-------src | |-------ejb | | |-------client | | | |-------HelloClient.java | | |-------helloworld-ejb | | |-------Hello.java | | |-------HelloBean.java | | |-------HelloHome.java | | |-------HelloLocal.java | | |-------HelloLocalHome.java |------build.xml
Applications other than the helloworld example can be ignored for the remainder of the tutorial, but should be unaffected by changes required for enabling IIOP. This tutorial installs the demos to the root partition, so the application is under /demo/ejb/helloworld.
The supplied Ant build file provides targets for compiling the src, building the jar and ear, and running the client application. This tutorial assumes you are familiar with Ant build files. If you are unfamiliar with Ant, please see Apache's Ant documentation site: http://ant.apache.org/manual/index.html
Configure IIOP in OC4J
Edit the server.xml file as follows:
<install-dir>j2ee/home/config/internal-settings.xml
Make sure the server.xml file contains the following line:
<sep-config path="./internal-settings.xml" />
If the line is missing, or commented out, remove the comments or add the line below the following line:
<rmi-config path="./rmi.xml" />
This configures the IIOPServerExtensionProvider for OC4J.
Now edit the internal-settings.xml file as follows to configure your IIOP settings:
<install-dir>j2ee/home/config/internal-settings.xml
Make sure the file contains the following settings:
<server-extension-provider name="IIOP" class="com.oracle.iiop.server.IIOPServerExtensionProvider"> <sep-property name="port" value="5555" /> <sep-property name="host" value="localhost" /> <sep-property name="ssl" value="false" /> <sep-property name="trusted-clients" value="*" /> </server-extension-provider>
If necessary, you can modify the host and port to match your environment. If your file contains entries for SSL, temporarily comment them out:
<!-- <sep-property name="ssl-port" value="5556" /> <sep-property name="ssl-client-server-auth-port" value="5557" /> <sep-property name="keystore" value="keystore.jks" /> <sep-property name="keystore-password" value="->pwForSSL" /> <sep-property name="truststore" value="truststore.jks" /> <sep-property name="truststore-password" value="->pwForSSL" /> -->
Now OC4J is configured for IIOP. The final step to enable IIOP on the server side is to start OC4J with the JVM argument: -DgenerateIIOP=true. This can be done on the command line for OC4J standalone, and in the ${ORACLE_HOME}/opmn/opmn.xml file for Oracle Application Server installs.
Configure the JNDI provider URL
Edit the jndi.properties file as follows for the helloworld application:
<install-dir>/demo/ejb/helloworld/etc/jndi.properties java.naming.factory.initial=com.evermind.server.ApplicationClientInitialContextFactory java.naming.provider.url=corbaname:iiop:localhost:5555#helloworld #java.naming.provider.url=ormi://localhost:23791/helloworld java.naming.security.principal=admin java.naming.security.credentials=welcome
Comment out the line containing the ORMI provider URL, and add a line matching the corbaname provider URL in the example.
Build and deploy the application
From the <install-dir>/demo/ejb/helloworld directory, run the default ant target to build the application:
<install-dir>/demo/ejb/helloworld > ant
Start OC4J if you have not done so already, then execute the following deploy command:
java -jar ${J2EE_HOME}/admin.jar ormi://localhost:23791 admin welcome -deploy -file dist/helloworld.ear -deploymentName helloworld -iiopClientJar dist/helloworld_iiop_client.jar
This deploys the helloworld application and generates the client EJB JAR containing the client IIOP stubs in dest/helloworld_iiop_client.jar.
Run the application
Edit the <install-dir>/demo/ejb/common.xml file, and make sure the environment settings for ORACLE_HOME, JAVA_HOME, and J2EE_HOME match your environment.
Execute > ant run
You should see the appropriate "Hello ..." response from the client application. To verify that communication is running over IIOP, you can set the following JMV arg on both the client and the server:
-Diiop.runtime.debug=true
Enable IIOP over SSL on the server
Edit the internal-settings.xml file and uncomment or add the SSL settings (indicated by the bold lines in the following example):
<server-extension-provider name="IIOP" class="com.oracle.iiop.server.IIOPServerExtensionProvider"> <sep-property name="port" value="5555" /> <sep-property name="host" value="localhost" /> <sep-property name="ssl" value="true" /> <sep-property name="trusted-clients" value="*" /> <sep-property name="ssl-port" value="5556" /> <sep-property name="ssl-client-server-auth-port" value="5557" /> <sep-property name="keystore" value="keystore.jks" /> <sep-property name="keystore-password" value="yourPWD" /> <sep-property name="truststore" value="truststore.jks" /> <sep-property name="truststore-password" value=" yourPWD " /> </server-extension-provider>
If necessary, you can modify the host and port to match your environment. The keystore and truststore files may be the same physical file. The preceding names are only for illustration. If you do not have a keystore file, you can use the following Sun example for using the keytool:
http://java.sun.com/docs/books/tutorial/security1.2/summary/tools.html
Add the absolute path and filename to the keystore and truststore properties in the example.
Enable SSL on the client
Edit the jndi.properties file for the helloworld application:
<install-dir>/demo/ejb/helloworld/etc/jndi.properties java.naming.factory.initial=com.evermind.server.ApplicationClientInitialContextFactory java.naming.provider.url=corbaname:iiop:localhost:5556#helloworld java.naming.security.principal=admin java.naming.security.credentials=welcome
Change the port in the provider URL to be the SSL port from internal-settings.xml.
Create a file called ejb_sec.properties for the helloworld application:
oc4j.iiop.trustedServers=* nameservice.useSSL=true oc4j.iiop.trustStoreLoc=<path to server's keystore> oc4j.iiop.trustStorePass=<password for server's keystore file>
This file communicates the applications security requirements to the OC4J client bootstrap classes. The properties in this example indicate that SSL should be used for EJB lookups, and that all servers supporting SSL should be trusted. The truststore setting is a quick way of using the same keystore configured for OC4J instead of exporting the certificate in the servers keystore and importing it into a second truststore file.
Run the application with IIOP over SSL
Execute > ant run
You should see the appropriate "Hello ..." response from the client application. To verify that communication is running with IIOP over SSL, set the -Diiop.runtime.debug=true for both the client and the server.
This section describes release notes for J2EE Connector Architecture (J2CA). It includes the following topic:
The following J2EE Connector Architecture (J2CA) issues have been resolved in the 10.1.2 implementation:
Bug 3624173: A proper error was not generated upon failure to look up a data source. Related issues also uncovered a bug in the OC4J ApplicationConnectionManager.init() method, which should not bind a connection factory into JNDI if the associated principal mapping mechanism cannot be created successfully.
Bug 2990051 (3529400 related): When connection pooling was disabled, only the connection handle, not the physical connection, was closed upon commit or rollback. The physical connection should be closed as well.
Bug 3525933: When user code calling ManagedConnectionFactory.matchManagedConnection() resulted in a NotSupportedException, the OC4J ApplicationConnectionManager.allocateConnection() method likewise threw a NotSupportedException. Essentially, this meant that if the user disabled connection pooling, OC4J would always abort at an allocateConnection() call. Instead, OC4J should catch the NotSupportedException error and create a connection without using a pool.
This section describes known errors in the OC4J documentation in Oracle Application Server 10g Release 2 (10.1.2). It covers the following books:
This section describes known errors in the Oracle Application Server Containers for J2EE Enterprise JavaBeans Developer's Guide. It includes the following topic(s):
The version of the Oracle Application Server Containers for J2EE Enterprise JavaBeans Developer's Guide that was included on the original documentation library CD-ROM for release 10.1.2 Phase 1 contains information regarding timers that is not applicable for the 10.1.2 release. The incorrect version of the manual is identified on the title page by "Part No. B15505-01" and the Print Date "NOVEMBER 2004".
The corrected version of Oracle Application Server Containers for J2EE Enterprise JavaBeans Developer's Guide for 10.1.2 is identified on the title page by "Part No. B15505-02" and the Print Date "JANUARY 2005". The corrected version of the manual is available on any subsequent documentation library CD-ROM for release 10.1.2 and in the online documentation library located on OTN at:
http://www.oracle.com/technology/documentation/appserver1012.html
This section describes known errors in the Oracle Application Server Containers for J2EE JSP Tag Libraries and Utilities Reference. It includes the following topic(s):
For the 10.1.2 OC4J documentation release, the chapter on Personalization tags in the Oracle Application Server Containers for J2EE JSP Tag Libraries and Utilities Reference has been removed due to the status of Oracle Application Server Personalization in Phase I of the 10.1.2 release. This chapter will be returned to the document in the 10.1.3 release. In the meantime, anyone interested can refer to the 9.0.4 OC4J documentation set for information about this tag library.
This section describes known errors in the Oracle Application Server Containers for J2EE User's Guide. It includes the following topic(s):
Section 5.5.3.1, "An OC4J Process Is Not "Contained" in an OC4J Instance"
Section 5.5.3.2, "Correct Cross Reference for Metric-Based Load Balancing Information"
Section 5.5.3.3, "JDK 1.4.2 Supported and Installed with OC4J"
Section 5.5.3.4, "Primers Content Removed from OC4J User's Guide"
The following incorrect statement appears in the Oracle Application Server Containers for J2EE User's Guide Chapter 8, OC4J Clustering:
"Each OC4J process is contained in an OC4J instance and inherits its configuration from the OC4J instance. All applications deployed to an OC4J instance are deployed to all OC4J processes in the OC4J instance."
The statement is incorrect in that an OC4J process as such can only be "contained" in other processes, an OC4J instance is not a process.
The correct statement in this case is:
"Each OC4J process is associated to an OC4J instance and inherits its configuration from that OC4J instance. All applications deployed to an OC4J instance are started in all the OC4J processes associated to that OC4J instance."
In the description of the <metric-collector> element of the server.xml file in Appendix B - Additional Information of the Oracle Application Server Containers for J2EE User's Guide, the following incorrect cross reference is given:
"For details on using the <metric-collector> element and using metric-based load balancing with mod_oc4j, see the Oracle Application Server 10g Performance Guide."
Replace the incorrect cross reference with the following correct cross reference:
For details on using metric-based load balancing with mod_oc4j, see the Oracle HTTP Server Administrator's Guide.
Chapter 1: "OC4J Overview" of the Oracle Application Server Containers for J2EE User's Guide contains incorrect references to the Java Development Kit (JDK) used with Oracle Application Server Containers for J2EE 10g Release 2 (10.1.2).
The "Using JDK With OC4J" section lists JDK 1.3.1 and 1.4.1 as the supported versions. This list should also include JDK 1.4.2.
The "Requirements" section incorrectly states that JDK 1.3.x is installed with OC4J. The correct version is JDK 1.4.2.
Chapter 1: "OC4J Overview" of the Oracle Application Server Containers for J2EE User's Guide contains a reference to "primers", which are no longer included in the User's Guide.
The following notes on undeployment and redeployment are intended to supplement the deployment discussion in the Oracle Application Server Containers for J2EE User's Guide.
General undeployment/redeployment notes:
Once an application is undeployed from OC4J, it is no longer accessible to clients. In an Oracle Application Server environment, Oracle HTTP Server will be restarted to remove the OC4J mount point. This will result in the loss of existing HTTP sessions.
During a redeployment, OC4J removes the existing application (EAR/WAR) before redeploying the new EAR. This means, for example, that attempts to access an HTML file that was included in the previous application, but not the new one, will result in "File Not Found" errors.
Also note that a redeployed WAR file overlays the previously expanded WAR, meaning that some older files may persist in the new deployment and will need to be deleted. For example, static HTML files from the previous deployment that are not included in the new WAR may continue to reside in the expanded WAR directory structure, and would have to be manually deleted.
"Hot redeployment" notes:
When an EAR is redeployed or "hot redeployed" on a running OC4J instance, the status of the classes loaded in the JVM from the previous application may vary. In some cases a classloader may recognize that a class or JAR file in the file system has changed, and reload the class or library. In other cases whether a new class definition is loaded may depend on whether the JVM tuning allows the garbage collector to flush the existing class definition.
Issues may also exist with respect to serialized objects containing session data. If the class related to a session object changes, it may not be possible to cast the generic session object back to the class, since the class has changed and its variables may occupy a different memory footprint. This may result in lost session data.
In an Oracle Application Server environment, a "hot deployment" - deploying an application without restarting OC4J - adds Oc4jMount directives to mod_oc4j.conf, which in turn forces a restart of Oracle HTTP Server. This will result in the loss of existing HTTP sessions.
This section describes known errors in the Oracle XML API Reference. It includes the following topic(s):
In the Oracle XML API Reference, Chapter 15, "Package Dom APIs for C++", add the following entries:
On page 15-22, in Table 15-7 "Summary of DOMImplRef Methods; Dom Package", add an entry for formDocument() method, description: "Forms a document reference given a pointer to the document."
On page 15-24, add the following method description:
formDocument()
Description
Forms a document reference given a pointer to the document.
Syntax
DocumentRef< Node>* formDocument( Node* node);
----------------------------------------------------
Parameter Description
----------------------------------------------------
node Pointer to the document node.
----------------------------------------------------
Returns
DocumentRef< Node>* pointer to the document reference.
This section describes known errors in the OC4J Services Guide. It includes the following topic(s):
On page 4-24 in "Example DataDirect Data Source Entries", the Oracle Application Server Containers for J2EE Services Guide shows the following example as a data source entry for SQLServer. However, the example is incorrect, a colon is missing.
@ url="jdbc:sqlserver//hostname:port;User=test;Password=secret"
The correct example is as follows:
@ url="jdbc:sqlserver://hostname:port;User=test;Password=secret"
This section describes known errors in the OC4J Security Guide. It includes the following topic(s):
Section 5.5.6.1, "Allowed Values for establish.trust elements"
Section 5.5.6.2, "The external.synchronization Property Is No Longer Supported"
Section 5.5.6.3, "Define Roles in Lower Case for Third-Party LDAP Logins"
Chapter 15, "Configuring CSIv2", incorrectly describes the values of the <establish-trust-in-target> and <establish-trust-in-client> elements.
The <establish-trust-in-target> element can take only the values supported and none; it cannot take the value required.
The <establish-trust-in-client> element can take the values required, supported, and none.
The <jazn> property external.synchronization is no longer supported.
In Chapter 9, "Configuring External LDAP Providers", you should be aware of the following issue.
Applications that use third-party LDAP providers must define all deployment roles using lowercase only. Using uppercase letters in role names will cause authorization failures. When you define deployment roles in orion-application.xml, be sure to map all logical roles to lower-case names only.
The following snippet demonstrates valid and invalid deployment role names.
<security-role-mapping name="sr_developer"> <!- Logical role -->
<group name="developers" /> <!- Valid deployment role -->
</security-role-mapping>
<security-role-mapping name="jr_developer"> <!- Logical role -->
<group name="JuniorDevelopers" /> <!- Invalid deployment role;
causes authorization failure -->
</security-role-mapping>
In Chapter 4, "Overall Security Configuration", the section "Removing Realm Names From Principals" is incomplete. The jaas.user.simplename property, <propertyname="jaas.username.simple" value="true" />, may be set only in the instance-specific jazn.xml file,
$ORACLE_HOME/j2ee/$INSTANCE/config/jazn.xml.
This property affects only the specified OC4J instance. Setting this property in orion-application.xml has no effect.
