Skip Headers
Oracle® Application Server Release Notes
10g Release 2 (10.1.2) for hp-ux Itanium and Linux Itanium
B15871-05
  Go To Documentation Library
Home
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
 
Next
Next
 

5 Oracle Application Server Containers for J2EE (OC4J)

This chapter discusses release notes for the following topics:

You can access Oracle manuals mentioned in this document at the following URL:

http://www.oracle.com/technology/index.html

5.1 Configuration Issues and Workarounds

This section describes configuration issues and their workarounds for OC4J. It contains the following topics:

For information on configuring OC4J, refer to the Configuration Guide for OC4J at

http://www.oracle.com/technology/documentation/index.html

5.1.1 Oracle JDBC OCI Driver Problem on Linux Itanium and Windows Itanium

When accessing the Oracle Database, the Oracle Application Server uses either the type 2 JDBC-OCI driver or the type 4 JDBC-Thin driver. However, on Linux Itanium and Windows Itanium platforms, using Sun JVM (Hotspot), we have identified a bug reference 6227954 (http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6227954) which prevents the Oracle Application Server from using the JDBC-OCI driver. Oracle and Sun are actively and jointly working toward the resolution of this issue. Meanwhile, as a workaround, we recommends that Oracle Application Server customers use the Oracle JDBC-Thin driver, in Sun JVM environment, on Itanium-2 systems.

5.1.2 OC4J OutofMemory Errors

If the heap size of the default Java virtual machine (JVM) of OC4J is too small for applications that you deploy, then you might get OutofMemory errors from your OC4J processes. If you review the log files for the OC4J instance in the directory $ORACLE_HOME/opmn/logs, then 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, navigate to the OC4J instance homepage and perform the following steps:

  1. Stop the OC4J Instance.

  2. Navigate to the Server Properties page.

  3. In the Command Line Options area of the Server Properties page, the heading Multiple VM Configuration, set the options for Java.

    For example, enter the following to set the JVM heap sizes to 512 Megabytes:

    
    -Xmx512m 
    
     
    
    
  4. Click Apply.

  5. Start the OC4J instance.

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

5.2 Release Notes for EJB

This section describes release notes for Enterprise Java Beans (EJB). It covers the following topics:

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

5.2.2 Big EAR File Deployment Runs Out of Memory

