4 Oracle Application Server Containers for J2EE (OC4J)

4.1.1 Notes on Oracle JDBC-OCI driver upgrade in the Oracle Application Server

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

4.1.2 OC4J Out of Memory Errors

If the OC4J default JVM heap size is too small for applications that you deploy, then you might 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 might 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:

1. Stop the OC4J Instance.

2. Drill down to the Server Properties page.

3. 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 
    
   

4. Use the Apply button to apply the changes.

5. Start the OC4J instance.

For more information, see the Oracle Application Server 10g Performance Guide.

4.2.1 Servlet Bug Fixes Between 9.0.4 and 10.1.2

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.

4.3.1 Deprecated orion-ejb-jar.xml Attributes

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"

4.3.2 Big EAR File Deployment Runs Out of Memory

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

4.3.3 EJB Wrapper Code Compilation Fails When Running in zh_CN.GB18030 Locale.

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.

4.4.1 ORMI - OC4J Only Creates IPv4 Sockets

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.

4.4.2 ORMI Protocol Is Not Secure

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.

4.4.3 Enabling IIOP in OC4J

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 names above 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.

4.4.4 J2EE Connector Architecture (J2CA)

This section describes release notes for J2EE Connector Architecture (J2CA).

4.5.1 JSP Tag Libraries and Utilities Reference Errata

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):

• Section 4.5.1.1, "Personalization Tags Chapter Removed for 10.1.2 phase 1"

4.5.2 OC4J User's Guide Errata

This section describes known errors in the Oracle Application Server Containers for J2EE User's Guide. It includes the following topic(s):

• Section 4.5.2.1, "An OC4J Process Is Not "Contained" in an OC4J Instance"

• Section 4.5.2.2, "Correct Cross Reference for Metric-Based Load Balancing Information"

4.5.3 Oracle XML API Reference Errata

This section describes known errors in the Oracle XML API Reference. It includes the following topic(s):

• Section 4.5.3.1, "Add Information for formDocument() Method"

4.5.4 OC4J Services Guide Errata

This section describes known errors in the OC4J Services Guide. It includes the following topic(s):

• Section 4.5.4.1, "Correct SQLServer Data Source Example"

@ url="jdbc:sqlserver//hostname:port;User=test;Password=secret" 
 

@ url="jdbc:sqlserver://hostname:port;User=test;Password=secret"