6 Oracle Application Server Containers for J2EE

6.4.1.1 Data Sources Creates the Correct Number of Connection Pools in 10.1.2

In the 9.0.4 release, Data Sources incorrectly created multiple connection pools for the same data source: One pool for transactional connections and one pool for non-transactional connections.

This behavior is corrected for release 10.1.2.

6.4.1.2 Fatal Error Code Enhancement

For each data source defined in data-sources.xml, you can define fatal error codes that indicate that the back-end database with which the data source communicates is no longer accessible. When OC4J detects one of these error codes (stated when a SQLException is thrown by the JDBC driver), OC4J will clean its connection pool. That is, it closes all connections in the connection pool. For Oracle, the predefined fatal error codes are: 3113, 3114, 1033, 1034, 1089, and 1090.

Use the following procedure to add additional fatal error codes for Oracle.

Use the <fatal-error-codes> element, which is a subtag of the <data-source> element. The <fatal-error-codes> element uses the child element <error-code> to define one fatal error code. You can define 0 - n <error-code> elements for each <fatal-error-codes> element. For example, for fatal error codes 10, 20, and 30, the data source definition would look like this:

<data-source 
class="com.evermind.sql.DriverManagerDataSource" 
name="ds" 
location="jdbc/ds" 
xa-location="jdbc/xa/ds" 
ejb-location="jdbc/ejb/ds" 
@ connection-driver="oracle.jdbc.driver.OracleDriver" 
username="scott" 
@ password="tiger" 

@ url="jdbc:oracle:thin:@//localhost:1521/oracle.regress.rdbms.dev.us.oracle.com">
 
         <fatal-error-codes> 
            <error-code code='10'/> 
            <error-code code='20'/> 
            <error-code code='30'/> 
         </fatal-error-codes> 

</data-source> 

6.4.1.3 Fixed Connection Pool Problems

The following connection pool problems are fixed in 10.1.2.0.2.

In pre-10.1.2.0.2 versions of OC4J, the data sources subsystem would create multiple connection pools for the same data source for the following cases:

• When a connection was used inside a global transaction and outside a global transaction during the same thread of execution (during the execution of a servlet for example.) In this case one connection pool was created for connections used inside global transactions and one connection pool was created for connections used outside of the global transaction.

• When a connection was retrieved from the data source using the non-default user/password. For example, the use of getConnection() caused one connection pool to be created and getConnection("user", "password") caused another connection pool to be created. This is especially bad because each user/password combination created another, separate connection pool.

• Indicating via configuration that a data source's connections are to be shared caused an additional data source to be created under the covers which would then duplicate all of the connection pool issues described previously.

This resolves code bug 4226465 and documentation bug 4373802.

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

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

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

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

6.6.1.3 JDK 1.4.2 Supported and Installed with OC4J

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.

6.6.1.4 Primers Content Removed from OC4J User's Guide

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.

6.6.1.5 Additional OC4J Deployment Notes

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

6.6.2.1 Add Information for formDocument() Method

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.

6.6.3.1 Corrected 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"

6.6.3.2 Corrected JDBC Connect String for Third-Party Databases

In the "Example DataDirect Data Source Entries" section of the "Data Sources" chapter of the Oracle Application Server Containers for J2EE Services Guide for 9.0.4 and 10.1.2.x, the URLs in the examples are incorrect.

The INCORRECT part of the URL is as follows:

 url="jdbc:databasevendor://... 

The CORRECT URL fragment is as follows:

 url="jdbc:oracle:databasevendor://... 

The corrected example DataDirect Data Source Entries are as follows:

SQLServer

Here is a data source configuration sample for a SQLServer database.

<data-source 
                 class="com.evermind.sql.DriverManagerDataSource" 
                 name="OracleDS" 
                 location="jdbc/OracleCoreDS" 
                 xa-location="jdbc/xa/OracleXADS" 
                 ejb-location="jdbc/OracleDS" 
                 schema="database-schemas/ms-sql.xml" 
                 
 connection-driver="com.oracle.ias.jdbc.sqlserver.SQLServerDriver" 
                 username="mssql" 
                 password="mssql" 
                 
 url="jdbc:oracle:sqlserver://PZWU-PC\WUPZIAS;User=mssql;Password=mssql" 
                 inactivity-timeout="30" 
 /> 

DB2