OutOfMemory exceptions occur when deploying Enterprise Archive File (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 excessive for available memory.

A workaround for the problem is to direct the deployment process to compile each EJB module's wrapper code individually. You can do this by starting OC4J as follows:


 -Dejbdeploy.batch=false




Note:

The preceding workaround should only be used when this specific exception occurs. The workaround may result in an increased deployment time for the application.

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

The compilation of EJB wrapper code fails when running in zh_CN.GB18030 locale. When running in zh_CN.GB18030 locale, parts of the source code of EJB wrapper 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 the following URL:

http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4954023

The workaround is to use a different locale. Refer to the Sun bug 4954023 for details.

5.3 Release Notes for OC4J Services

This section describes release notes for OC4J services. OC4J Services include:

The section contains the following release notes:

5.3.1 ORMI - OC4J Only Creates IPv4 Sockets

OC4J only creates Internet Protocol version 4 (IPv4) sockets. Even on stack machines of dual network (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.

5.3.2 Security of ORMI Protocol

It should be noted that the ORMI protocol is not secure. All communication over ORMI is not encrypted including security credentials. Customers who want to encrypt ORMI traffic should use ORMI over HTTPS, which will encrypt all communication between the client and the server.

5.3.3 Enabling IIOP in OC4J

This section describes the steps necessary to enable Internet Inter-ORB Protocol (IIOP) applications in OC4J. After performing the steps you should be able to:

  • Access a remote EJB over IIOP

  • Secure EJB invocations with IIOP over SSL

  • Secure corba name lookups by remote clients with IIOP over SSL

To minimize deployment and configuration changes, the document uses the demo helloworld EJB application available through the installation and on OTN:

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 perform 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 steps are as follows:

  • Getting Started

  • Configuring IIOP in OC4J

  • Configuring the JNDI provider URL

  • Building and Deploying the Application

The following sections describe the steps in detail:

Getting Started

Expand the EJB demos in your development environment. The helloworld application should be available at the <install-dir>/demo/ejb/helloworld directory 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 remaining document, but changes required for enabling IIOP will not affect the applications. This document shows the installation of 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. It is assumed that you are familiar with Ant build files. If you are unfamiliar with Ant, then please refer to Apache's Ant documentation site:


http://ant.apache.org/manual/index.html

Configuring IIOP in OC4J

Edit the server.xml file as follows:


  <install-dir>j2ee/home/config/internal-settings.xml



Ensure that 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 subsequent to the following line:


<rmi-config path="./rmi.xml" />



This configures IIOPServerExtensionProvider for OC4J.

Now edit the internal-settings.xml file to configure your IIOP settings as follows:


  <install-dir>j2ee/home/config/internal-settings.xml



Ensure that 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 development environment. If your file contains entries for SSL, then temporarily comment them out as follows:


<!--

   <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 through the command line for OC4J standalone, and in the ${ORACLE_HOME}/opmn/opmn.xml file for Oracle Application Server installations.

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

Building and deploying 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



First start OC4J if you have not done so already, and 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.

Running the application

Edit the <install-dir>/demo/ejb/common.xml file, and ensure that the environment settings for ORACLE_HOME, JAVA_HOME, and J2EE_HOME match your environment.

Execute ant run.

You should refer to the appropriate Hello ... response from the client application. To verify that communication is running over IIOP, you can set the following JMV arguments on both the client and 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 refer to the same physical file. The file names mentioned are only for illustration. If you do not have a keystore file, then 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



In the provider URL, change the port to 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 requirements for applications security 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 importing the certificate in the servers keystore to a second truststore file.

Run the application with IIOP over SSL

Execute ant run.

You should refer to 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 server.

5.4 Release Notes for JSP

This section describes known issues for JSP. It includes the following topics:

5.4.1 JSP Compilation Problems on HP-UX Itanium

If you try to compile JSP code containing references to the sun.tools.javac.Main class the following message is displayed and the code does not compile on HP-UX Itanium:


oracle.jsp.provider.jspcomplieexception



Use either of the following methods to avoid this problem:

  • Do not include tools.jar in the CLASSPATH variable.

  • Set the use_old_compiler initialization parameter to false in the global-web-application.xml file

5.5 Release Notes for Documentation Errata

This section describes known errors in the OC4J documentation in Oracle Application Server 10g Release 2 (10.1.2). It contains the following topics:

5.5.1 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 topics:

5.5.1.1 An OC4J Process Is Not Contained in an OC4J Instance

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 because an OC4J process as such can only be contained in other processes and 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."

5.5.1.2 Correct Cross Reference for Metric-Based Load Balancing Information

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, refer to the Oracle HTTP Server Administrator's Guide.

5.5.2 Oracle XML API Reference Errata

This section describes known errors in Oracle XML API Reference. It includes the following topics:

5.5.2.1 Add Information for formDocument() Method

In the Oracle XML API Reference Guide, 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.

5.5.3 OC4J Services Guide Errata

This section describes known errors in OC4J Services Guide. It includes the following topics:

5.5.3.1 Correct SQLServer Data Source Example

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"



5.5.4 OC4J Security Guide Errata

This section describes known errors in the OC4J Security Guide. It includes the following topics:

5.5.4.1 Allowed Values for establish.trust Elements

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 accept only the supported values and none. It cannot take the value required. The <establish-trust-in-client> element can take the values required, supported, and none.

5.5.4.2 The external.synchronization Property Is No Longer Supported

The <jazn> property external.synchronization is no longer supported.

5.5.4.3 Define Roles in Lower Case for Third-Party LDAP Logins

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>

5.5.4.4 Removing Realm Names From Principals

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