Skip Headers
Oracle® Application Server Release Notes
10g Release 3 (10.1.3) for IBM zSeries Based Linux
B32204-05
  Go To Table Of Contents
Contents

Previous
Previous
 
Next
Next
 

5 Oracle Containers for J2EE

This chapter discusses release notes for Oracle Containers for J2EE (OC4J) for 10.1.3. 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

5.1 Configuration, Deployment, and Administration

This section describes configuration, deployment, and administration issues for Oracle Containers for J2EE (OC4J). This section covers the following topic(s):

For information on configuring OC4J, see the Configuration Guide for OC4J at:

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

5.1.1 Remove the Tomcat Examples

OC4J ships the Tomcat examples by default. Many of the Tomcat examples do not conform to the Oracle Secure Coding Standards. Oracle recommends that you remove the Tomcat examples except when used in demonstration and testing environments.

5.1.2 Deprecated Environment Variables dedicated.connection, dedicated.rmicontext, and LoadBalanceOnLookup

Environment variables dedicated.connection, dedicated.rmicontext, and LoadBalanceOnLookup are deprecated.

To configure replication-based load balancing, use environment variable oracle.j2ee.rmi.loadBalance with the settings that Table 5-1 lists.

Table 5-1 Settings for Environment Variable oracle.j2ee.rmi.loadBalance

Setting Description

client

The client interacts with the OC4J process that was initially chosen at the first lookup for the entire conversation (Default)

context

The client goes to a new server when a separate context is used (similar to deprecated dedicated.rmicontext).

lookup

The client goes to a new server for every lookup.


5.1.3 Deprecated Environment Variable ejb.batch.compile

Environment variable ejb.batch.compile is deprecated.

To enable or disable batch compilation, use the orion-application.xml file <orion-application> element batch-compile attribute.

5.1.4 Deprecated orion-ejb-jar.xml Attributes

The following orion-ejb-jar.xml file attributes are deprecated:

  • max-instances-per-pk

  • min-instances-per-pk

  • disable-wrapper-cache

  • instance-cache-timeout

  • locking-mode="old_pessimistic"


Note:

Do not use these attributes in this release. Doing so will lead to deployment failure.

5.1.5 Web-Site-Related Options No Longer Available

The OC4J web-site-related options (accessible with the -site command) that were provided in the admin.jar utility in previous releases are no longer available.

For information on how to create and manage OC4J web site configurations see the "Managing Web Sites in OC4J" chapter in the Oracle Containers for J2EE Configuration and Administration Guide.

5.1.6 Unsupported Methods in JMX MBeanServer and MBeanServerConnection Interfaces

A number of methods from the JMX MBeanServer interface are not available to J2EE applications when they use the MBeanServer object obtained from the following operation:

MBeanServer mbsrv = MBeanServerFactory.newMBeanServer();

The use of any of the following methods on the returned MBeanServer object will throw an UnsupportedOperationException exception:

public final ClassLoader getClassLoaderFor(ObjectName mbeanName)

public final ClassLoader getClassLoader(ObjectName loaderName)

public final ClassLoaderRepository getClassLoaderRepository()

public final Object instantiate(String className)

public final Object instantiate(String className, ObjectName loaderName)

public final Object instantiate(String className, Object[] params, String[] signature)

public final Object instantiate(String className, ObjectName loaderName, Object[] params, String[] signature)

public final ObjectInstance createMBean(String className, ObjectName name)

public final ObjectInstance createMBean(String className, ObjectName name, ObjectName loaderName)

public final ObjectInstance createMBean(String className, ObjectName name, Object[] params, String[] signature)

public final ObjectInstance createMBean(String className, ObjectName name, ObjectName loader, Object[] params, String[] signature)

public final ObjectInputStream deserialize(ObjectName name, byte[] data)

public final ObjectInputStream deserialize(String className, byte[] data)

public final ObjectInputStream deserialize(String className, ObjectName loaderName, byte[] data)

A number of methods from the MBeanServerConnection interface are not supported when an application uses the Oracle JMX connectors. The use of any of the following methods on the MBeanServerConnection object that is created will throw an UnsupportedOperationException exception:

public final ObjectInstance createMBean(String className, ObjectName name)

public final ObjectInstance createMBean(String className, ObjectName name, ObjectName loaderName)

public final ObjectInstance createMBean(String className, ObjectName name, Object[] params, String[] signature)

public final ObjectInstance createMBean(String className, ObjectName name, ObjectName loader, Object[] params, String[] signature)

5.1.7 Upgrade to Latest J2SE Release

Currently Oracle Application Server 10.1.3.0.0 is certified with JDK 1.4.2_09 and JDK 1.5.0_05 and JDK 1.5.0_06. The product installs with JDK 1.5.0_05 by default.

In general, J2SE releases are number a.b.c_d, where "a.b.c" is the major release number, as in 1.4.2 or 1.5.0, and "d" is the minor release number, as in "05" or "06". As a general practice, Oracle recommends that customers upgrade to the latest minor release number of J2SE to ensure that they benefit from any bugs resolved in those specific J2SE upgrades. Oracle explicitly restates the certification matrix for major release numbers of J2SE.

Currently there is a known J2SE bug in J2SE 1.5.0_05 and J2SE 1.5.0_06 that manifests itself in an out-of-memory error in long-running stress tests involving BigDecimals numeric types. This bug is tracked by Sun at:


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

The workaround for this bug is to upgrade to J2SE 1.5.0_06 and set the JVM startup parameters for the impacted Oracle Containers for J2EE instance with this additional parameter:

-XX:CompileCommand=exclude,oracle/jdbc/driver/NumberCommonaccessor.getBigdecim

Information on configuring the J2SE runtime in Oracle Application Server can be found in the Oracle Containers for J2EE Configuration and Administration Guide at:


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

5.1.8 Workaround for ORA-604/ORA-12705 Error Using a Not-Fully Supported Locale

When you try to get a connection on a Locale that is not supported in JDBC, JDBC throws a SQLException. - Bug 4704421

Use the following to verify runtime Java's locale:

System.out.println(Locale.getDefault().toString()) 

Unsupported Locales include any Locale that is NOT listed in the "Fully Supported Locales" table in on the Java 5.0 Java Supported Locales page at the following URL: http://java.sun.com/j2se/1.5.0/docs/guide/intl/locale.doc.html

For example, Locales that are "Provided but not Tested" include the following:

  • ab_CD

  • fr_FR_EURO

  • it_IT_EURO

  • th_TH_TH, Thai (Thailand,TH)

  • be, Belarusian

  • be_BY, Belarusian (Belarus)

  • es_AR, Spanish (Argentina)

  • es_BO, Spanish (Bolivia)

  • es_DO, Spanish (Dominican Republic)

  • es_EC, Spanish (Ecuador)

  • es_HN, Spanish (Honduras)

  • es_PY, Spanish (Paraguay)

  • es_UY, Spanish (Uruguay)

  • mk, Macedonian

  • mk_MK, Macedonian (Macedonia)

  • no_NO_NY, Norwegian (Norway,Nynorsk)

  • sq, Albanian

  • sq_AL, Albanian (Albania)

The workaround for this problem is to update your default Locale setting of Java. You can do any of the following:

  • Change default Locale from the unsupported es_AR, to the fully supported es (Spanish):

     Locale.setDefault(new Locale("es")); 
    
  • When Locale has variant code such as fr_FR_EURO, remove variant code (EURO) and set default:

    Locale.setDefault(new Locale("fr", "FR")); 
    
  • Set English as the default Locale:

    Locale.setDefault(Locale.ENGLISH); 
    

5.1.9 Incompatibility When Moving Between JDK 1.5 and 1.4

When you deploy an application (including the OC4J default application) to OC4J running JDK 1.5 (Java 5), you cannot re-use that deployment on OC4J running JDK 1.4.

Code compiled with JDK 1.5 (Java 5) cannot be read by the JDK 1.4 VM. When OC4J is running under JDK 1.4 and tries to load a class which was compiled with JDK 1.5, a class loading exception will be thrown with the following message:

Unsupported major.minor version 49.0