Here is a data source configuration sample for a DB2 database:

  <data-source 
                   class="com.evermind.sql.DriverManagerDataSource" 
                   connection-driver="com.oracle.ias.jdbc.db2.DB2Driver" 
                   name="OracleDS" 
                   location="jdbc/OracleCoreDS" 
                   xa-location="jdbc/xa/OracleXADS" 
                   ejb-location="jdbc/OracleDS" 
                   schema="database-schemas/db2.xml" 
                   username="db2admin" 
                   password="db2admin" 
                   
 url="jdbc:oracle:db2://ying.us.oracle.com:50000;DatabaseName=sample;CreateDefa ultPackage=TRUE" 
                   inactivity-timeout="30" 
/> 

Sybase

Here is a data source configuration sample for a Sybase database:

  <data-source 
                 class="com.evermind.sql.DriverManagerDataSource" 
                 name="OracleDS" 
                 location="jdbc/OracleCoreDS" 
                 xa-location="jdbc/xa/OracleXADS" 
                 ejb-location="jdbc/OracleDS" 
                 schema="database-schemas/sybase.xml" 
                 connection-driver="com.oracle.ias.jdbc.sybase.SybaseDriver" 
                 username="JDBC_TEST" 
                 password="JDBC_TEST" 
                 url="jdbc:oracle:sybase://dlsun150:4101" 
                 inactivity-timeout="30" 
 /> 

Informix

Here is a data source configuration sample for an Informix database:

 <data-source 
                 class="com.evermind.sql.DriverManagerDataSource" 
                 name="OracleDS" 
                 location="jdbc/OracleCoreDS" 
                 xa-location="jdbc/xa/OracleXADS" 
                 ejb-location="jdbc/OracleDS" 
                 schema="database-schemas/informix.xml" 
                 
 connection-driver="com.oracle.ias.jdbc.informix.InformixDriver" 
                 username="tg4odbc" 
                 password="tg4odbc" 
                 
 url="jdbc:oracle:informix://dlsun150:3900;informixServer=gtw93;DatabaseName=ga tewaydb" 
                 inactivity-timeout="30" 
 /> 

6.6.3.3 Corrected Java Object Cache Code Example for Implementing a CacheEventListener

In the "*Implementing a Cache Event Listener" section of the "Java Object Cache" chapter of the Oracle Application Server Containers for J2EE Services Guide for 10.1.2.0.2, Example 9-14 has mismatched braces and misleading indentation.

The corrected example for Implementing a CacheEventListener is as follows:

import oracle.ias.cache.*; 
 
    // A CacheEventListener for a cache object 
    class MyEventListener implements CacheEventListener 
    { 
 
        public void handleEvent(CacheEvent ev) throws CacheException 
        { 
           MyObject obj = (MyObject)ev.getSource(); 
           obj.cleanup(); 
        } 
     } 
 
 class MyObject 
 { 
   public void cleanup() 
   { 
     // do something 
   } 
 } 
 
 import oracle.ias.cache.*; 
 
    // A CacheEventListener for a group object 
     class MyGroupEventListener implements CacheEventListener 
     { 
        public void handleEvent(CacheEvent ev) throws CacheException 
        { 
           String groupName = (String)ev.getSource(); 
           notify("group " + groupName + " has been invalidated"); 
 
        } 
        void notify(String str) 
        { 
          // do something 
        } 
     } 

6.6.4.1 Incorrect Example in Deployment Roles and Users

On page 3-8 of the Oracle Application Server Containers for J2EE Security Guide, under "Deployment Roles and Users", there is an example that does not properly close the <type> and <name> subelements of a <member> element. Here is the corrected example:

<role>
 <name>developer</name>
  <members>
   <member>
    <type>user</type>
    <name>john</name>
   </member>
  </members>
</role> 

6.6.4.2 Incorrect internal-settings.xml Information

The Oracle Application Server Containers for J2EE Security Guide incorrectly states that the internal-settings.xml file supports password indirection for keystore-password and truststore-password (page 14-2). This is incorrect; the internal-settings.xml file does not support password indirection.

6.6.5.1 Disregard Previous Release Note: Package Name for RMIInitialContextFactory Has Changed

Disregard the following release note from the initial 10.1.2 OC4J Release Notes. The information does not apply to the 10.1.2 release.

"The package name for RMIInitialContextFactory has changed from oracle.j2ee.rmi.server to oracle.j2ee.rmi. "