Skip Headers

Oracle9iAS Containers for J2EE Release Notes
Release 2 (9.0.2) for Windows

Part Number A97646-01
Go To Documentation Library
Home

Oracle9iAS Containers for J2EE

Release Notes

Release 2 (9.0.2) for Windows

May 2002

Part No. A97646-01

This document summarizes the differences between Oracle9iAS Containers for J2EE (OC4J) and its documented functionality. It covers the following topics:

1 Release Notes for J2EE Connector Architecture

This section includes issues with J2EE Connector Architecture that are not reflected in the Oracle9iAS 9.0.2 documentation.

1.1 IllegalArgumentException

A bug causes an IllegalArgumentException; an example is:

java.lang.IllegalArgumentException: No such property: ConnectionURL, existing writable properties are: [logWriter, connectionURL]

Such an exception may occur if the resource adapter deployment descriptor specifies any configuration property whose <config-property> element name attribute setting begins with a capital letter when the second character is not a capital. This includes the standard properties defined in section 10.4.3 in Sun Microsystems' J2EE Platform Connector Architecture 1.0 Specifications, such as ConnectionURL. This is in conflict with sections 8.3.1 and 8.8 of Sun's JavaBeans 1.01 Specifications, which states that a JavaBean with methods setConnectionURL() and getConnectionURL() should have a property name connectionURL, not ConnectionURL.

1.1.1 Workaround

The workaround here is to change the <config-property> element name attribute setting in the resource adapter's ra.xml file from ConnectionURL to connectionURL. The ra.xml file is found in the

%J2EE_HOME%\connectors\connector-name\rar-file-name\
META-INF

directory if the resource adapter is deployed standalone, or

%J2EE_HOME%\applications\app-name\rar-file-name\META-INF

directory if the resource adapter is packaged within an EAR file. (%J2EE_HOME% is %ORACLE_HOME%\j2ee\home.) If the resource adapter has been deployed, also change the value of the name setting in the <config-property> element in the generated oc4j-ra.xml file under the application-deployment directory. For example, change the following <config-property> element from:

<config-property name="ConnectionURL" value="jdbc:cloudscape:rmi:CloudscapeDB;create=true"/>

to:

<config-property name="connectionURL" value="jdbc:cloudscape:rmi:CloudscapeDB;create=true"/>

and restart OC4J.

1.2 deployconnector Switch Not Available in this Release

The -deployconnector switch in the admin command line tool (admin.jar) documented in Oracle9iAS Containers for J2EE Services Guide is not available for deploying standalone resource adapters.

1.2.1 Workaround

Standalone resource adapters can be deployed manually. Follow these steps:

  1. Create a new directory under the %J2EE_HOME%\connectors directory.

  2. Copy the resource adapter RAR file into the new directory.

  3. Add the following to the %J2EE_HOME%\config\oc4j-connectors.xml file:

    <connector name="your_resource_adapter_name" path="your_resource_adapter.rar"> </connector>
    
  4. In the %J2EE_HOME%\config\server.xml file, make sure that the connector-directory attribute is specified in the <application-server> element as follows:

    <application-server
       application-directory="..\applications"
       deployment-directory="..\application-deployments"
       connector-directory="..\connectors">
    

    In the %J2EE_HOME%\config\application.xml file, if there is no <connectors> element under <orion-application> that looks like this, add it:

    <connectors path=".\oc4j-connectors.xml"/>
    

    In these first four steps, you have deployed the standalone resource adapter to OC4J.

  5. Start or restart OC4J process. OC4J will automatically unpack your RAR file in the

    %J2EE_HOME%\connectors\your-directory-name\your-resource-adapter-name\

    directory.

    In step 5, OC4J created a directory called your_resource_adapter_name in %J2EE_HOME%\application-deployments\default\ when you started the OC4J process.

  6. Configure the oc4j-ra.xml file under the

    %J2EE_HOME%\application-deployments\default\your_resource_adapter_name

    directory with the desired connector property settings, each with its distinct JNDI name for look-up from application components, and, optionally, with different configuration property values. Here is an example of an oc4j-ra.xml file:

    <oc4j-connector-factories>
     <connector-factory location="eis/eisJNDIforCloudscape"
       connector-name="BlackBoxNoTx">
         <config-property name="connectionURL"
             value="jdbc:cloudscape:rmi:CloudscapeDB;create=true"/>
     </connector-factory>
     <connector-factory location="eis/eisJNDIforOracle"
       connector-name="BlackBoxNoTx">
         <config-property name="connectionURL"
           value="jdbc:oracle:thin:@localhost:1521:orcl"/>
     </connector-factory>
    </oc4j-connector-factories>
    