This can occur in scenarios such as:

  • You deploy an application that contains EJBs to OC4J running under JDK 1.5, then, without undeploying the application, you restart OC4J under JDK 1.4. The problem is that the generated code associated with the EJBs will have been compiled with the same JDK version that was used to start the server and that the generated code is cached between server restarts on the file system in the <OC4J_HOME>/j2ee/home/application-deployments directory.

    The workaround for this is to shutdown the server, remove either the contents of the <OC4J_HOME>/j2ee/home/application-deployments directory (or just the offending application's sub-directory) and restart the server with JDK 1.4.

  • You deploy an EAR file which contains classes that were compiled with and targeted to JDK 1.5 to OC4J running under JDK 1.4.

    The workaround for this is to recompile the contents of the EAR using JDK 1.4 and redeploy.


Note:

To simplify this discussion, we assume that no cross compilations are being used to target code to specific JDK versions.

5.1.10 Configuring a Machine to Work With and Without a Network Connection

When you work on a single machine using localhost, add the IP address in the <ipaddr> subelement of the <notification-server> element and explicitly set up a discover list in the <discover> element to refer to the localhost OPMN remote port, as defined in the cluster <port> element. An example of this configuration follows:

   <notification-server>
      <ipaddr remote="127.0.0.1" request="127.0.0.1"/>
      <port local="6101" remote="6201" request="6004"/>
      <ssl enabled="true" wallet-file="$ORACLE_HOME\opmn\conf\ssl.wlt\default"/>
      <topology>
         <discover list="localhost:6201"/>
      </topology>
   </notification-server>

If you supply the localhost IP address, 127.0.0.1, the machine can work with or without a network.

5.1.11 Converting Pre-10.1.3 Data Sources to 10.1.3 Format

For information on converting pre-10.1.3 data sources to 10.1.3 format, see the release note at Section 5.6.3.3, "Converting Existing Data Sources to Release 3 Format".

5.1.12 Xalan Library Not Supported as a Shared Library with JDK1.4

If you are using JDK1.4, Oracle Application Server 10.1.3 does not support using the Xalan library shipped with the JDK as a shared library. To use the Xalan library, you have two alternatives:

  • Use JDK1.5, in which the embedded Xalan library IS supported as a shared library.

  • With JDK1.4, use a standalone distribution of the Xalan library instead of the embedded version.

5.1.13 Recommendation for <cluster> Element write-quota Setting

Chapter 9 of the 10.1.3 Oracle Containers for J2EE Configuration and Administration Guide documents the <cluster> element of the orion-application.xml file, including use of the write-quota attribute. This attribute determines the number of other "group members" within a cluster to which application state information should be replicated.

Be aware, however, that a "group member" is actually a JVM, not a node, and that it is possible to have multiple JVMs per node.

To ensure that more than one node receives state replication, set write-quota to a number greater than the highest number of JVMs on any one node within the cluster. For example, if there are three nodes, which have six JVMs, four JVMs, and three JVMS, respectively, set write-quota to a value of at least 7.

5.1.14 OC4J Memory Error

When compiling large jsp page, the following memory error is displayed along with JspCompileException:

[ **Out of memory, aborting** ]
[ ]
[ *** panic: JVMST018: Cannot allocate memory for
initializeMarkAndAllocBits(allocbits1)*** ]

To workaround this issue, lower the maximum heap size by adding -Dbuild.compiler.options=-J-Xmx750M option to the OC4J home java-options in the opmn.xml file.

For example,

<process-type id="home" module-id="OC4J">
value="-Dbuild.compiler.options=-J-Xmx750M
-Djava.security.policy=$ORACLE_HOME/j2ee/home/config/java2.policy
-Djava.awt.headless=true -Xmx256m "/>

5.1.15 The oracle.home and oracle. j2ee.home System Properties

The following information has been added to the 10.1.3.1 Oracle Containers for J2EE Configuration and Administration Guide.

Instead of the environment variables ORACLE_HOME and J2EE_HOME, you can use the system properties oracle.home and oracle.j2ee.home to set the Oracle and J2EE home directories. The following table describes these system properties that you can set for OC4J.

Property Description
oracle.home Sets the root directory into which you will install the OC4J distribution.

Instead of using the oracle.home system property, you can set the value of the ORACLE_HOME environment variable to the root directory.

oracle.j2ee.home Sets the J2EE home directory to the installed directory of the oc4j.jar and admin.jar files, oc4j_install_dir/j2ee/home.

Setting this system property or the J2EE_HOME environment variable to the J2EE home directory enables you to invoke oc4j.jar and admin.jar from any directory.


5.1.16 Maximum Threads in Work Manager Thread Pool

The max attribute of the <work-manager-thread-pool> element or WorkManagerThreadPool MBean specifies the maximum number of threads that OC4J can create in the pool. The default value of max is 40.

The work manager thread pool uses three worker threads for internal use. For example, if you specify max="16", then only 13 worker threads are available to service requests. Similarly, if the max value is 20, then only 17 threads are available. So you need to set this value to your required maximum number of threads plus 3.

5.1.17 Configuring Multicast Discovery with opmnassociate

The opmnassociate utility adds the default home OC4J instance to a cluster using multicast discovery. This utility performs the following steps:

  1. Inserts or updates the <discover> element in opmn.xml with the specified multicast address and port

  2. Configures the default Web site to receive and respond to requests from Oracle HTTP Server using the Apache JServ Protocol (AJP) by modifying the corresponding <port> element in opmn.xml

  3. Restarts OPMN to load the new configuration into the runtime

The opmnassociate tool is installed in the ORACLE_HOME/bin directory on each OC4J instance. The tool must be run individually on each instance and will update only the opmn.xml file on that instance.

On UNIX and Linux systems, the syntax is as follows:

opmnassociate.sh "*multicastAddress:multicastPort" [-restart]

For example:

opmnassociate.sh "*225.0.0.20:8001" -restart

On Windows systems, the syntax is as follows:

opmnassociate "*multicastAddress:multicastPort" [-restart]

For example:

opmnassociate "*225.0.0.20:8001" -restart

The asterisk (*) preceding the IP address is required.

5.1.18 Downgraded JDK and <java-compiler> in server.xml

An OPMN-managed OC4J instance installed as a component of Oracle Application Server uses JDK 5.0 by default. If an application that will be deployed to OC4J requires a JDK 1.4.2 release, you can downgrade to the earlier version.

  1. Stop the OC4J instance.

  2. Delete the ORACLE_HOME/j2ee/instance/application-deployments directory.

    Deleting this directory will cause the application files to be recompiled when OC4J is restarted with the JDK 1.4.2.

Before switching from JDK 5.0 to JDK 1.4.2, you must remove all compiled application files from the OC4J instance:

You can specify the JDK to use for each OC4J instance through manual edits to the opmn.xml configuration file. If you want to use the javac compiler installed with the JDK defined in the JAVA_HOME environment variable, also remove the <java-compiler> element from server.xml and let OC4J rediscover the default settings.

5.1.19 Configuration of Application Mount Points

In previous releases of Oracle Application Server the list of application mount points had to be managed manually in the mod_oc4j configuration file, mod_oc4j.conf.

In the current release, the mount point list is dynamically updated as new nodes and applications are added to—or removed from—the cluster. This dynamic discovery mechanism is enabled by default and requires no additional configuration.

You can still configure application mount points manually and view the mount point list, as the Oracle Containers for J2EE Configuration and Administration Guide describes. For additional information about configuring mount points, see Oracle HTTP Server Administrator's Guide.

5.1.20 Hot Deployment in OC4J

The term hot deployment refers to the process of deploying archive files - EARs, WARs, JARs, and so on - and their associated XML descriptor files on a production application server without shutting down or restarting (bouncing) the server.

In addition, libraries at the container level cannot be deployed in this manner. If an application is dependent upon a newer library, OC4J must be restarted.

For details on redeploying applications to an OC4J instance, see the Oracle Containers for J2EE Deployment Guide.

5.1.20.1 Deployment of Applications

Hot deployment or redeployment of an application or standalone module into OC4J is generally supported as long as no changes are made during the deployment process to existing data source, JMS, or RMI configuration files, and the structure of an Enterprise JavaBean replacing an existing EJB has not changed.

5.1.20.2 Deployment of Shared Libraries

Shared libraries are loaded and managed at a container level. A change to a shared library does require a container restart.

If a redeployed application has an import-shared-library declaration that goes from a lower to a higher version, such as from 2.2.8 to 2.2.9, then the version change in the declaration should not require a container restart. The application will be restarted on redeployment and should pick up the new shared library version (as long as the library is available).

5.1.21 Allowed Format for Version Numbers in MANIFEST.MF File

Previously, version numbers in the Specification-Version and Implementation-Version attributes of a MANIFEST.MF file were limited to five elements: n1.n2.n3.n4.n5. (OC4J would not start if there were more than five elements in a Specification-Version or Implementation-Version value.)

Now, version numbers of up to eight elements are allowed: n1.n2.n3.n4.n5.n6.n7.n8.

The maximum allowed value for an element is 99999999.

5.1.22 Migration Tool Issue: Prepending Oracle Internet Directory Realm Name to Custom Principals

Be aware of the following issue when you use the OracleAS JAAS Provider migration tool to migrate policies from the file-based provider to the Oracle Identity Management (essentially, Oracle Internet Directory) security provider, either in "policy" mode or "all" mode: The migration tool prepends the Oracle Internet Directory realm name to custom or nonrealm principal names in grantee entries in the policy configuration. (A custom principal may come into play when authenticating through a custom login module, for example.)

In the migrated configuration, a custom principal name in a grantee entry becomes, for example, "us/anyone" instead of just "anyone", assuming "us" is the realm name. This results in permission issues. For ADF applications, for example, this results in public pages not working after migration to Oracle Internet Directory as the security provider.

This problem will be fixed in the 10.1.3.3 release. For 10.1.3.2 and prior 10.1.3.x releases, you can use either of the following workarounds:

  • Manually remove the "us/" prefix from the LDIF file that the migration tool creates, prior to importing it into Oracle Internet Directory.

  • Manually remove the "us/" prefix from relevant grantee entries after the migration, using Oracle Internet Directory administration tools.

5.1.23 Job Scheduler Redeployment

If you redeploy an application with scheduled jobs, the scheduled jobs will not run after the application is redeployed.

When redeploying an application with scheduled jobs, you should:

  1. Remove all scheduled jobs.

  2. Redeploy the application.

  3. Resubmit all the jobs.

5.1.24 Incompatible ONS Versions

The Oracle Notification Service (ONS) that is included with the Oracle Application Server 10.1.3.x releases is incompatible with the ONS version included with the Database 10.1.0.x releases. The following error is received when the two versions attempt a connection:

invalid connect server IP format
...
Terminating connection
...

The incompatibility causes RAC features, such as Fast Connection Failover, to fail. The workaround is to install the 10.1.0.6 patch set for the Oracle Database Server. The patch set includes an updated ONS. The patch can be downloaded from https://metalink.oracle.com.

5.1.25 Use of '/' for Context Root

Specification of "/" for the context root when deploying an application to OC4J is supported now. This includes support by Application Server Control and admin_client.jar.

Background: The 10.1.3.1 release of the Oracle Containers for J2EE Configuration and Administration Guide states that "Specifying a root setting of "/" will override the OC4J default Web application. This setting or a null setting is not allowed by the admin_client.jar utility when binding a Web application to the Web site."

Now, however, a root setting of "/" is allowed. You can use this as the context root when deploying an application. The following example uses admin_client.jar to deploy a WAR file and bind to "/".

% java -jar admin_client.jar deployer:oc4j:localhost oc4jadmin welcome1 \
  -deploy -file d:how-to-rolling-upgrade-web-v1.war -deploymentName h2ru_2 \
  -bindAllWebApps -contextRoot "/"

Be aware that if an EAR file includes an application.xml file that has the context root set to "/", such as in the following example, then "/" will be the default context root when the application is deployed using either Application Server Control or admin_client.jar.

<application>
  <display-name>How-To Rolling Upgrade</display-name>
  <module>
    <web>
      <web-uri>how-to-rolling-upgrade-web.war</web-uri>
      <context-root>/</context-root>
    </web>
  </module>
</application>

Note:

Because the default ping URL for Oracle HTTP Server is also "/", using "/" as the context root when you deploy an application may result in the following issues:
  • Pings intended for Oracle HTTP Server go directly to OC4J instead.

  • Extraneous HEAD requests appear in the *-web-access.log file.

You can avoid these issues by placing the following directive:

Oc4jMountCopy off

Into the following file:

ORACLE_HOME/Apache/Apache/conf/dms.conf

5.1.26 Warning Regarding Maximum Concurrent Timers

This release note provides background information and workarounds for warnings, such as the following examples, that occur when the number of concurrent timers exceeds the maximum.

WARNING J2EE OJR-10002

The number of concurrent Timers has reached the maximum limit

By default in 10.1.3.1 and 10.1.3.2, OC4J allows only eight concurrent timers. (A timer can be triggered through an EJB timer, the timer service, or the scheduler.) This limit is low by default because we expect each timer to be of short duration. When the number of timers is at the limit, such as if timers are running longer for any reason, timers are no longer executed; when a new timer occurs, you will see the warning messages. There are two OC4J flags you can use in this circumstance:

  • timer.service.debug: Determines whether to output additional diagnostic information for the timer service, including information about the current number of running timers. For example: -Dtimer.service.debug=true

  • executor.concurrent.tasks: Specifies the number of concurrent tasks for the Executor Service. Through this flag you can increase the maximum number of concurrent timers allowed by OC4J. For example: -Dexecutor.concurrent.tasks=12


Note:

Each timer executes in a separate thread. If the maximum is set too high, resulting in numerous timers executing, then many threads will be used. It is advisable to recycle threads once they finish executing.

5.1.27 Incorrect orion-ejb-jar.xml Created When cmp-field-mapping Specified

In previous releases of OC4J, when you use ascontrol to deploy an EJB CMP 2.1 application with an orion-ejb-jar.xml file that contains cmp-field-mapping elements, OC4J sometimes failed to preserve persistence-name, omitted persistence-type, or both.

In this release, OC4J correctly handles all cmp-field-mapping configuration.

5.1.28 Specifying the Mapping Attribute

For X.509 Certificate Authentication (X509Certificate), JAZN sets the mapping attribute for the Oracle Internet Directory (OID) provider to "DN" by default.

To change the default value, you can configure the value of the mapping.attribute property:

  1. Locate the $Oracle_Home/j2ee/<oc4j_inst>/config/jazn.xml file.

  2. Add the mapping.attribute property configuration to the <jazn> tag. For example:

    <jazn provider... > 
    ... 
       <property name = "mapping.attribute" value="cn"/> 
    ... 
    </jazn> 
    
  3. Restart the OC4J instance.

Likewise, other login modules now rely on the mapping.attribute property in the jazn.xml file, including:

  • WS-Security Username token with no password (WSSLoginModule)

  • SAML (SAMLLoginModule)

    SAMLLoginModule first looks at the SubjectNameIdentifier to determine the mapping. If blank, then the mapping.attribute is used.

  • X.509 client certificate authentication (X509LoginModule)

  • Third party login module (LDAPLoginModule)

The mapping attribute for these login modules must be set in the jazn.xml file as described here.

5.1.29 Use of the http.file.allowAlias Property

By default, OC4J now ships with the http.file.allowAlias property set to false. This setting prevents the use of symbolic links. Oracle strongly recommends that this setting not be changed to true, which might allow JSP source code to be visible to end users in some circumstances.

Instead of changing the property setting, you can use one of the following workarounds:

  • Temporarily switch from using the OC4J lightweight HTTP listener to front ending the OC4J application through Oracle HTTP Server, so that browsers access the pages indirectly through MOD_OC4J and Apache JServ Protocol (AJP), rather than directly through HTTP.

  • Replace all symbolic links in an application with the names of the real files they represent.

    You can use a shell script to automate the replacement of symbolic links. For example:

    #!/bin/ksh
    
    PROGNAME="${0##*/}"
    LN_EXTN="ln"
    
    function displaySyntax
    {
    echo "${PROGNAME}! SYNTAX: ${PROGNAME} <some_dir_path>"
    exit 1
    }
    
    if [[ $# < 0 ]]
    then
    displaySyntax
    fi
    
    DIR="$1"
    
    if [[ ! -d ${DIR} 
    then
    displaySyntax
    fi
    
    find ${DIR} -type l|while read filepath
    do
    echo "FIXING: ${filepath} (=> ${filepath}.${LN_EXTN})"
    mv ${filepath} ${filepath}.${LN_EXTN}
    cp -L ${filepath}.${LN_EXTN} ${filepath}
    done
    

This example KSH script would be invoked on Unix as follows:

$ fixLinks <web_module_root>

The script will recurse through any directory and, for any file it finds that is a symbolic link, will rename each link with an additional .ln extension and then place a copy of the link target in the original location where the link was found.

5.1.30 oracle.http.client Shared Library Missing from system-application.xml

The oracle.http.client shared library is missing from the system application. This library, which should be part of the set of shared libraries that applications import from system by default, is not specified in the 10.1.3.0.0 system-application.xml configuration file.

Before you deploy any portlets to an OC4J instance, you need to add the oracle.http.client shared library to the ORACLE_HOME/j2ee/instance/config/system-application.xml file. You can do this by adding the following line to the <imported-shared-libraries> section of the file:

<import-shared-library name="oracle.http.client" />

5.2 Servlets and JSPs

This section describes release notes for servlets. It covers the following topic(s):

5.2.1 Servlet Invocation by Classname Disabled by Default

In the 10.1.3 implementation, servlet invocation by class name is not enabled by default. Therefore, in default mode, you must use standard servlet configuration in web.xml before a servlet can be invoked. For example:

  <servlet> 
     <servlet-name>mytest</servlet-name> 
     <servlet-class>mypackage.MyTestClass</servlet-class> 
  </servlet> 
  ... 
  <servlet-mapping> 
     <servlet-name>mytest</servlet-name> 
     <url-pattern>/servlet/mytest</url-pattern> 
  </servlet-mapping> 

Without this configuration, attempts to invoke the servlet will result in a 404 NOT FOUND error. This differs from the default behavior in previous releases, where invocation by class name was enabled.

Alternatively, customers can choose to enable invocation by class name when they start OC4J, by setting the http.webdir.enable property as follows:

-Dhttp.webdir.enable=true 

5.2.2 Physical File Required for Welcome File

A physical file must be present for a welcome file to dispatch to a servlet. To create a servlet mapped to /index.html that maps to the JSP /index.jsp and have it serve as a welcome file, the web.xml file should include the following entries:

<servlet> 
   <servlet-name> index_jsp </servlet-name> 
   <jsp-file> /index.jsp </jsp-file> 
</servlet> 

<servlet-mapping> 
   <servlet-name>index_jsp</servlet-name> 
   <url-pattern>/index.html</url-pattern> 
</servlet-mapping> 

This works only if there is a physical file, /index.html, in the Web application. The file can be zero length. As long as the file exists, this servlet will be loaded as the welcome file. Otherwise, a java.lang.StringIndexOutOfBoundsException exception will be thrown.

5.2.3 Warning Issued for servlet.init() Not Working with run-as

For a Web application, when run-as user is specified in the web.xml file, all method invocations except the Servlet.init() method will be invoked as the specified user. With the JMS Router being the default application of OC4J, calls need to be authorized to the router's EJBs. This is done by defining the application role "jmsRouter", which is mapped to the JAAS "oc4j-administrators" role, and specifying <method-permission> for all methods of the router's EJBs.

The init() method of the servlet within the router's Web model creates a router EJB object. Regardless of whether run-as is specified in web.xml for the servlet, a security exception is thrown:

@ oracle.oc4j.rmi.OracleRemoteException: anonymous is not allowed to call this EJB method, check your security settings (method-permission in ejb-jar.xml and security-role-mapping in orion-application.xml).

Workaround

The security warning can be removed by commenting out '*' in the <method-name> element of <method-permission> in ejb-jar.xml and explicitly enumerating all methods in AdminMgrBean that the jmsRouter role can access, as follows.

<!-- 
    <method-permission> 
      <role-name>jmsRouter</role-name> 
      <method> 
         <ejb-name>AdminMgrBean</ejb-name> 
         <method-name>*</method-name> 
      </method> 
    </method-permission> 
--> 
    <method-permission> 
      <role-name>jmsRouter</role-name> 
      <method> 
         <ejb-name>AdminMgrBean</ejb-name> 
         <method-name>getConfig</method-name> 
      </method> 
    </method-permission> 
    ... 

runAsRoleName is correctly parsed in ServletDescriptor.java, stored in info and thread in HttpApplication.loadServlet().

5.2.4 Request Parameters Not Available During Filter Execution

HTTP request parameters will not be available to servlet filters that are meant to be executed before dispatch of the request to a static resource (an .html file, for example). Note that filters that execute before dynamic resources, such as a servlet or JSP, will have access to the parameters.

5.2.5 The default-charset Setting Does Not Apply to Servlets

In 10.1.3, the default-charset attribute of the <orion-web-app> element in the orion-web.xml file applies to JSP pages only, not to servlets.

5.2.6 Form Authentication Filter

An OC4J proprietary filter dispatcher was introduced in 10.1.3 that enables a filter to access the username/password credentials passed in to OC4J through Form Authentication. For example, you would do this if you want to perform further authentication on external resources.

To enable this feature, specify the FORMAUTH value in the <dispatcher> element for the filter in the orion-web.xml file.

The following examples show the code that declares the filter and the code that specifies the FORMAUTH feature:


Note:

The <filter> element can be declared in either the orion-web.xml file or the web.xml file.

The <filter-mapping> element must be declared in the orion-web.xml file.


In orion-web.xml or web.xml:

<filter> 
   <filter-name>MyFilter</filter-name> 
   <filter-class>myFilterClass</filter-class> 
</filter> 

In orion-web.xml:

<orion-web-app>
...
   <web-app> 
   ...
      <filter-mapping> 
         <filter-name>MyFilter</filter-name> 
         <dispatcher>FORMAUTH</dispatcher> 
      </filter-mapping> 
   </web-app> 
</orion-web-app>

Any filter declared this way will be executed after the authentication form is submitted, but before authentication is performed in OC4J.

The filter can call request.getParameters() to get the j_username and j_password parameters from the request object.

Here is an example of the calling code:

import javax.servlet.*;
import javax.servlet.http.*;

public class MyFilter implements Filter {

    public MyFilter() {
        super();
    }

    public void doFilter(ServletRequest request, 
                         ServletResponse response,
                         FilterChain filterChain)
        throws IOException, ServletExxception {
        HttpServletRequest req = (HttpServletRequest) request;

String username = req.getParameter("j_username");
String password = req.getParameter("j_password");
// use these credentials to access a remote DB        
....
filterChain.doFilter(request, response);
    }

    public void init(FilterConfig filterConfig) throws ServletException {
    }

    public void destroy() {
    }
}

5.2.7 ojsp Tag Libraries Deprecated

Oracle-proprietary ojsp tag libraries are deprecated in OC4J 10.1.3.x releases. They will be desupported in OC4J release 11g.

5.2.8 Disabling Servlet Reloading

In the global-web-application.xml file, you can force OC4J to not reload a specific servlet if the servlet is modified. This feature is enabled by setting the undocumented auto-reload attribute of the <servlet> element to false.

auto-reload="false">.

This parameter is not documented in the OC4J 10.1.3.x Servlet documentation.

The following example shows that this can be done for a single servlet.

In global-web-application.xml:

 ...  
   <servlet auto-reload="false"> 
      <servlet-name>nlservlet</servlet-name> 
        <servlet-class>com.netledger.core.requesthandler.NLServlet 
        </servlet-class> 
   </servlet> 

5.2.9 Specifying justrun for Production Environment Efficiency

For efficiency in the production environment, the sample-web.war that is to be precompiled using ojspc should include the following declaration in its sample-web.war\WEB-INF\web.xml just after the <web-app> element:

  <servlet> 
    <servlet-name>jsp</servlet-name> 
    <servlet-class>oracle.jsp.runtimev2.JspServlet</servlet-class> 
    <init-param> 
       <param-name>main_mode</param-name> 
       <param-value>justrun</param-value> 
    </init-param> 
  </servlet> 

The settings of the main_mode parameter, including justrun, are described in Chapter 3, Configuring the OC4J JSP Environment, of the Oracle Containers for J2EE Support for JavaServer Pages Developer's Guide.

5.2.10 Using a Tag Library with the ojspc Utility

To use your own tag library with ojspc, the best method is to put your tag library under WEB-INF/lib in a WAR that contains a JSP page and then precompile the archive, which can be either a standalone WAR or an EAR that contains the WAR.

For example, mytaglib.war contains these files:


jsp/mytaglib_example.jsp
WEB-INF/web.xml
WEB-INF/orion-web.xml
WEB-INF/lib/mytaglib.jar

The mytaglib.jar file contains META-INF/mytaglib.tld as well as the class files for all tags declared in that tag library descriptor (mytaglib.tld).

In this example, the WAR (mytaglib.war) is inside an EAR file along with META-INF/application.xml.

The following ojspc command precompiles the EAR file:

ojspc -output out/mytaglib.ear mytaglib.ear 

After the precompilation, the EAR file will be in out/mytaglib.ear and will contain a WAR file with the precompiled JSP page under WEB-INF/lib, __oracle_jsp_mytaglib_web.jar mytaglib.jar, as well as the original mytaglib.jar file.

You could deploy this EAR file to OC4, and if you set the <ojsp-init> attribute main-mode to the value justrun in the orion-web.xml deployment descriptor, the precompiled version in WEB-INF/lib will be used. Alternatively, you could set the main_mode parameter to justrun in an <init-param> element of the jsp servlet configuration for the OC4J instance in $J2EE_HOME/config/global-web-applications.xml.

5.3 EJB

This section describes release notes for EJB. It covers the following topics:

5.3.1 EJB 3.0 Support

In this release, OC4J supports a subset of the functionality specified in the EJB 3.0 proposed final draft at: http://jcp.org/aboutJava/communityprocess/pr/jsr220/index.html

For example, support for some EJB 3.0 features such as persistence API, external lifecycle listener class, and interceptors may not be compliant with the latest EJB 3.0 specification.

You may need to make code changes to your EJB 3.0 OC4J application after the EJB 3.0 specification is finalized and OC4J is updated to full EJB 3.0 compliance.

5.3.2 Orion CMP is Deprecated

The Orion persistence manager is deprecated. Oracle recommends that you use OC4J and the TopLink persistence manager for new development. Using the migration tool, you can easily migrate an existing OC4J application that uses EJB 2.0 entity beans with the Orion persistence manager to use EJB 2.0 entity beans with the TopLink persistence manager.

For more information, see "Migrating OC4J Orion Persistence to OC4J TopLink Persistence" in the Oracle TopLink Developer's Guide.

5.3.3 Orion CMP and Non-Oracle Databases

When using the (deprecated) Orion persistence manager with CMP and a non-Oracle database, OC4J does not read the schema XML file specified by the data-sources.xml file managed-data-source element schema attribute.

For example, consider the data-sources.xml and orion-ejb-jar.xml files shown in the following examples:

Example 5-1 Non-Oracle Database data-sources.xml

<connection-pool
    name="ConnectionDB2"
    max-connections="20"
    min-connections="1">
    <connection-factory
        factory-class="com.oracle.ias.jdbcx.db2.DB2DataSource"
        user="jdoe"
        password="password"
        url="jdbc:oracle:db2://server.foo.com:50000;...>
        <property name="databaseName" value="appdb"/>
        <property name="packageName" value="JDBCPKG"/>
        <property name="serverName" value="server.foo.com"/>
        <property name="portNumber" value="50000"/>
        <xa-recovery-config>
            <password-credential>
                <username>jdoe</username>
                <password>password</password>
            </password-credential>
        </xa-recovery-config>
    </connection-factory>
</connection-pool>
 
<managed-data-source
    connection-pool-name="ConnectionDB2"
    schema="database-schemas/db2.xml"
    jndi-name="jdbc/OracleDS"
    name="OracleDS"
/> 

Example 5-2 orion-ejb-jar.xml

<enterprise-beans>
    <persistence-manager name="orion"/>
    <entity-deployment name="EmployeeBean" max-tx-retries="0" location="EmployeeBean">
        <primkey-mapping>
            <cmp-field-mapping
                name="empNo" persistence-name="empNo" persistence-type="integer"
            />
        </primkey-mapping>
        <cmp-field-mapping
            name="empName" persistence-name="empName"
        />
        <cmp-field-mapping
            name="salary" persistence-name="salary"
        />
        <finder-method lazy-loading="true">
            <method>
                <ejb-name>EmployeeBean</ejb-name>
                <method-name>findAll</method-name>
                <method-params></method-params>
            </method>
        </finder-method>
    </entity-deployment>
</enterprise-beans>

Deploying this application will raise an error like:

Error creating table: [oias][DB2 JDBC Driver][DB2]ILLEGAL SYMBOL

To work around this problem, update the orion-ejb-jar.xml to manually define the mapping data types as Example 5-3 shows.

Example 5-3 Updated orion-ejb-jar.xml

<enterprise-beans>
    <persistence-manager name="orion"/>
    <entity-deployment name="EmployeeBean" max-tx-retries="0" location="EmployeeBean">
        <primkey-mapping>
            <cmp-field-mapping
                name="empNo" persistence-name="empNo" persistence-type="integer"
            />
        </primkey-mapping>
        <cmp-field-mapping
            name="empName" persistence-name="empName" persistence-type="varchar(255)"
         />
        <cmp-field-mapping
            name="salary" persistence-name="salary" persistence-type="double"
        />
        <finder-method lazy-loading="true">
            <method>
                <ejb-name>EmployeeBean</ejb-name>
                <method-name>findAll</method-name>
                <method-params></method-params>
            </method>
        </finder-method>
    </entity-deployment>
</enterprise-beans>

5.3.4 Stateful Session Bean Replication Trigger Configuration

In this release, for stateful session beans, OC4J supports session-deployment attribute replication settings of:

  • inherited (default)

  • onShutdown

  • onRequestEnd

  • none

The replication attribute for stateful session beans cannot be configured in Application Server Control. The inherited value is never displayed and the value cannot be reset to none.

To work around this problem, for all stateful session beans, you must manually configure the orion-ejb-jar.xml file session-deployment element replication attribute.

5.3.5 EJB 3.0 Entities and Application Server Control

When you deploy EJB 3.0 entities to OC4J, you cannot manage them using Application Server Control: when you use Application Server Control to view your EJB module, the Entity Beans area will display "No entity beans found".

You can manage all other EJB 3.0 beans such as session beans. For example, if you deploy an EJB module that contains both EJB 3.0 entities and EJB 3.0 session beans, your session beans will be visible through Application Server Control.

5.3.6 Entity and Session Deployment Attribute tx-retry-wait

The orion-ejb-jar.xml file entity-deployment and session-deployment element tx-retry-wait attribute is not in orion-ejb-jar-10_0.xsd (nor in orion-ejb-jar.dtd).

You can still use this attribute in your orion-ejb-jar.xml file but if you do, do not configure OC4J to perform XML file validation (using the -validateXML option on the OC4J startup command line).

5.4 Web Services

This section describes release notes for Web Services. It covers the following topics:

5.4.1 Long File Names Cause Deployment to Fail

If the combined length of the generated file and directory names passes a certain size limit, then deployment will fail and throw an error. This size limit varies for different operating systems. For example, on the Windows operating system, the size limit is 255 characters. - Bug 4673270


Note:

You can avoid this problem by upgrading to a more recent version of the J2SE 5.0 JDK (jdk-1_5_0_06 or later).

The length of the names is controlled by WebServicesAssembler and the deployment code. WebServicesAssembler generates file names based on the method name in the Java class or the operation name in the WSDL. The deployment code creates directories for code generation based on the names of the EAR and the WAR files.

To avoid the generation of file and directory names that are too long, limit the number of characters in the following names to a reasonable length.

  • Method names in Java classes

  • Operation names in the WSDL

  • Directory name for the location of the OC4J installation (also be aware that the JDeveloper's built-in OC4J instance is typically placed in a directory below the JDeveloper installation)

  • File name for a WAR file

  • File name for an EAR file

5.4.2 SoapFaultException Will Not Invoke a Handler's handleFault Method

On the server, a SoapFaultException() thrown by an implementation class will not invoke a handler's handleFault() method. The handleResponse() method is called instead.

5.4.3 Clients Cannot Deserialize SOAP-Encoded anyType Arrays

Clients of SOAP-encoded services are not able to deserialize arrays of type anyType.

5.4.4 Arrays in Document-Literal Encoding May Not be Supported when Mapped to a Single Array Parameter

Arrays may not be supported in document-literal encoding when mapped directly to a Java method parameter. This issue has been seen in DII and WSIF clients.

It also occurs in document-literal Web services that map base64Binary (or hexBinary) arrays to the type byte[][].

There are two possible ways to work around this issue:

  • Keep the wrapper by specifying the WebServicesAssembler argument unwrapParam="false".

  • Use RCP-encoded or RPC-literal styles.

5.4.5 NLS Characters in SYS.XMLTYPE Values May Not be Supported

In Database Web Services, NLS characters that occur in a SQL SYS.XMLTYPE value may not be properly handled.

5.4.6 Self Referential WSDL Imports Fail to Load in the Test Page

The test page (Web Services Home Page) fails to load when using self-referential WSDL imports to the same application. For example:

location="http://samebox:8888/sameapp/import.wsdl"

Since the WSDL is available locally in the application, it should be referenced with a relative path instead. For example:

location="./import.wsdl"

5.4.7 SOAP 1.2 Results May Not be Properly Deserialized

In certain cases, the SOAP 1.2 response may not be properly deserialized, resulting in an element-name-mismatch exception. Specifically, this happens if the Web services returns output parameters and a result value, but this result element does not immediately follow after an http://www.w3.org/2003/05/soap-rpc result element.

5.4.8 WSIF Mapping of Nillable XSD Types

WSIF invocations will map the primitive and nillable XML schema types to primitive Java types. This does not permit the representation of XML nil values.

As a work around, you may want to use SOAP-encoded XML types in the WSDL.

5.4.9 Support for NLS Characters in the WSDL

NLS characters that occur in names in the WSDL, such as in the name of a service, port type, operation, binding or port, are not supported. This may also result in errors on the test page (Web Services Home Page).

5.4.10 Multiple Service Elements in Top Down Web Service Assembly

WebServicesAssembler does not support multiple service elements for the topDownAssemble command.

5.4.11 Multiple Message Formats in a WSDL Application

Multiple message formats, such as RPC-encoded and document-literal, are not supported in a single Web application.

5.4.12 Invalid Configuration Not Detected for EJB 2.1 Web Services

EJB 2.1 Web services will be deployed during server side code generation even if the configuration is incorrect.

5.4.13 Schema Features Limitations

This section describes Web Services schema features limitations. It covers the following topic(s):

5.4.13.1 Schema Features that are Mapped to a SOAPElement

If any of the following schema features are encountered in the WSDL, they will be mapped to a SOAPElement.

  • Any model group with multiple xsd:any elements

  • xsd:choice elements

  • Mixed content

  • Substitution groups

  • A type with multiple xsd:anyAttribute

5.4.13.2 Derived complexTypes Are Not Handled Properly

If a complexType derives from another by adding some attributes, then once the complexType is run through the OC4J WSDL2Java tool, all of the attributes in the subtype will be deleted. If the subtype does not have additional elements, it will be presented as a SOAPElement in the generated Java code.

If you are able to edit the WSDL, then you can work around this problem in either of the following ways:

  • Move the attribute definitions from the sub type to the supertype.

  • Avoid using type extensions.

5.4.13.3 RPC Encoded Does Not Support Complex Types With Attributes

If the schema contains a binding with an RPC-encoded message format and WebServicesAssembler encounters a complexType with attributes, then it will throw an "unsupported type encountered" error message.

5.4.13.4 XML Types xsd:choice and xsd:group are Not Supported for Proxy or Top Down Web Service Assembly

If you are assembling Web Services top down or assembling Web service proxies, WebServicesAssembler cannot consume WSDLs that contain the xsd:choice or xsd:group XML types. If you want to consume a WSDL that contains these XML types, set the WebServicesAssembler dataBinding argument to false and code the SOAPElement so that the payload conforms to the schema definition in the WSDL file.

5.4.14 Limitations on Top Down Processing of Type Mappings

You can specify the WebServicesAssembler ddFileName argument to define type mappings. A type mapping maps a schema type to an existing Java class and allows an optional custom serializer. In the top down use case, if you do not supply a custom serializer, then WebServicesAssembler will always generate a bean for the type.

The work around for this limitation is to ensure that the existing Java class is in the classpath given to WebServicesAssembler and that the overwriteBeans argument is set to false.

5.4.15 REST-Enabled Web Services Cannot be Deployed with Application Server Control

Application Server Control cannot successfully deploy EAR files containing REST-enabled Web services. Instead of using Application Server Control, you can use JDeveloper, Ant, or admin_client.jar to deploy the EAR file.

5.4.16 Explicit HTTP Data Chunking is Not Supported

Enabling chunked data transfer for HTTP as described in Chapter 13 of the Oracle Application Server Web Services Developer's Guide by explicitly setting DO_NOT_CHUNK or CHUNK_SIZE properties will not have any effect. However, chunking will still be implicitly enabled when using attachments.

5.4.17 Runtime Exception Masked By java.io.NotSerializableException

When the Web Service client is invoked by an EJB, the RMI protocol requires that the client parameter, return, and exception implement java.io.Serializable.In the current release, however, the oracle.j2ee.ws.common.util.localization.LocalizableSupport class does not implement java.io.Serializable. Consequently, exceptions thrown by a Web service client invoked by EJB are not properly returned to the invoker. Instead, the invoker receives the description below.

Error deserializing return-value: writing aborted;java.io.NotSerializableException:/@ oracle.j2ee.ws.common.util.localization.LocalizableSupport; nested /exception is:java.io.WriteAbortedException: writing aborted;java.io.NotSerializableException:/@ oracle.j2ee.ws.common.util.localization.LocalizableSupport/java.rmi.UnmarshalException: Error deserializing return-value: writingaborted; java.io.NotSerializableException:

5.4.18 Get NodeLists by Using getFirstChild and getNextSibling Instead of getChildNode

You may see a performance degradation when iterating over a NodeList obtained by using node.getChildNode. This degradation will only be significant for NodeLists with very long lengths.

Instead of using the NodeList obtained by node.getChildNodes, the current Oracle XDK implementation offers an optimization of navigating a list of child nodes by using node.getFirstChild and looping over node.getNextSibling. The following code sample illustrates this technique.

Node n = ...;
if (n.hasChildNodes()) {
   for(Node nd=n.getFirstChild(); nd!=null; nd=nd.getNextSibling()){
         nd.getValue(); // do something with nd       
      }
}

5.4.19 Performing Client Call-out to Web Services from the Database

The Web services call-out utility allows a client to access Web services from the database. Web services call-out can be employed by PL/SQL clients, SQL statements and Java in the database. This utility is based on JPublisher 10g Release 2 (10.2) and Oracle Web Services 10g Release 3 (10.1.3).

Two versions of the utility are available, based on whether your target database is the Oracle 10g database (Release 10.1 or 10.2), or a pre-Oracle 10g database.

The call-out utility is available at the following Web site under the heading "Database as Web Services consumer: Calling-out external Web services".

http://www.oracle.com/technology/sample_code/tech/java/jsp/dbwebservices.html

The following sections describe how a client in the database can perform Web services call-out:

5.4.19.1 How to Perform Web Services Call-Out using Static Proxy and JPublisher

The JPublisher 10g command line option -proxywsdl can be used to generate database-side Java and PL/SQL wrappers from the WSDL file of a Web service. To allow JPublisher to generate and load wrappers for Web service clients into the database, the dbwsa.jar and dbwsclient.jar files must be present in the classpath and inside the database respectively.

The following procedure sets up the environment and the database for JPublisher-supported Web service call-out. This procedure needs to be performed only once.

  1. Download and install the JPublisher 10g Release 2 (10.2) if it is not already on your system.

    You can obtain the JPublisher release from the following Web site:

    http://otn.oracle.com/software/tech/java/sqlj_jdbc/index.html

  2. Add the dbwsa.jar to the directory ORACLE_HOME\sqlj\lib (Windows) or ORACLE_HOME/sqlj/lib (UNIX).

  3. Set up the appropriate JDK as the Java VM and Java compiler.

    The version of the JDK must be the same as the Java VM in the target database:

    • Use the JDK 1.4 for the Oracle 10g (Release 10.1 or 10.2) database.

    • Use the JDK 1.3 for the Oracle 9.2 database.

  4. Add dbwsa.jar file to the classpath environment variable.

  5. Load the dbwsclient.jar file either into the SYS schema or into the schema where the Web service client will be invoked.

    For example, the following loadjava command will load the dbwsclient.jar file into the SYS schema.

    %loadjava -u sys/change_on_install -r -v -f -s -grant public -noverify -genmissing dbwsclient.jar
    

    The following loadjava command illustrates how to load the dbwsclient.jar file into a specific schema.

    % loadjava -u scott/tiger -r -v -f -noverify -genmissing dbwsclient.jar
    

Example

The following example illustrates how to generate Java and PL/SQL wrappers for a Web service client and then invoke it by using SQL statements. The example follows these general steps:

  1. Identify the Web service you want to invoke.

  2. Call JPublisher with the appropriate options to generate the client proxy, the PL/SQL and Java wrappers, and load them into the database.

    A JPublisher command to do this would include the required -proxywsdl and -user options. The command could also include the optional -endpoint, -httpproxy, -sysuser, -dir, and -proxyopts options. For example:

    % jpub -user=username/password -sysuser=superuser_name/superuser_password -proxywsdl=WSDL_URL -endpoint=Web_services_endpoint  
    
  3. Invoke the Web service by using the appropriate SQL, PL/SQL, or Java commands.

The following command lines deploy the Web service javacallout to an OC4J instance. The samples/javacallout.wsdl file is the WSDL file for the Web services.

% java -jar $J2EE_HOME/admin.jar ormi://localhost oc4jadmin welcome -deploy -file samples/javacallout.ear -deploymentName javacallout

% java -jar $J2EE_HOME/admin.jar ormi://localhost oc4jadmin welcome -bindWebApp javacallout javacallout http-web-site /javacallout

The following command creates the Web service client and its Java and PL/SQL wrappers in the subdirectory tmp, then loads the wrappers into the database.

% jpub -user scott/tiger -sysuser sys/change_on_install -proxywsdl=sample/javacallout.wsdl   -endpoint=http://localhost:8888/javacallout/javacallout -dir=tmp

This command produces the following output:

tmp/HelloServiceEJBJPub.java
tmp/plsql_wrapper.sql
tmp/plsql_dropper.sql
tmp/plsql_grant.sql
tmp/plsql_revoke.sql
Executing tmp/plsql_dropper.sql
Executing tmp/plsql_wrapper.sql
Executing tmp/plsql_grant.sql
Loading tmp/plsql_proxy.jar

You can invoke the PL/SQL functions provided in tmp/plsql_wrapper.sql. Each PL/SQL function corresponds to an operation in the Web service. For example, if your Web service is available at the following endpoint:

http://localhost:8888/javacallout/javacallout

then you can issue the following SQL command.

SQL> select jpub_plsql_wrapper.sayhello('hello') from dual;

The command will return the following output.

JPUB_PLSQL_WRAPPER.SAYHELLO('HELLO')
-----------------------------------
HELLO!! You just said :hello

For more information about JPublisher call-out support, see "Web service Call-out using Dynamic Invocation Interface and the SYS.UTL_DBWS Utility" in Oracle Database JPublisher User's Guide. This is available from the following Web site.

http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/index.html

5.4.19.2 How to Perform Web Services Callout using Dynamic Invocation Interface and the SYS.UTL_DBWS Utility

A PL/SQL user can invoke Web services using the PL/SQL package SYS.UTL_DBWS. This package provides wrapper functions for the JAX-RPC Dynamic Invocation Interface (DII) APIs.

The following procedure applies to Oracle Database 10g Release 1 or later. The procedure sets up the database for Web service callout using SYS.UTL_DBWS, and refreshes the utility with more recent features provided in this download.

  1. Load the dbwsclient.jar file into the database, as described in "How to Perform Web Services Call-Out using Static Proxy and JPublisher".

  2. Execute utl_dbws_decl.sql and utl_dbws_body.sql SQL scripts as SYS.

    You can now use SYS.UTL_DBWS to call Web services.

Example

The call-out utilities download includes the SQL scripts samples/test-plsql-dii.sql and samples/test-plsql-dii2.sql.

Both scripts invoke the sayHello operation defined in javacallout.wsdl. Examine the two scripts for their correspondences with the WSDL file. Both scripts produce the following output; the phrase PL/SQL DII client return is produced by the client code.

PL/SQL DII client return HELLO!! You just said :hello  

For more information on the SYS.UTL_DBWS utility, see Oracle Database PL/SQL Packages and Types Reference available from the following Web site.

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

5.4.20 genWsdl Command Does not Preserve Order of Variables

If you use the WebServicesAssembler genWsdl command or Ant task, then the variables in the generated WSDL file will be in a different order from those in the original Java class files. This can cause problems if you continue to modify your Java code after generating the WSDL file. For example, clients may no longer be able to access the server's Web services.

To work around this problem:

  1. Generate the WSDL file with genWSDL.

  2. Edit the generated WSDL file to place the variables in the desired order.

  3. If you are assembling the Web service bottom up, then replace the original WSDL file in the EAR/WAR file with the edited WSDL file.

5.4.21 genValueType Command Does Not Validate Restrictions

In JAX-RPC Web services, the genValueType command generates bean classes for data types but does not validate restrictions in the XSD file.

For example, the following XSD fragment defines a SerialNumber data type based on string that restricts its length to 16 characters. When genValueType creates the bean classes, it does not validate the length.

    ... 
      xsd:element name="SerialNumber"> 
              <xsd:simpleType> 
                <xsd:restriction base="xsd:string"> 
                  <xsd:length value="16"/> 
                </xsd:restriction> 
               </xsd:simpleType> 
             </xsd:element>/ 
    ... 

This is a known limitation: the Oracle Web Services JAX-RPC stack does not enforce most restrictions. To work around this problem, write your own bean classes instead of using generated bean classes.

5.4.22 XML Serialization Does Not Accept the Array Java Data Type for Document-Literal-Bare Message Format

If you attempt to expose a Java method that uses the array Java type as a Web service that uses the document-literal-bare (unwrapped) message format, then the serialization of the method will fail.

For example, assume that you want to expose the method public SearchResult[] WebServiceClass() which has the following definition:

    public class SearchResult implements Serializable {
    public SearchResult() { }
    private String name;
    private String value;
    public void setName(String name) { this.name = name; }
    public String getName() { return name; }
    public void setValue(String value) { this.value = value; }
    public String getValue() { return value; }
     }

     public SearchResult[] WebServiceClass(String testTriger) {
              System.out.println(testTriger);
              return STATIC_RESULT_A;
         }
 

If you create the Web service bottom up, the WSDL file will contain the following XML for the SearchResult method:

         ...
        <sequence>
         <element name="result" type="tns:SearchResult" nillable="true" minOccurs="0"
         maxOccurs="unbounded"/>
         </sequence>
         ...

However, on executing the service, the following error will be returned:

ERROR OWS-04046 serialization error: java.lang.ClassCastException:

The work around for this issue is to use doc-literal-wrapped message format.

5.5 Web Services Security

This section describes release notes for Web Services Security. It covers the following topic(s):

5.5.1 Stale Indirect User Accounts Must be Removed Manually

In release 10.1.3, you must use Application Server Control to obfuscate the keystore, signature key, and encryption key passwords. During obfuscation, an indirect user account is created in the system-jazn-data.xml file.

If you undeploy the application, these indirect user accounts are not removed. You must manually delete the them by using Application Server Control.

The following list describes how you can identify the names of indirect user accounts for global-level and port-level keystores and keys.

  • For a port-level keystore, the name of the indirect user account is created with the following format:

    applicationName.portName.keystore.actual-keystore-name

    For example:

    my-security-sample.myport.keystore.myks.jks

  • For a global-level keystore, the name of the indirect user account is created with the following format:

    default.keystore.actual-keystore-name

    For example:

    default.keystore.myks.jks

  • For port-level keys, the name of the indirect user account is created with the following format:

    applicationName.portName.key.actual-key-alias

    For example:

    my-security-sample.myport.key.mysignkey

  • For global-level keys, the name of the indirect user account is created with the following format:

    default.key.actual-key-alias

    For example:

    default.key.mysignkey

5.6 OC4J Services

This section describes release notes for OC4J Services. OC4J Services include: Java Naming and Directory Interface (JNDI), Oracle Enterprise Messaging Service (OEMS), Data Sources, Remote Method Invocation (ORMI and IIOP), OC4J Transaction Support, Java Object Cache (JOC), and XML Query Service (XQS).

The section contains release notes for the following OC4J Services:

5.6.1 JNDI

This section describes release notes for JNDI. It covers the following topic(s):

5.6.1.1 New Package Names for RMI and Application Client Initial Context Factories

In this release, note the following new package names for the initial context factories:

  • oracle.j2ee.rmi.RMIInitialContextFactory

  • oracle.j2ee.naming.ApplicationClientInitialContextFactory

5.6.1.2 These Environment Properties Are No Longer Supported

The following environment properties are no longer supported as of release 10.1.3:

dedicated.connection

dedicated.rmicontext

In release 10.1.3, the known ORMI /JNDI bugs that required these flags have been resolved. To enable client-side ORMI load-balancing in 10.1.3, use the oracle.j2ee.rmi.loadBalance property described in the "Load Balancing" section of the JNDI chapter of the Oracle Containers for J2EE Services Guide.

5.6.1.3 Context Factory Restructuring

The package structure for context factories provided by previous releases of OC4J is deprecated, and is replaced by a more consistent naming structure. The following context factories are deprecated in release 10.1.3:

  • com.evermind.server.rmi.RMIInitialContextFactory

  • com.evermind.server.ApplicationClientInitialContext Factory

  • com.oracle.iiop.server.IIOPInitialContextFactory

For the new context factory names that replace the deprecated ones, see the java.naming.factory.initial initial context property described in the "Constructing a JNDI Context" section of the JNDI chapter of the Oracle Containers for J2EE Services Guide.

5.6.1.4 Objects that Implement javax.naming.Referenceable Interface

OC4J JNDI in 10.1.3 now provides full support for binding objects that implement the javax.naming.Referenceable interface

5.6.1.5 Local Host Not Supported

The java.naming.provider.url JNDI property does not support the value localhost when a remote client connects to an application server instance that is managed by OPMN. The value must be the complete hostname or IP Address. This does not affect clients that connect to standalone application server instances.

5.6.2 Oracle Enterprise Messaging Service (OEMS)

This section describes release notes for the Oracle Enterprise Messaging Service (OEMS). It covers the following topic(s):

5.6.2.1 Special Considerations For Undeploying the Default Instance of the Oracle gJRA Resource Adapter

OC4J cannot be started with OracleASjms, the pre-packaged standalone JMS Connector, undeployed without certain changes. This note deals with additional changes necessary to start OC4J while the default instance of the Oracle gJRA resource adapter, OracleASjms, is undeployed. For general undeployment of a resource adapter, see the Oracle Containers for J2EE Services Guide. The following additional changes must be made:

  • In $J2EE_HOME/config/application.xml comment out the following lines:

    <web-module id="jmsrouter_web" path="../../home/applications/jmsrouter.war" />
    <ejb-module id="jmsrouter_ejb" path="../../home/applications/jmsrouter-ejb.jar" />
    
  • In $J2EE_HOME/config/default-web-site.xml, comment out the following line

      <web-app application="default" name="jmsrouter_web" root="/jmsrouter" load-on-startup="true" />
    

If these changes are made, OC4J may be started, but the OracleAS JMS Router will not work.

To reinstate the JMS Router:

  1. Fully redeploy the OracleASjms resource adapter instance.

  2. Uncomment the lines mentioned above in $J2EE_HOME/config/application.xml and $J2EE_HOME/config/default-web-site.xml.

When OC4J is restarted, the OracleAS JMS Router should be available.

5.6.2.2 OC4J May Fail to Restart after Abnormal OC4J Shutdown

If you encounter OC4J JMS Server startup problems after an abnormalOC4J shutdown, first check that no other OC4J JMS Server is running and using the same persistence files. Then remove any.lock files from the

 ORACLE_HOME/j2ee/instance_name/persistence 

directory and try restarting again.

If problems persist, confirm that the jms.xml file is valid.

If problems still persist, remove the jms.state file from the persistence directory and try again, but be aware that removing this file may result in loss of transaction information. For additional information, see the section "Abnormal Termination" in the "Oracle Enterprise Messaging Service" chapter of the Oracle Containers for J2EE Services Guide.

5.6.2.3 getconfigProperties() Lists Some Unsupported Properties

The list of properties returned by the JMS Administrator MBean's getconfigProperties() method includes the following properties that are neither documented nor supported:

  • oc4j.jms.checkPermissions

  • oc4j.jms.j2ee14

  • oc4j.jms.noJmx

  • oc4j.jms.printStackTrace

  • oc4j.jms.rememberAllXids

5.6.2.4 XA-styled JMS Connections Not Supported Between OC4J Versions

Oracle Application Server does not support XA-styled JMS connections between different versions of OC4J.

5.6.2.5 Poor Performance When Persisting Messages to a Database

The OEMS database persistence feature performs poorly if the queue tables are configured to use old compatibility modes. The compatibility mode is set using the compatible parameter. For example:

DBMS_AQADM.CREATE_QUEUE_TABLE(
        Queue_table            => 'demoTestQTab',
        Queue_payload_type     => 'SYS.AQ$_JMS_MESSAGE',
        sort_list              => 'PRIORITY,ENQ_TIME',
        multiple_consumers     => false,
        compatible             => '8.1.5');

The compatible parameter should only be set to older modes if there are issues migrating to the new schema layouts or if existing queue tables cannot be exported to the new schema layouts.

When using the latest schema layouts, set the compatible parameter to 10.0.0.0.0 or omit the parameter to use the default compatibility mode. Either option ensures that the most efficient schema and locking mechanisms are used.

5.6.3 Data Sources

This section describes release notes for Data Sources. It covers the following topics:

5.6.3.1 New Syntax for Data Source Configuration

The data sources subsystem has been completely rewritten. Part of the rewrite includes a new syntax for the configuration using the data-sources.xml file. The pre-10.1.3 syntax is still supported but users are encouraged to use the new syntax. Also users are encouraged to convert their existing application data-sources.xml files to the new syntax. See the Oracle Containers for J2EE Services Guide for details on converting data-sources.xml.

5.6.3.2 OracleConnectionCacheImpl Deprecated

The class oracle.jdbc.pool.OracleConnectionCacheImpl has been deprecated because it does not support multiple schemas. When defining the factory-class for connection factories and data-source-class for native data sources, use oracle.jdbc.pool.OracleDataSource instead of oracle.jdbc.pool.OracleConnectionCacheImpl.

5.6.3.3 Converting Existing Data Sources to Release 3 Format

The OC4J 10.1.3 implementation understands the 10.1.3 and the pre-10.1.3 (10.1.2 and 9.0.4) formats of the data-sources.xml file. For an application that was previously used in a pre-10.1.3 OC4J implementation and contains its own data-sources.xml file, the OC4J 10.1.3 implementation automatically converts the data-sources.xml file from the pre-10.1.3 format to the 10.1.3 format when you use the Application Server Control Console to change anything in the data-sources.xml file, such as modifying an existing data source or creating or deleting a data source.

With an active OC4J instance in a standalone environment, you can alternatively use admin.jar with the following syntax to manually convert a pre-10.1.3 data-sources.xml file to the 10.1.3 format. This is discussed in the Oracle Containers for J2EE Configuration and Administration Guide. The guide does not mention that you can specify an ORMI URL only when OC4J is running or that the ORMI URL is optional.

java -jar admin.jar ormi://oc4jHost:oc4jOrmiPort adminId adminPassword -convertDataSourceConfiguration old-data-sources.xml new-data-sources.xml

You can also convert a data-sources.xml file before deployment, without a running OC4J instance. The syntax for this offline conversion is as follows:

java -jar admin.jar -convertDataSourceConfiguration old-data-sources.xml new-data-sources.xml

Notes:

  • If you include the ORMI port, then OC4J must be running. When OC4J is not running, you must omit the ORMI URL from the admin.jar command line.

  • If you do not include the ORMI port, then the admin.jar command will work either way, that is, with OC4J running or with OC4J not running.

  • The admin.jar utility works only in the standalone OC4J environment. This utility is installed in the Oracle Application Server environment, but does not work in an OPMN-managed environment.

  • The newer admin_client.jar utility works in both environments, standalone and managed Oracle Application Server. However, the admin_client.jar utility does not convert data-sources.xml files.


Check for Consistency Between Your Application and the New data-sources.xml File

After conversion, whether manual or automatic, visually inspect the new data-sources.xml file and confirm that there is consistency between your application and the new file regarding the JNDI location used to refer to a data source. This is advisable because the new file may contain data source definitions that are not used.

This happens because the old format uses multiple location attributes (such as location, ejb-location, xa-location, and so on). The conversion to the new 10.1.3 format creates a separate data source in the new data-sources.xml file corresponding to each location attribute specified in the old data-sources.xml file. In most cases, client applications will only use the data source defined by either the location or ejb-location attribute. But we cannot be sure of this. Therefore, the converted data-sources.xml may have definitions that are not used by the applications and can be removed from the file.

You can also refer to examples of the new data-sources.xml format in the "Data Sources" chapter of the Oracle Containers for J2EE Services Guide.

5.6.3.4 Configuring OC4J instance for oci drivers

If any application uses oci drivers for a datasource connection then, add the following <environment> section in opmn.xml for that particular OC4J instance. For example, if the application is deployed to the default home instance, then configure the OC4J instance as follows:

<ias-component id="OC4J">
   <environment>
      <variable id="SHLIB_PATH" value="$ORACLE_HOME/lib32" />
      <variable id="LD_LIBRARY_PATH" value="$ORACLE_HOME/lib32" />
   </environment>
     <process-type id="home" module-id="OC4J" status="enabled">

5.6.3.5 SQLServer Named Instance Definition Corrected

A SQL Server named instance defined outside of Java code, i.e., in data-sources.xml in OC4J, should have only one backward slash('\') separating the server name and the instance name.

This is incorrectly documented in the Data Sources chapter of the Oracle Containers for J2EE Services Guide. For further information, see the release note at Section 5.9.3.3, "SQLServer Named Instance Definition Corrected"

5.6.3.6 Use the Current Oracle JDBC Drivers when Using Shared Libraries

In OC4J 10.1.3.0, some Orion CMP features may not work as designed if the current Oracle JDBC Drivers that are shipped with OC4J are not used, and the JDBC Driver libraries are added to an OC4J instance using the Shared Library feature. In such situations, different JDBC library versions will clash.

5.6.3.7 Fast Connection Failover Is Disabled When Using OracleXADataSource

In earlier versions of release 10.1.3, OC4J incorrectly disables Fast Connection Failover (FCF) when the connection factory for a connection pool is configured to use oracle.jdbc.xa.client.OracleXADataSource. One-off patch number 5001421 has been created to fix the problem. This patch can be downloaded at the Oracle MetaLink.

5.6.3.8 Upgrading the Oracle THIN JDBC Driver

The JDBC THIN driver cannot be upgraded or changed at the Oracle Application Server-instance level due to component dependencies. JDBC THIN driver upgrades must be completed for each OC4J instance using the Shared Library feature.

Instructions for upgrading the JDBC THIN driver are located on the OTN How To site:

http://www.oracle.com/technology/tech/java/oc4j/1013/how_to/index.html

5.6.4 OC4J Transaction Support

This section describes release notes for OC4J Transaction Support. It covers the following topics:

5.6.4.1 Change the Default JTA Recovery Password Immediately

The default JTA recovery password should be changed immediately. OC4J is shipped with a default password, which should be changed after install. The recovery password is configured in the configuration file jazn-data.xml, which is in the $J2EE_HOME/config directory. To modify the transaction recovery password, change the credentials value for the user JtaAdmin in the jazn-data.xml file.

<user>
    <name>JtaAdmin</name>
    <display-name>JTA Recovery User</display-name>
    <description>Used to recover propagated OC4J transactions</description>
    <credentials>!newJtapassword</credentials>
</user>

Even if OC4J is configured to use a security service other than JAZN, such as OID, the transaction recovery password must still be configured in jazn-data.xml.

5.6.4.2 New Configuration File for Transaction Manager

All transaction-manager-related configuration is now done in the transaction-manager.xmlfile.

5.6.4.3 The In-DB Coordinator Is Deprecated

The use of the in-database transaction coordinator by OC4J is deprecated as of release 10.1.3. Oracle recommends that the middle-tier transaction coordinator be used going forward.

5.6.4.4 The Mid-Tier Coordinator Does Not Use a Persistent Store By Default

The mid-tier coordinator does not use a persistent store by default. Prior to use in production, the mid-tier coordinator should be configured to use a persistent store which will enable transaction recovery.

5.6.4.5 DMS must be enabled to obtain JTA statistics

To obtain JTA statistics, ensure that DMS is enabled.

5.6.4.6 Transaction Propagation Between 10.1.3 Instances Only

Transaction propagation is only supported between 10.1.3 instances.

5.6.5 RMI

This section describes release notes for OC4J Remote Method Invocation (RMI and IIOP). It covers the following topics:

5.6.5.1 RMI Recommendations

In this release, note the following recommendations:

  • Environment variables dedicated.connection and dedicated.rmicontext are not required for lookup using EJBs in 10.1.3

    The dedicated.connection environment variable is still required for EJBs hosted in 10.1.2 being looked up from 10.1.3 - Bug 4895256

  • The RMI port may not be released immediately sometimes. - Bug 4892487

  • Old tunneling is deprecated. Use the new URL, as described in the "Configuring ORMI Tunneling through HTTP" section of the "RMI" chapter of the Oracle Containers for J2EE Services Guide.

  • Old package names for context factories deprecated and new names are recommended to be used, as described in the "Constructing JNDI Context" section of the "JNDI" chapter of the Oracle Containers for J2EE Services Guide.

5.6.5.2 Excessive ORMI Connections Created

Setting the JNDI property oracle.j2ee.rmi.loadBalance to either context or lookup currently creates separate ORMI connections for each call to new InitialContext. Closing the context does not cause the connection to be closed. Doing this repeatedly will result in performance degradation.

5.6.5.3 Workaround for HTTP Tunnelling Failover

The following workaround is necessary for HTTP Tunnelling failover to work in iAS mode. This workaround applies to iAS mode, where the provider URL points to OHS using mod_oc4j. The workaround is not needed in standalone mode, where the provider URL lists multiple OC4J instances.- Bug 4599521

The workaround must be done for all OC4J server instances in the cluster, such as home1, home2, and so on.

  1. Go to Application Server Control Console.

  2. Select a server instance, such as "home".

  3. In the instance window, select the Applications tab.

  4. Select the "default" application.

  5. In the Application:default window, select the Administration tab.

  6. Select the Clustering Properties task.

  7. Select the "Override parent application clustering settings" radio button. Specify Clustering Enable.

  8. Click the OK button.

  9. Repeat for each OC4J server instance.

  10. Add the <distributable /> element to the <ORACLE_HOME>/j2ee/home/default-web-app/WEB-INF/web.xml file.

  11. Restart the server using opmnctl stopall and then opmnctl startall.

5.6.5.4 Incorrect "Provider URL..." Error Message

In certain cases when there is something wrong with the provider url format, the following incorrect error message is displayed:

" Provider URL must be of the form [opmn:]corbaname::host:port#/appname"

The URL format in the error message is incorrect. The correct URL format is:

[opmn:]corbaname::host:port#[instancename#]appname

5.6.6 XQS

This section describes release notes for XML Query Service (XQS). It covers the following topic(s):

5.6.6.1 Implementation Restriction on the fn:doc() and fn:collection() Functions

The only arguments that the current implementation of the built-in XQuery functions fn:doc and fn:collection support are URLs with the "file" protocol that specify a path to a file on the local file system, as in this function call:

   fn:doc("C:/MyDocuments/XQS/myView.xq")

The protocol part of the URL is always assumed to be "file" and can be omitted.

As an alternative to the fn:doc() function, you can use an XQS document function to access a document via any URL that Oracle Application Server supports. For example, a <document-source> element has the following configuration:

   <document-source>
         <function-name prefix="ns"> genericFile </function-name>
   </document-source>

The XQS function genericFile() can be used in a query expression, as follows:

   declare namespace ns = "…"; 
   declare function ns:genericFile() external; 

5.6.6.2 Incorrect XQS Type-Checking Example

The XQS chapter in the OC4J Services Guide contains an error. The example XQuery expression provided in the "Type-Checking for Input Parameters" section is incorrect. The following example is correct:

import schema namespace ns1="urn:namespace_1" at "http://mydomain/myschema.xsd";

declare namespace xqs = "http://xmlns.oracle.com/ias/xqs";
declare function xqs:takeNS1Input($param as element(ns1:InputElement)?) external;

let $in := <ns1:InputElement>...</ns1:InputElement>
let $y := xqs:takeNS1Input($in)
return <result>$y//ns1:Content</result>

5.6.6.3 XQS Schema Import Support

The XQS chapter in the OC4J Services Guide contains an error. The "XQuery Optional Features" section indicates that the XQuery schema import feature is not supported. XQS does support the schema import feature as defined by the W3C.

5.7 J2EE Connector Architecture (J2CA)

This section describes release notes for J2EE Connector Architecture (J2CA). It covers the following topics:

5.7.1 J2CA Lifecycle Issues

  • Unable to deploy multiple versions of a standalone RAR

  • A standalone RAR takes precedence over one in an application. When the same fully-qualified class exists in both a standalone RAR and also in a RAR deployed in an EAR, the class will always be loaded from the standalone RAR.

  • When stopping a resource adapter, OC4J does not always properly stop dependent applications.

5.7.2 Cannot Cast a Connection Handle to a Concrete Type

OC4J wraps all connection handles with connection handle proxies to perform connection association and therefore connection handles can only be cast to interfaces implemented by the connection handle. An attempt to cast a connection handle to a concrete class will cause a ClassCastException.

5.7.3 RAR Name Must Be Unique

NullPointerException occurs if an attempt is made to deploy an RAR when there is already an RAR deployed with the same name.

5.7.4 Set inactivity-timeout-check in oc4j-ra.xml

Set inactivity-timeout-check in the oc4j-ra.xml file. Changing the inactivity-timeout-check property for an RAR connection pool with ASControl does not work properly. This property should be set to the proper value in the oc4j-ra.xml file prior to deploying the resource adapter.

5.7.5 Revised Release Note - Stop the Resource Adapter Before Redeploying or Undeploying It

When a resource adapter with active endpoints is redeployed or undeployed without stopping it first, OC4J throws a DeployerException due to active endpoints. To work around this issue, stop the resource adapter prior to redeploying or undeploying it.


Note:

This release note is revised to include undeployment as well as redeployment.


5.7.6 Explicit Configuration Is Necessary For Resource Adapter To Support XA Transaction Recovery

XA transaction recovery can be configured using Application Server Control using the following steps:

  1. In the Connection Factories tab accessed from the Resource Adapter Home page for the appropriate resource adapter, choose the JNDI location of the connection factory that you want to configure.

  2. In the Options tab of the resulting Edit Connection Factory page, you can do any of the following:

    • Add a new user name.

      After specifying the user name, you can specify a password directly or indirectly. For a direct password, choose Password and type the password itself.

      For an indirect password, choose Indirect Password and type a key (which might just be the user name, for example). OC4J uses the key to do a lookup in the User Manager (specifically, in the jazn-data.xml file).

    • Change an existing user name or password

5.7.7 ASControl Changes to Work Manager Thread Pool Not Persisted If <work-manager-thread-pool> Not Defined

Changes to work manager thread pool properties from ASControl are not persisted to the server.xml file if there is no <work-manager-thread-pool> element defined.

5.8 OracleAS JAAS Provider and Security

This section describes release notes for the OracleAS JAAS Provider in Release 10.1.3.0.0. It covers the following topics:

5.8.1 COREid Status for 10.1.3.0.0

The initial version of the 10.1.3.0.0 OC4J Release Notes pointed out that as of the 10.1.3.0.0 release, you cannot use the COREid Access security provider for J2EE Web applications deployed in 10.1.3 OC4J. This update is to point out that, in fact, you cannot yet use any functionality through the COREid custom login module. In other words, COREid integration with Web and EJB applications will not be supported until a patch is made available. (Because the Oracle Web Services Manager agent covers integration with COREid, there *is* COREid integration for Web services in the 10.1.3.0.0 implementation.) Refer to OracleMetaLink to check the status of the future 10.1.3.0.0 patch set.

5.8.2 Restart Application After Configuring Through Security Provider MBean

Whenever a configuration change is made using Application Server Control or the OC4J security provider MBean, the application must be restarted. Until the application is restarted, all other operations of the security provider MBean are invalidated and will return the following message: "The security provider has been changed. Operation temporarily invalidated till application or OC4J restart."

5.8.3 Necessary Permission Grants When Using Security Manager

Users running with a SecurityManager in an Oracle Application Server environment should be aware that if an OC4J instance name other than home is used, adding the following permission grants to ORACLE_HOME/j2ee/instance_name/config/java2.policy will be necessary for proper operation of OC4J:

grant codebase
"file:${oracle.home}/j2ee/${oracle.oc4j.instancename}/connectors/OracleASjms/OracleASjms/gjra.jar" {
    permission java.security.AllPermission;
};

grant codebase "file:
${oracle.home}/j2ee/${oracle.oc4j.instancename}/connectors/datasources/datasources/datasources.jar"
{
    permission java.security.AllPermission;
};

(Failure to add these does not compromise security but may hinder OC4J operations.) - Bug 4942880

5.8.4 Indirect Users for Password Indirection

If you choose to use indirect passwords in the OC4J 10.1.3.0.0 implementation, an indirect user is created in the system-jazn-data.xml file when you use this feature. Be aware that these indirect user accounts are not removed automatically when an application is undeployed; you must use Application Server Control Console to delete any stale indirect user accounts manually.

5.8.5 JAAS Policy Configuration with Custom Realms

When you use custom realms, and JAAS policies are granted to users or roles in the custom realm, you should do the following:

  1. In the <jazn> element of your application orion-application.xml file, specify a default-realm setting of "custom_realm_name".

  2. Do not specify a location attribute setting in the <jazn> element.

  3. Set the jaas.username.simple property to "false" in jazn.xml, using a <property> subelement of the <jazn> element.

These steps allow the custom realm and its users, roles, and policies to be persisted in system-jazn-data.xml.

Note that to use JAAS authorization, in particular to grant permissions to users or roles in a custom realm, the custom realm and its users and groups must be defined and persisted in system-jazn-data.xml, not in a jazn-data.xml file deployed in the application EAR file.

5.8.6 User Manager Delegation for the File-Based Provider

Before HTTP requests can be dispatched to the target servlet, the OracleAS JAAS Provider JAZNUserManager coordinates authentication. JAZNUserManager supports the OC4J UserManager delegation model, but effectively this applies only to the file-based provider. With delegation, if a user or group is not found at the application-level JAZNUserManager instance, the request is delegated to the parent user manager.

Specifically, note the following restrictions and additional details:

  • If the application and parent application are both configured to use the file-based provider, delegation goes up through the parent hierarchy as far as necessary, until a parent is not configured to use the file-based provider. Delegation is not propagated beyond that point.

  • If the application is configured to use the file-based provider, and the parent is configured to use the LDAP-based provider, an external LDAP provider, or a custom login module, there is no delegation support.

  • If the application itself is configured to use the LDAP-based provider, an external LDAP provider, or a custom login module, there is no delegation support.


Note:

In OC4J, the system application is at the root of the hierarchy, but the default application is the default parent of any deployed application. Both use system-jazn-data.xml as the user repository.

5.8.7 JNDI Context Pool Timeout Property for Oracle Internet Directory

For the LDAP-based provider (Oracle Internet Directory), the OC4J 10.1.3 implementation includes a new property, JNDI_CTX_POOL_TIMEOUT, that you can set in order to specify a timeout for the JNDI context pool. This may be useful, for example, when there is a firewall between the middle tier, including OracleAS JAAS Provider, and the Oracle Internet Directory. The timeout on the firewall connection could be coordinated with the timeout of the directory context.

Set this property through a <property> subelement of the <jazn> element in the jazn.xml file, specifying the timeout in milliseconds. The following example specifies a timeout of 5 seconds.

<jazn ... >
   <property name="JNDI_CTX_POOL_TIMEOUT" value="5000">
   ...
</jazn>

5.8.8 Miscellaneous OracleAS JAAS Provider and Security Release Notes

  • Although it is already stated in the 10.1.3.0.0 OC4J Security Guide, make special note of the fact that the OC4J administration account, admin in previous releases, has changed to oc4jadmin.

  • Security context propagation is supported only between OC4J 10.1.3 instances.

5.8.9 Signature Verification Fails for X.509 Token-Based Authentication On Windows Platforms

On Windows platforms, there is a known issue with X.509 token authentication. The signature verification fails for X.509 token-based authentication.

If X.509 token-based authentication is not used, then the digital signature verification of SOAP body or elements works as expected.

For example, digital signature verification of a web service works as expected if web service is secured with combination of username token or SAML token-based authentication.

Refer to OracleMetaLink to check the status of a future patch to remedy this problem.

5.8.10 J2EE SSO Is Deprecated in the OC4J 10.1.3.0 Implementation

The OC4J 10.1.2 phase 2 implementation provided a lightweight single sign-on feature, characterized by the use of a stateful session EJB to maintain SSO state across multiple Web applications. This J2EE SSO was particularly intended for standalone OC4J, because it did not require a full Oracle Application Server environment as OracleAS Single Sign-On does.

In the OC4J 10.1.3.0 implementation, J2EE SSO still exists but is deprecated and undocumented. It is anticipated that in the OC4J 10.1.3.1 implementation, J2EE SSO will be desupported and replaced by an alternative implementation of equivalent functionality.

5.8.11 Basic Authentication Fallback for Digest Authentication Module

By default in the OC4J 10.1.3.0.0 implementation, the digest authentication module also handles basic authentication if the client sends a basic authentication header. To disable this behavior, so that the digest module would never handle basic authentication, set the digest.auth.basic.fallback property to "true" as in the example below. (Note that the logic of this setting is counterintuitive and will be reversed in the next release.)

<jazn provider="XML" location="jazn-data.xml">  <property name="digest.auth.basic.fallback" value="true" />  ...</jazn> 

5.8.12 Controlling Caching of JNDI Contexts for LDAP Connections

By default in 10.1.3.x implementations, OC4J uses java.lang.ref.WeakReference objects to cache JNDI contexts when using connection pooling for connections to the LDAP-based provider, and uses JVM garbage collection to garbage-collect the JNDI contexts.

We recommend, however, that you not rely on this WeakReference and JVM garbage collection functionality. You can disable it with the following property setting:

<jazn ... >
   <property name="jndi.ctx_pool.weakref.enable" value="false" />
   ...
</jazn>

(The default setting is "true".) When this is disabled, OC4J uses the following properties, which you should set appropriately, to control caching in the connection pool:

  • jndi.ctx_pool.timeout: Timeout value, in milliseconds, for the LDAP JNDI connection pool. The default is 0, for no timeout. The recommended setting is 3600000 milliseconds, which is one hour.

  • jndi.ctx_pool.threshold_size: Threshold to limit the number of idle connections in the pool. The default, and recommended initial setting, is 100.

(Both properties are ignored if jndi.ctx_pool.weakref.enable is set to "true".)

For example:

<jazn ... >
   <property name="jndi.ctx_pool.weakref.enable" value="false" />
   <property name="jndi.ctx_pool.threshold_size" value="100" />
   <property name="jndi.ctx_pool.timeout" value="3600000" />
   ...
</jazn>

Notes:


5.8.13 JAZN Tool No Longer Includes -clustersupport

The DCM component is no longer supported in Oracle Application Server 10.1.3. Consequently, the -clustersupport option is no longer available in the jazn.jar administrative tool.

Problem

Using the -clustersupport option when invoking jazn.jar results in the following error:

An error has occured in propagating the changes to the cluster. java.lang.ClassNotFoundException oracle.security.jazn.smi.DcmUtil

This problem occurs because Distributed Configuration Management (DCM), used in prior releases of Oracle Application Server to replicate common configuration information across a cluster, is no longer supported with release 10.1.3. Consequently, the -clustersupport option is not supported in the JAZN (jazn.jar) administrative tool.

Solution

Do not use the -clustersupport option when invoking jazn.jar.

5.8.14 AJP13 Protocol Vulnerable to Bypass User Authentication

When OC4J is running a site using the AJP13 protocol, a security vulnerability exists if a remote attacker can directly access the AJP port on the machine running OC4J. The AJP13 protocol defines an AJP parameter remote_user, which is used by OHS to implement mod_osso. An attacker can use this parameter to bypass authentication on OC4J. If a user constructs an AJP packet that inserts a valid remote_user value as an AJP parameter, the user will be able to access resources that the specified user (remote user) has permission to access.

You must ensure that the system running OC4J does not expose the AJP port to the outside world.

You can protect against the vulnerability in either of the following ways:

5.9 Documentation Errata

This section describes known errors in the OC4J documentation in Oracle Application Server 10g Release 3 (10.1.3). It covers the following books:

5.9.1 Web Services

This section describes Web Services documentation errata. It covers the following topic(s):

5.9.1.1 WebServicesAssembler Command genInterface Does Not Use the use and style Arguments

Book: Oracle Application Server Web Services Developer's Guide

Chapter 4, "OracleAS Web Services message Formats", Section: "Selecting Message Formats"

The list of WebServicesAssembler commands that can use the use and style arguments includes genInterface. This is an error. The genInterface command cannot use these arguments.

5.9.1.2 Error in Ant Task for Assembling JMS Web Services

Book: Oracle Application Server Advanced Web Services Developer's Guide

Chapter 8, "Using JMS as a Web Service Transport", Section: "Assembling a Web Service Bottom Up that Uses JMS Transport"

In Step 1, there is a missing closing angle bracket in the <oracle:porttype clause, at the end of the sendConnectionFactoryLocation attribute. The <oracle:porttype clause should read as follows:

...
   <oracle:porttype
       interfaceName="oracle.j2ee.ws.jmstransport.Echo"
       className="oracle.j2ee.ws.jmstransport.EchoImpl"
       >
       <oracle:port
          uri="/echo"
          sendQueueLocation="jms/senderQueue"
          name="EchoPort"
          sendConnectionFactoryLocation="jms/senderQueueConnectionFactory">
      </oracle:port>
...

5.9.1.3 Additions to List of Supported Platforms

Book: Oracle Application Server Web Services Developer's Guide

Chapter 3 lists the platforms on which Oracle Web Services is supported. The HP-UX and AIX platforms should be added to this list.

The Oracle Web Services stack is supported on the same platforms as Oracle Application Server and OC4J. For an up-to-date list of the supported platforms for each release, see the following Web site: http://metalink.oracle.com

5.9.2 Oracle Application Server Advanced Web Services Developer's Guide

This section describes errors in the Oracle Application Server Advanced Web Services Developer's Guide. It covers the following item(s):

5.9.2.1 Auditing and Logging File Path Corrections

The Oracle Application Server Advanced Web Services Developer's Guide Chapter 6, "Auditing and Logging Messages" lists the paths to the auditing and logging log.xml files as: <ORACLE_HOME>\log\wsmgmt\logging\log.xml and <ORACLE_HOME>\log\wsmgmt\audit\log.xml

These paths are incorrect. The correct paths are: <ORACLE_HOME>\j2ee\<OC4J_instance_name>\log\wsmgmt\auditing\log.xml and <ORACLE_HOME>\j2ee\<OC4J_instance_name>\log\wsmgmt\logging\log.xml

5.9.2.2 Incorrect XML in Examples in the "Using Web Service Providers" Chapter

The chapter titled "Using Web Service Providers" in the Oracle Application Server Advanced Web Services Developer's Guidecontains examples with incorrect XML.

Example 10-5

"oracle-webservices.xml Fragment, with a <provider-description> Clause" is not well-formed xml.

  • The spaces after slashes in closing tags must be removed:

    Change: </ wsdl-service-name> to: </wsdl-service-name>

    Change: </ implementation-class> to: </implementation-class>

  • Closing tag is missing a slash:

    Change: <auditing>...<auditing> to: <auditing>...</auditing>

Example 10-6

"Provider Elements in the web.xml Deployment Descriptor" is well-formed but invalid XML.

The description and display-name elements are out-of-order and mis-positioned according to the JDeveloper 10.1.3.3.0.4157 schema validation:

Change:

        <servlet-name>LoggerProviderPort</servlet-name> 
        <display-name>LoggerProviderPort</display-name> 
        <description>JAX-RPC endpoint  Provider Port</description> 

to:

        <description>JAX-RPC endpoint  Provider Port</description> 
        <display-name>LoggerProviderPort</display-name> 
        <servlet-name>LoggerProviderPort</servlet-name> 
 

5.9.3 Oracle Containers for J2EE Services Guide

This section describes errors in the Oracle Containers for J2EE Services Guide. It covers the following item(s):

5.9.3.1 Incorrect URL in Native Data Source Example for Fast Connection Failover

In the Oracle Containers for J2EE Services Guide Chapter 4, "Data Sources", the "Enabling Fast Connection Failover in the data-sources.xml File" section, in the native data source example for fast connection failover labelled "Enabling Fast Connection Failover in the data-sources.xml File" is incorrect.

  • The url is not correct for a RAC environment.

  • The brackets in the <native-data-source> element do not match correctly.

The INCORRECT example is as follows:

<native-data-source> 
   name="nativeDataSource"
   jndi-name="jdbc/nativeDS"
   description="Native DataSource"
   data-source-class="oracle.jdbc.pool.OracleDataSource"
   user="scott"
   password="tiger"
   url="jdbc:oracle:thin:@localhost:1521:oracle">
  <property name="connectionCacheName" value="ICC1"/>
  <property name="connectionCachingEnabled" value="true"/>
  <property name="fastConnectionFailoverEnabled" value="false"/>
</native-data-source>

A CORRECT example is as follows:

<native-data-source 
   name="nativeDataSource"
   jndi-name="jdbc/nativeDS"
   description="Native DataSource"
   data-source-class="oracle.jdbc.pool.OracleDataSource"
   user="scott"
   password="tiger"

url="jdbc:oracle:thin:@(DESCRIPTION= 
   (LOAD_BALANCE=on) 
   (ADDRESS=(PROTOCOL=TCP)(HOST=host1) (PORT=1521)) 
   (ADDRESS=(PROTOCOL=TCP)(HOST=host2)(PORT=1521)) 
   (CONNECT_DATA=(SERVICE_NAME=service_name)))"> 

  <property name="connectionCacheName" value="ICC1"/>
  <property name="connectionCachingEnabled" value="true"/>
  <property name="fastConnectionFailoverEnabled" value="false"/>
</native-data-source>

5.9.3.2 Correction to the OEMS JMS Database Certification Matrix Table

In Table 3-8 OEMS JMS Database Certification Matrix, the last row of the table is not correct, it indicates that OEMS JMS Database 10.1.3 only certifies with DataBase v9.0.1.4, but does not certify with 10.x. In fact, OEMS JMS Database 10.1.3 does certify with 10.x.

The corrected table is as follows:

Table 5-2 OEMS JMS Database Certification Matrix

OracleAS / Oracle Database 9.0.1 9.0.1.3 9.0.1.4 9.2.0.1 9.2.0.2+ 10.1.0+ 10.2.0+

9.0.2

X

X


X




9.0.3



X



X


9.04



X


X



9.0.4.1






X


10.1.2



X


X

X


10.1.3



X


X

X

X


5.9.3.3 SQLServer Named Instance Definition Corrected

A SQL Server named instance defined outside of Java code, i.e., in data-sources.xml in OC4J, should have only one backward slash('\') separating the server name and the instance name.

This is incorrectly documented in the Data Sources chapter of the Oracle Containers for J2EE Services Guide.

Specifically, here's the change should be made to the documentation:

* Replace the text "myserver\\myinstance" with "myserver\myinstance" in section "4.9.2.2.4 DataDirect SQLServer" of the Data Sources chapter in the OC4J Services

Specifically, replace the text "myserver\\myinstance" with "myserver\myinstance" in the following examples in the Data Sources chapter:

  • SQLServer Managed Data Source

  • SQLServer Native Data Source

5.9.3.4 Correction to ORMI Tunneling URL

In the "Configuring ORMI Tunneling Through HTTP" section of Chapter 6, "Using Remote Method Invocation in OC4J", of the Oracle Containers for J2EE Services Guide, correct the following syntax specification:

Replace the INCORRECT syntax specification

ormi:http:// <hostname:[http_port]>/<context_uri>/<appName>

with the following CORRECT syntax specification:

ormi:http[s]://hostname[:http_port]>/<appName>

5.9.3.5 Missing Tables in Transaction Support Chapter

The tables are missing in the "OC4J Transaction Support Statistics" section of Chapter 5 - OC4J Transaction Support, of the 10.1.3.0 Oracle Containers for J2EE Services Guide.

This release note contains the text of the "OC4J Transaction Support Statistics" section with the tables restored.

OC4J Transaction Support Statistics

The statistics listed in the following table are provided by the JTAResource MBean, which is accessible through the Application Server Control Console.

Statistic Description
activeCount Total count of active transactions.

A consistently high value can indicate a heavy load on the server.

Suggest balancing across the cluster.

committedCount Total count of transactions that have committed.

This value can be used to determine the average load on the server since startup (or since the time the statistic was reset via admin). Similar to activeCount, a high value for this average can indicate a heavy load on the server.

Suggest load balancing.

rolledbackCount Total count of transactions that have rolled back.

A high value might indicate an issue in the system (such as a database down) resulting in performance degradation.

Examine the fine-grained rollback cause counts and logs for the cause of the rollbacks.

rolledbackDueToTimedOutCount Total count of transactions that have rolled back due to timeout.

A high number might indicate any of several issues causing the transaction (or activity within transactional bounds) to time out. Possibly the timeout value specified is not flexible enough.

Determine what activities within the transactions involved (which may be of a certain type/application) are taking up time or adjust the transaction-timeout value in the transaction-manager.xml configuration file.

rolledbackDueToAppCount Total count of transactions that have rolled back due to the application calling setRollbackOnly or rollback explicitly.

A high value can occur for any reason, but will most often occur due to some handled exception within an application (such as SQLException during database update).

Examine application code that calls setRollbackOnly or rollback to see why it is doing so.

rolledbackDueToResourceCount Total count of transactions that have rolled back due to and error in an enlisted resource.

A high value might indicate an issue with one or more resource managers (such as database) or with the network connection between OC4J and these resources.

Examine the OC4J and resource manager logs.

rolledbackDueToAdminCount Total count of transactions that have rolled back due to administrative action.

A high value suggests that the system or application may not be automated enough (such as too much system administration in general or inadequate transaction architecture handling). Or possibly a particular issue has occurred that required extensive administration.

Analyze logs for trends and contact those responsible for the administrative action.

rollbackExceptionCount Total count of RollbackExceptions encountered.

A high value might indicate an issue in the system (such as a database down) resulting in performance degradation. This might be caused by a direct internal system failure or by the application calling setRollbackOnly for some reason.

Examine the fine-grained rollback cause counts and logs for the cause of the rollbacks and look into application code that calls setRollbackOnly.

heuristicMixedExceptionCount Total count of HeuristicMixedExceptions encountered.

A high value might indicate a high number of potentially non-ACID outcomes resulting from inconsistent or inappropriate administrative intervention.

Analyze logs for trends and contact those responsible for the administrative action(s)

heuristicRollbackExceptionCount Total count of Heuristic Rollback Exceptions encountered.

A high value suggests that the system or application might not be automated enough (such as too much system administration in general or inadequate transaction architecture handling). Or possibly an issue has occurred that required extensive administration. Unlike the rolledbackDueToAdminCount, which indicates administrative rollback at the root transaction manager level while a transaction is active, this count indicates either a subordinate Transaction Manager or resource manager being administratively rolled back while in the prepared state.

Analyze the OC4J and resource manager logs for trends and contact those responsible for the administrative action.

securityExceptionCount Total count of SecurityExceptions encountered.

A high value and most often any value greater than 0 might indicate an issue with the identity on the thread executing this.

Examine the OC4J logs.

illegalStateExceptionCount Total count of IllegalStateExceptions encountered.

A high value here should be rare and only possible as a result of prior administrative intervention.

Analyze OC4J logs for trends and contact those responsible for the administrative action.

systemExceptionCount Total count of SystemExceptions encountered.

A high value here should never occur and indicates a serious failure in the system.

Analyze OC4J and resource manager logs.

heuristicCommittedCount Total count of heuristically committed transactions.

A high value suggests the system or application may not be automated enough (such as too much system administration in general or inadequate transaction architecture handling). Or possibly an issue has occurred that required extensive administration. This is due to a subordinate Transaction Manager and not a resource manager being administratively rolled back while in the prepared state.

Analyze OC4J logs for trends and contact those responsible for the administrative action.

heuristicRolledbackCount Total count of heuristically rolled back transactions.

A high value suggests the system or application may not be automated enough (such as too much system administration in general or inadequate transaction architecture handling). Or possibly an issues has occurred that required extensive administration. This is due to a subordinate Transaction Manager and not a resource manager being administratively rolled back while in the prepared state.

Analyze OC4J logs for trends and contact those responsible for the administrative action.

heuristicCount Total count of all heuristically rolled back and committed transactions.

See comments for heuristicCommittedCount and heuristicRolledbackCount.

averageCommitTime Average commit time of all transactions.

This is the average of the performTransaction values. However, this is a mean average so there may be spikes in the system indicating other issues as well.

Analyze the finer-grain statistics as well as log files for indication of system spikes. Also analyze overall architecture as necessary.

performTransaction Time from beginning to end of the transaction.

This is useful as a high-level indicator of performance issues. However, since it is a measure from the beginning to the end of the transaction only, anything that occurs within this time frame might be the cause of a large value here. Some possibilities are: application logic, database activity, jms activity, transaction processing, and so on.

Analyze finer-grain statistics and overall architecture as necessary.

singlePhaseCommitCompletion Time required for a single-phase commit completion.

A single-phase commit involves a single resource only and no 2PC costs (such as logging) are incurred. A large value here usually indicates an issue with the single resource being committed (such as network latency to the database).

Analyze the metrics of the resource involved in the commit.

twoPhaseCommitCompletion Time required for a two-phase commit completion.

A high value indicates delays in the prepare and commit calls on resource managers or the transaction record logging in OC4J.

Analyze the metrics of the resources involved in and performance settings for transaction record logging in OC4J in the transaction-manager.xml file.

transactionSuspended Time a transaction has been suspended.

A high value indicates that the transactions are being held in a suspended state waiting for a return call in a different or no transactional context (often from an EJB method call) or during propagation of a transaction context.

Analyze the application to determine what activity is taking place during the suspend or whether there is a network latency in the case of propagation.

rollbackCompletion Time required for a rollback completion.

A high value indicates delays in the rollback calls on resource managers which may be a result of network latency or resource manager issues.

Analyze the metrics of the resource(s) involved in the rollback.


The attributes listed in the following table are provided by the JTAResource MBean.

Attribute Description
inDoubtXids An array of in-doubt transaction Xids
activeXids An array of active transaction Xids
heuristicCommittedXids An array of heuristic committed transaction Xids
heuristicRolledbackXids An array of heuristic rolled back transaction Xids
currentTransactionDetail Details of all current transactions on the server, including those active, in-doubt, and recovering

The following JTAResource MBean operations are related to statistics.

Operation Description
clearStats Reset all OC4J Transaction Support statistics, except for activeCount, to 0
addThresholdEvent Add an event to be fired when the specified OC4J Transaction Count Statistic exceeds the specified threshold and again at the specified count intervals

addThresholdEvent takes the following parameters:

  • statName - The name of the Count Statistic to monitor

  • threshold1- The count at which to broadcast the event

  • repeatNotificationInterval - The interval count at which to broadcast subsequent events

removeThresholdEvent Remove a threshold event

removeThresholdEvent takes the following parameter:

  • statName - The name of the Count Statistic whose threshold event is to be removed


5.9.3.6 Packager Flag to Prevent Generation of Web Services Web Module

If you want to prevent OC4JPackager from creating and adding a Web service module to your application, which would expose your XQS views with WSDLvisibility set to "true" as Web service operations, specify the -no_ws flag when you run the packager, as follows:

% java -jar OC4JPackager.jar ... -no_ws

This is an optional, toggle flag. By default, a Web service module will be added.

5.9.3.7 Wrong Data Source Element Name

The "Defining Data Source" chapter in the OC4J Services Guide contains an error. The Fifth bullet in the "Configuration Notes" section is incorrect. The bullet should read:

"Native data sources are defined using the <native-data-source> element. The data-source-class attribute can be set to any fully qualified class name of an object that implements the javax.sql.DataSource interface."

5.9.3.8 Wrong Defaults Listed for Connection Pool Attributes

The Data Source chapter in the OC4J Services Guide contains an error. The Connection Pool Attributes table incorrectly lists default values for the time-to-live-timeout attribute and the abandoned-connection-timeout attribute. The default value for these features is actually 0 and not -1. The default value (0) indicates that these features are disabled.

5.9.3.9 Invalid Attribute

Table 5-3, "Connection Pool Attributes," includes a description of the disable-server-connection-pooling attribute. This attribute is no longer supported and should not be added to the J2EE_HOME/config/data-sources.xml configuration file.

5.9.4 Oracle Containers for J2EE Developer's Guide

This section describes errors in the Oracle Containers for J2EE Developer's Guide. It covers the following item(s):

5.9.4.1 Import Example Only for Thin JDBC Drivers

In Chapter 3 of the Oracle Containers for J2EE Developer's Guide, "Utilizing the OC4J Class Loading Framework," the example of importing an earlier version of the Oracle JDBC driver is only for thin JDBC drivers. This example does not apply to the Oracle Call Interface (OCI) drivers.

You can find it in the subsection "Example: Importing an Earlier Version of the Oracle JDBC Driver" under "Configuring an Application to Import a Nondefault Version of a Shared Library." The example shows how to configure an application to use an Oracle 9.2.0_5 JDBC driver, which is an earlier version of the Oracle JDBC driver than the version packaged with Oracle Containers for J2EE 10g Release 3 (10.1.3).

5.9.4.2 Default Session Timeout for OC4J Is 20 Minutes

In the Oracle® Containers for J2EE Developer's Guide 10g Release 3 (10.1.3), Chapter 8, J2EE Best Practices, under the heading "Always Invalidate Sessions When No Longer in Use", the default session timeout for OC4J is incorrectly identified as 30 minutes.

The correct default session timeout for OC4J is 20 minutes.

5.9.4.3 Correction to Example: Replacing the Oracle XML Parser with the Xerces Parser

The following typo exists in the published version of the 10.1.3.0.0 Oracle Containers for J2EE Developer's Guide:

The sample on page 3-9, at the end of the subsection "Example: Replacing the Oracle XML Parser with the Xerces Parser" is missing a closing quotation mark in

     max-version="2.5.0 

The sample code line should read as follows:

     <import-shared-library name="xerces.xml" max-version="2.5.0"/> 
 

5.9.4.4 Missing Character in Service URL Strings

In Oracle Containers for J2EE Developer's Guide, Chapter 5, "Creating MBeans to Manage Your Applications," under "Remote Management Using the Management EJB (JSR-77)," some of the service URL strings in the code segments are missing a required colon character (":"). The incorrect entries are like this one:

String url="service:jmx:rmi///opmn://opmnhost1.company.com:6003/home"

In this entry, ":" is missing between "rmi" and "///".

The correct service URL string follows:

String url="service:jmx:rmi:///opmn://opmnhost1.company.com:6003/home"

5.9.4.5 Incorrect Setting for Client Module in orion-application.xml

The description of the <client-module> element recommends the wrong value for the user attribute under "Elements in the orion-application.xml File" in Appendix A, "OC4J-Specific Deployment Descriptors." The descriptions of the auto-start and user attributes incorrectly recommend setting user to true when auto-start='true'.

These attribute settings, however, would prevent OC4J from calling the main method in an application client archive (CAR) at startup. When the auto-start attribute is set to true, you need to set user to anonymous. The descriptions of these <client-module> attributes should read as follows:

  • auto-start: Whether to automatically start the application in-process at OC4J server startup. The default is false. If this attribute is set to true, the user attribute must be set to anonymous.

  • user: Set to anonymous to run the client in-process. If the auto-start attribute is set to true, the user attribute must be set to anonymous.

5.9.5 Oracle Containers for J2EE Security Guide

This section describes errors in the Oracle Containers for J2EE Security Guide. It covers the following item(s):

5.9.5.1 Correct Package Name for getUserPrincipal() and getCallerPrincipal()

The OC4J Security Guide release for 10.1.3.0.0 specified an incorrect package name for the User class in its description of the getUserPrincipal() and getCallerPrincipal() methods. The package is com.evermind.security, not oracle.j2ee.security.

5.9.5.2 Obsolete <data-source> Element Cited

In the 10.1.3.1 Oracle Containers for J2EE Security Guide, in the section "Using Password Indirection" (Chapter 6), and in the 10.1.3.0.0 version of the same book, "Creating an Indirect Password" (Chapter 5), a passage refers to the password attribute of the <data-source> element in file data-sources.xml. This actually should refer to the password attribute of the <native-data-source> element or <managed-data-source> element, which combined to replace the <data-source> element in the 10.1.3.0.0 release.

5.9.5.3 Form Authentication Method Supported with Custom Login Modules

The Oracle Containers for J2EE Security Guide incorrectly states in at least two locations that the form authentication method is not supported with custom security providers (custom login modules). This is incorrect—in 10.1.3.x implementations, the form method is supported with custom security providers.

The error occurs in the following locations:

  • 10.1.3.0.0:

    • Chapter 2, "Overview of OC4J Security", section "Authentication in the OC4J Environment";

    • Chapter 13, "Web Application Security Configuration", section "Specifying auth-method in web.xml".

  • 10.1.3.1 and higher:

    • Chapter 2, "Java Platform Security", section "Web Application Standard Authentication Methods"

    • Chapter 17, "Web Application Security Configuration", section "Specifying auth-method in web.xml".

5.9.5.4 Invalid Reference to x509cert.mapping.attribute Property

The Oracle Containers for J2EE Security Guide incorrectly refers to the OracleAS JAAS provider property x509cert.mapping.attribute. In particular, Chapter 13, Web Application Security Configuration, in the section "Using Client-Cert Authentication" contains the following incorrect example:

<orion-application ... > 
... 
   <jazn provider="XML" ... default-realm="myrealm" ... > 
      <property name="x509cert.mapping.attribute" value="CN"/> 
... 
   </jazn> 
... 
</orion-application> 

This example and other references to x509cert.mapping.attribute are incorrect since the x509LoginModule utilizes the mapping.attribute property as do other providers. For more information about this property and how to configure it, see the release note at Section 5.1.28, "Specifying the Mapping Attribute".

5.9.6 Oracle Containers for J2EE Administration and Configuration Guide

This section describes documentation errata for the Oracle Containers for J2EE Configuration and Administration Guide. It includes the following topics:

5.9.6.1 Modification of the <log> Tag in system-application.xml for Log Rotation

In Oracle Containers for J2EE Configuration and Administration Guide, Chapter 1, "Introducing OC4J," under "Understanding the Application Hierarchy in OC4J" and "The System Application," the "Important" note states that you should not modify the system-application.xml file except for the <jazn> tag. You might also need to modify the <log> tag to rotate the system log file.

5.9.6.2 Incorrect Example for Disabling Text File Logging

In Oracle Containers for J2EE Configuration and Administration Guide, Chapter 10, "Logging in OC4J," under "Enabling/Disabling Text File Logging," the example for disabling text file logging comments out the entire <log> element, but the text before the example says to remove or comment out the <file> element. The incorrect example follows:

<!--
<log>
  <file path="application.log" />
</log>
-->

Here is a corrected example:

<log>
  <!-- <file path="application.log" /> -->
</log>

5.9.6.3 Format for Variables That Configure Text Logging for Web Sites

Information about the $cookie and $header variables is missing from the description of the format attribute of the <access-log> element under "Configuring Text-Based Access Logging" in Chapter 13, "Managing Web Sites in OC4J."

In the <access-log> subelement of the <web-site> element in a Web site's configuration file (*-web-site.xml), you can specify a number of variables in the format attribute, you can specify a number of variables that result in information being prepended to log entries. When you specify the $cookie or $header variable, the format needs to be as follows:

$cookie:[name] 
$header:[name]

5.9.6.4 Configuration of OPMN Gateway Element Shows Incorrect Order

The order of <topology> subelements is incorrect in the opmn.xml configuration example under "Configuring Cross-Topology Gateways" in Chapter 8, "Configuring and Managing Clusters," of Oracle Containers for J2EE Configuration and Administration Guide. The example shows a configuration for a gateway as follows:

<opmn>
 <notification-server> 
  <port ... /> 
  <ssl ... /> 
  <topology> 
   <gateway list="node1.com:6201&node2.com:6202&node3.com:6203/"/> 
   <discover list="*224.0.0.37:8205"/> 
  </topology> 
 </notification-server> 
 ... 
</opmn> 

Because the <topology> subelements are incorrectly ordered according to the opmn.xsd file, using this configuration results in an OPMN error.

The correct configuration follows:

<opmn>
 <notification-server>
  <port ... />
  <ssl ... />
  <topology>
   <discover list="*224.0.0.37:8205"/>
   <gateway list="node1.com:6201&node2.com:6202&node3.com:6203/"/>
  </topology>
 </notification-server>
 ...
</opmn>

5.9.6.5 Starting Order Incorrect for Static Peer-to-Peer Replication

The following paragraph shows an incorrect starting order for nodes under "Configuring Static Peer-to-Peer Replication" in Chapter 9, "Application Clustering in OC4J," of Oracle Containers for J2EE Configuration and Administration Guide.

In this configuration, each node specifies one other node as its peer. The result is that all of the nodes within the cluster are able to establish connections with one another. This scenario will work only if each node is started in succession; that is, www1.company.com must be started before www2.company.com. Otherwise, www2.company.com will not be able to "see" www1.company.com.

The following paragraph has the correct starting order.

In this configuration, each node specifies one other node as its peer. The result is that all of the nodes within the cluster are able to establish connections with one another. This scenario will work only if each node is started in succession; that is, www3.company.com must be started before www2.company.com. Otherwise, www2.company.com will not be able to "see" www3.company.com.

5.9.7 Oracle Containers for J2EE Deployment Guide

This section describes documentation errata for the Oracle Containers for J2EE Deployment Guide. It includes the following topics:

5.9.7.1 Update References to oracle-ant.jar to Be ant-oracle.jar

In Oracle Containers for J2EE Deployment Guide, Chapter 10, "Deploying with the OC4J Ant Tasks", under "Overview of the Ant Tasks", the ant-oracle.jar file is incorrectly referred to twice as the oracle-ant.jar file.

Correct the following sentences:

  • Incorrect:

    "The oracle-ant.jar file is installed by default within the ORACLE_HOME/ant/lib directory."

    Correct:

    "The ant-oracle.jar file is installed by default within the ORACLE_HOME/ant/lib directory."

    The location is correct.

  • Incorrect:

    "An XML file that you can import into the Ant build file (build.xml) using the Ant <import> task. This is necessary only if oracle-ant.jar is not installed in the ORACLE_HOME/ant/lib directory."

    Correct:

    "An XML file that you can import into the Ant build file (build.xml) using the Ant <import> task. This is necessary only if ant-oracle.jar is not installed in the ORACLE_HOME/ant/lib directory."

5.9.7.2 Information Missing from Description of admin_client.jar -redeploy Command Subswitches

Some information is missing from the description of the -redeploy command subswitches under "Redeploying an Archive" in Chapter 11, "Deploying with the admin_client.jar Utility":

  • The -file subswitch can specify the name of an EAR, WAR, or RAR, not just an EAR.

  • In the description of the -sequential subswitch, "EAR" should be "archive".

  • The -bindAllWebApps [webSiteName] subswitch is missing. This optional subswitch binds all Web modules to the specified Web site, or to the default Web site if none is specified.

    You can optionally supply a value for webSiteName, which is the name portion of the name_web-site.xml file that configures the Web site.

5.9.7.3 deploymentPlan Property Not Valid in Ant Task for WAR Deployment

The deploymentPlan property is incorrectly listed in Table 10-6, "deploy Properties for Standalone WAR Deployment" in Chapter 10, "Deploying with the OC4J Ant Tasks." You cannot use a deployment plan to deploy a standalone Web module.

5.10 Oracle Containers for J2EE Job Scheduler

This section describes issues associated with Oracle Containers for J2EE Containers for J2EE Job Scheduler. It includes the following topics:

5.10.1 Invalid Data Source Configuration May Result in Initialization Exception

In the JDBC persistence configuration, a null pointer exception results on container startup if the associated data source is improperly configured or the database server is not up.

There is no workaround for this issue; make sure the data sources are configured correctly and the target database is up.

5.10.2 Cancel API Is Not Transactional

If the Cancel API is invoked within a JTA transaction, all outstanding executions are canceled synchronously, not after the transaction is committed.

There is no workaround for this issue.

5.10.3 Lower Than Expected Throughput May Be Experienced for Large Number of Jobs

Lower than expected execution throughput may be observed when there are large burst jobs with concurrent schedules.

To work around this issue, disable the management bean and DMS statistics publication in order to increase throughput. This can be accomplished by setting the value of the following environment entries in the Job Scheduler configuration to false:

  • oracle.ias.scheduler.dms

  • oracle.ias.scheduler.jmx

5.10.4 Removing a Job May Impact Job Scheduler Event Listener Processing

Removing a job in the JMS persistence configuration may result in event processing delays. This behavior is exacerbated in a deployment where jobs are created and removed with high frequency.

To work around this issue, disable the management bean and DMS statistics publication in order to increase throughput. This can be accomplished by setting the value of the following environment entries in the Job Scheduler configuration to false:

  • oracle.ias.scheduler.dms

  • oracle.ias.scheduler.jmx

5.10.5 Peremptory Shutdown of OC4J Container May Prevent Subsequent Restart

The JMS server creates recover lock files in the $ORACLE_HOME/j2ee/home/persistence directory. As a result of a peremptory shutdown, these files may not be properly cleaned up and may prevent the container from restarting. Refer to the JMS release notes for more information.

This issue is only pertinent to Job Scheduler running in a JMS persistence environment.