Restart the OC4J process again for the configuration to take effect.

1.3 native-library Element Problem

The <native-library> element under <connector> in oc4j-connectors.xml does not work.

1.3.1 Workaround

Copy the native libraries, such as .so or .dll files, if any, to the top-level directory in which the resource adapter files are expanded when your application is deployed into OC4J. For example, suppose a standalone resource adapter named myRAfile.rar is deployed into the

%J2EE_HOME%\connectors\myRAname

directory. The top-level directory would be

%J2EE_HOME%\connectors\myRAname\myRAfile

Copy any native libraries that are packaged within that RAR file to this directory.

2 Release Notes for Oracle9iAS EJB Container

This section includes issues with EJB that are not reflected in the Oracle9iAS 9.0.2 documentation.

3 Release Notes for Oracle SQLJ

This section includes issues with SQLJ that are not reflected in the Oracle9iAS 9.0.2 documentation.

4 Release Notes for Oracle JDBC

This section includes issues with JDBC that are not reflected in the Oracle9iAS Release 2 (9.0.2) documentation.

The JDBC drivers shipped with this Oracle9iAS version have known problems. A JDBC patch addresses the problems. The patch is accompanied by a release note, which includes a list of known problems. Follow the instructions in the Oracle9i Application Server Installation Guide to install the necessary patches before you run Oracle9iAS.

5 Release Notes for Oracle9iAS Servlet Container

This section includes issues with servlets that are not reflected in the Oracle9iAS 9.0.2 documentation.

5.1 Unexpected Delay Instantiating java.security.SecureRandom

For security reasons, OC4J uses the class java.security.SecureRandom for secure seed generation. Session-based requests use this facility. Unfortunately, the amount of time required for the first instantiation to complete can be unacceptable, depending upon your application needs. Since OC4J makes this call lazily, it can cause an unexpected delay when it is first called during the course of application execution. If this occurs, one solution is for an application to enable the load-on-startup attribute in the <web-site> element of the web-site.xml configuration file and to create an instance of SecureRandom during the class initialization of the application. The result will be a longer startup time in place of a delay during the course of servicing clients.

5.2 Sharing Cached Objects in an OC4J Servlet

To take advantage of the Java cache's distributed functionality or to share a cached object between servlets, some minor modification to an application's deployment may be necessary. Any user-defined objects that will be shared between servlets or distributed between JVMs must be loaded by the system class loader. By default, objects loaded by a servlet are loaded by the context class loader. These objects are visible to only the servlets within the context that loaded them. The object definition is not available to other servlets or to the cache in another JVM. If the object is loaded by the system class loader, the object definition will be available to other servlets and to the cache on other JVMs.

With JServ, this was accomplished by including the cached object in the classpath definition available when the JServ process was started.

With OC4J, the system classpath is derived from the manifest of the oc4j.jar file and any associated jar files, including cache.jar. The classpath in the environment is ignored. To include a cached object in the classpath for OC4J, the class file should be copied to %ORACLE_HOME%\javacache\sharedobjects\classes or added to the jar file %ORACLE_HOME%\javacache\cachedobjects\share.jar. Both the classes directory and the share.jar file have been included in the manifest for cache.jar.

6 Release Notes for Oracle9iAS JSP Container

This section includes issues with JSP that are not reflected in the Oracle9iAS 9.0.2 documentation.


Note:

Starting with Oracle9iAS 9.0.2, components that ship with Oracle9iAS use the same version numbering. The major change in the Oracle9iAS JSP (OJSP) container in release 9.0.2.0 is better integration with the other Oracle9iAS containers for J2EE. 



Note:

OJSP demos are located in ojspdemos.ear in the J2EE demo instance of a regular Oracle9iAS 9.0 installation. They are not available with the oc4j\j2ee basic OTN download. 


6.1 General Notes

6.2 Security Considerations

Follow these security practices:

6.3 Known Issues and Restrictions

7 Release Notes for JAAS

This section includes issues with JAAS that are not reflected in the Oracle9iAS 9.0.2 documentation.


Note:

Some class and component names contain the word "JAZN," which is the internal code name for "JAAS provider." 


7.1 Admintool Changes

The JAZN Admintool now enforces authentication and authorization for most of the JAZN commands, including the JAZN shell. There are two ways to specify the user name and password for authentication purposes:

7.2 Updating OC4J Admin Password Using JAAS Administration Tool

Perform the following steps to update the OC4J admin password using the JAAS administration tool:

  1. Make sure that your ORACLE_HOME environment variable is set and you are using the correct java from the %ORACLE_HOME%\jdk\bin directory.

  2. In the %ORACLE_HOME%\j2ee\home directory, use the following command to change the admin password to the ias_admin password:

    java -Doracle.security.jazn.config=
    %ORACLE_HOME%\j2ee\home\jazn\install\jazn.xml -jar jazn.jar
     -setpasswd jazn.com admin welcome welcome1
    

    In this example, the ias_admin password is welcome1.

  3. Verify the change by performing the following:

    java -Doracle.security.jazn.config=%ORACLE_HOME%\j2ee\home\jazn\install\jazn.xml
    -jar jazn.jar -checkpasswd jazn.com admin -pw welcome1
    

    You should see the following message:

    Successful verification of user/password pair
    

    The affected jazn-data.xml file is located in the %ORACLE_HOME%\j2ee\home\config directory.

7.3 JAZNUserManager Delegation Support

JAZNUserManager now supports the OC4J "user manager delegation" model. If a user or group is not found at the application level JAZNUserManager instance, it delegates the request to the global user manager.

A known limitation is that delegation between principals.xml, which is the storage for XMLUserManager) and JAZNUserManager is not supported. For example, a configuration that sets principals.xml as the global user manager and JAZNUserManager as the application level user manager is not supported. (JAZNUserManager is the implementation class; it can be configured to use an XML file, jazn-data.xml, as storage or OID as storage.) This feature should be distinguished from the "identity delegation" feature discussed in the Oracle9iAS Containers for J2EE Services Guide. The "identity delegation" feature refers to the fact that when a servlet calls an enterprise bean on behalf of a client's request, the primary caller's identity is propagated to the enterprise bean for authorization purposes.

7.4 JAAS Clustering Support

JAZN-XML is integrated with DCM/SMI (System Management Interface, an API that EM uses to manage OC4J and OC4J applications) to provide cluster support. Any changes to jazn-data.xml via EM will be automatically propagated to all nodes participating in the same cluster.

However, be aware that any modification of jazn-data.xml will not be instantly picked up by the running OC4J instances. An OC4J instance needs to be restarted for the changes to take effect.

7.5 OC4J Services Guide, Chapter 5

The description regarding our demo application, callerInfo, is out of date. Refer to the file README.txt located at %ORACLE_HOME%\j2ee\home\jazn\demo\callerInfo for a more up-to-date description of this JAAS demo.

7.6 JAAS and Java 2 Security

Oracle9iAS 9.0.2 does not support using the JAAS provider as the J2SE policy (the Java 2 security policy) provider. For code-based security, we recommend using the J2SE 1.3.1 reference implementation. We provide a J2SE policy file that works with the J2SE 1.3.1 reference implementation. This file is located at %J2EE_HOME%\config\java2.policy.

7.6.1 How to Enable an Application with Java 2 Security

To enable an application with Java 2 security, do one of the following:

7.6.2 How to Enable OC4J with Java 2 Security

OPMN (Oracle Process Management Notification) supports specification of Java options in opmn.xml. The following opmn.xml fragment illustrates how to enable OC4J for Java 2 security in an ADE view:

<oc4j instanceName="home" numProcs="1" maxRetry="3">
   <config-file path=
     "c:\ade\rkng_oc4j902\oracle\j2ee\home\config\server.xml" />
   <java-bin path="c:\jdk1.3.1\bin\java" />
   <java-option
     value="-Djava.security.manager
                -Djava.security.policy=
             \c:\ade\rkng_oc4j902\j2ee\home\config\java2.policy" />
   <port ajp="0"/>
...
</oc4j>

To start up OC4J in standalone mode, specify the relevant system properties before the -jar option. For example:

java -Djava.security.manager
     -Djava.security.policy=%ORACLE_HOME%\j2ee\home\config\java2.policy
     -Doracle.home=%ORACLE_HOME% -jar oc4j.jar

At the minimum, the following system properties must be set:

Table 1 System Properties
Property Name  Description 

java.security.manager 

property to enable Java 2 security in this JVM 

java.security.policy 

location of your java2.policy (the default policy is located at %ORACLE_HOME%\j2ee\home\config\java2.policy

oracle.home 

value of %ORACLE_HOME% 

7.7 JAAS Login Module Configuration Provider

The JAZN-XML provider type of JAAS is also a JAAS login module configuration provider.

This subsection documents JAAS login module support.

7.7.1 Configure JAAS

7.7.1.1 Configure JVM

Add the following lines to your java.security configuration file, if not present already:

auth.policy.provider=oracle.security.jazn.spi.PolicyProvider
login.configuration.provider=oracle.security.jazn.spi.
LoginConfigProvider

This indicates that JAAS is to be used as the provider for JAAS login configuration as well as policy. This is the default configuration for the JDK shipped with Oracle9iAS release 2.

The java.security file is located in the %JAVA_HOME%\jre\lib\security directory.

7.7.1.2 Configure JAAS

Configure your jazn.xml file to use JAZN-XML as the provider:

For example, consider this simple jazn.xml file:

<jazn provider="XML" location="jazn-data.xml" />

This informs JAAS that JAZN-XML is the provider of choice (as opposed to JAZN-LDAP, which does not yet support login module configuration).

You must also configure jazn-data.xml properly for login module configuration. You can accomplish that by invoking the oracle.security.jazn.login.LoginModuleManager API or editing jazn-data.xml manually.

Here is a sample fragment of jazn-data.xml that configures a login module for an application:

<!-- Login Module Data -->
<jazn-loginconfig>
      <application>
            <name>JAZNUserManager</name>
            <login-modules>
                  <login-module>
                    <class>oracle.security.
                       jazn.realm.RealmLoginModule</class>
                     <control-flag>required</control-flag>
                        <options>
                             <option>
                                 <name>addRoles</name>
                                 <value>true</value>
                             </option>
                        </options>
                  </login-module>
            </login-modules>
      </application>
</jazn-loginconfig>

The preceding fragment specifies that for the application JAZNUserManager, the login module RealmLoginModule is a required component in the authentication process, with the addRoles option set to true.

For more information about JAAS and JAAS login modules, refer to the JAAS Web site (http://java.sun.com/products/jaas/).

7.7.1.3 Start up JVM with JAAS Enabled

Since JAAS is based on Java 2 security, you must first enable the Java 2 security manager according to Section 7.6, "JAAS and Java 2 Security".

In addition to the system properties related to Java 2, the following property must be set:

Table 2 Security Properties
Property Name  Description 

oracle.security.jazn.config 

The location of your jazn.xml configuration file. The default location for this file: %ORACLE_HOME%\j2ee\home\config\jazn.xml 

For example, the following script (a command consisting of one continuous line) starts up OC4J with Java 2 and JAAS enabled, in an ADE view:

%JAVA_HOME%\bin\java -Djava.security.manager
  -Djava.security.policy=%J2EE_HOME%\config\java2.policy
  -Doracle.home=%ADE_VIEW_ROOT%
  -Doracle.security.jazn.config=%J2EE_HOME%\config\jazn.xml
  -jar oc4j.jar

This feature is not supported by JAZN-LDAP in release 9.0.2.

7.8 Default Realm Should Be Specified if User Repository Has Multiple Realms

When the user repository (either the XML-based file or OID, that is, LDAP-based Oracle Internet Directory), has multiple realms, the default realm should be specified in the jazn.xml file. For example, if you are using JAZN-XML, and your default realm is called jazn.com, your jazn.xml file would consist of the following:

<jazn provider="XML"
        default-realm="jazn.com"
        location=".\jazn-data.xml" />

If you are using JAZN-LDAP, the location would be the URL for the OID server, as, for example:

<jazn provider="LDAP"
      default-realm="jazn.com"
      location="ldap://oid.us.oracle.com:389" />

Furthermore, the jazn tag in %ORACLE_HOME%\j2ee\home\config\application.xml must also specify the default realm if there is more than one.


Note:

In the JAAS context, a realm refers to a user community. This is a namespace for users and roles. When there are multiple realms in the user repository, the default realm must be specified, so that JAAS knows the default namespace in which to look up users and roles.  


7.9 Updated Information for the Default jazn.xml File Location

The default jazn.xml file is located in this directory: %ORACLE_HOME%\j2ee\home\config. The jazn.xml file found in %ORACLE_HOME%\j2ee\home\jazn\config is a private copy used by the Oracle Universal Installer.

7.10 JAAS Demo Data Needs to Be Loaded into LDAP if JAZN-LDAP Is Global User Manager

If the user manager for the default application for an OC4J instance is changed to JAZN-LDAP, the JAAS demo data needs to be loaded into the specified LDAP database. (This is documented in the README file in the %ORACLE_HOME%\j2ee\home\jazn\install directory.) Additionally, the default @ realm needs to be specified as jazn.com.

If the preceding is not done, deployment of the demos through EM or dcmctl will fail with an error when looking up java:comp/ServerAdministrator.

8 Release Notes for OC4J Administration and Management

In an Oracle9iAS environment, the tools and steps used to manage OC4J processes and modify XML configuration files are not the same as for a standalone OC4J environment. This is a change from the Oracle9iAS 1.0.2.2 release.

In particular, in an Oracle9iAS environment you can no longer do the following:

In Oracle9iAS, two Oracle tools--Oracle Enterprise Manager and the command-line dcmctl tool--are used to start, stop, and configure OC4J.

You must run the dcmctl tool appropriately after any manual modifications to XML configuration files.

Refer to the Oracle9iAS Containers for J2EE User's Guide for additional information. (There are separate versions of this document for Oracle9iAS and OC4J standalone. The standalone version is available through OTN.)

9 Release Notes for MERANT DataDirect Connect JDBC Driver

A customized version of the MERANT DataDirect Connect JDBC driver is shipped with Oracle9iAS, Release 2 (9.0.2) to provide connectivity to non-Oracle databases. Refer to standard MERANT documentation and release notes for technical information on the MERANT JDBC driver. In addition, be aware of the following differences between the standard MERANT JDBC driver and this customized version:

10 Document Errata

This section describes material that is wrong or missing from the documentation.

10.1 XML-Based JAAS Demo README.TXT Refers to a Nonexistent README

The file README.txt in the following directory:

%ORACLE_HOME%\j2ee\home\jazn\demo\callerInfo

has a reference to the file %ORACLE_HOME%\dcm\README, which does not exist. Instead, from a core install, go to the following page for a link to the JAAS Readme file:

http://servername/J2EE.htm

10.2 Incorrect Documentation of File Locations for xmlparserv2.jar, xsu12.jar, and JSP Tag Library Descriptor Files

The release 9.0.2 versions of the Oracle9iAS Containers for J2EE User's Guide, Oracle9iAS Containers for J2EE Support for JavaServer Pages Reference, and Oracle9iAS Containers for J2EE JSP Tag Libraries and Utilities Reference contain inaccuracies or incomplete information regarding file locations. The files involved are xmlparserv2.jar, xsu12.jar, and the JSP tag library descriptor (TLD) files.

In Oracle9iAS Release 2 (9.0.2), note the following:

10.3 Issue in the Oracle9iAS Containers for J2EE Services Guide

Here is a known issue in the Oracle9iAS Containers for J2EE Services Guide:

Oracle is a registered trademark, and Oracle9i is a trademark or registered trademark of Oracle Corporation. Other names may be trademarks of their respective owners.

Copyright © 2002 Oracle Corporation.

All Rights Reserved.


Oracle
Copyright © 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Home