Associating TopLink With an Oracle JDBC Driver

In this release, by default, TopLink is associated with Oracle JDBC driver version 10.2 (ojdbc14_102.jar).

If this Oracle JDBC driver version is not appropriate for the Oracle Database version you need to use, you can associate TopLink with another Oracle JDBC driver version.

How you associate TopLink with another version of Oracle JDBC driver depends on the type of application you are building:

EJB 3.0 and EJB 2.1 non-CMP Applications
EJB 2.1 CMP Applications
EIS AQ Connector Applications

For more information, see "Utilizing the OC4J Class Loading Framework" in the Oracle Containers for J2EE Developer's Guide.

EJB 3.0 and EJB 2.1 non-CMP Applications

For EJB 3.0 and EJB 2.1 non-CMP applications, note the following restrictions:

You may use multiple versions of Oracle JDBC driver simultaneously on the server, but each application may use only a single version.
For each oracle.jdbc shared library version, you must define a corresponding version of oracle.toplink shared library in server.xml.
You may use only Oc4jPlatform; you cannot use Oc4jPlatform_10_1_3.
If the version of imported shared library is not provided, then the one with the highest version is imported. For example, if oracle.jdbc version 10.2 defined in server.xml and system-application.xml imports oracle.jdbc without version, then oracle.toplink will use oracle.jdbc version 10.2.

To associate an EJB 3.0 or EJB 2.1 non-CMP application with a specific version of Oracle JDBC driver other than the default, do the following:

Create a folder in <ORACLE_HOME>/j2ee/home/shared-lib/oracle.jdbc for the new Oracle JDBC driver shared library.

In this example, you would create folder <ORACLE_HOME>/j2ee/home/shared-lib/oracle.jdbc/10.3.

When you reference the actual Oracle JDBC driver JAR file, you do so relative to this directory. You can either put the Oracle JDBC driver JAR file in this directory and simply reference the JAR file by name, or put it in some other directory and reference the JAR file with a partial path relative to this directory.
Define the new Oracle JDBC driver shared library in server.xml, as Example 20-3 shows.
Example 20-3 Defining a Shared Library for Oracle JDBC Driver Version 10.3 in server.xml
```
...
<shared-library name="oracle.jdbc" version="10.3">
    <code-source path="ojdbc14_103.jar"/>
</shared-library>
...
```
Use the oracle.jdbc shared library name with a different version number that corresponds to the version of Oracle JDBC driver you want to use: in this example, 10.3.

In this example, the code-source attribute path is just ojdbc14_103.jar: this assumes that you put the JAR file in <ORACLE_HOME>/j2ee/home/shared-lib/oracle.jdbc/10.3. Alternatively, you could set path to a partial path relative to the <ORACLE_HOME>/j2ee/home/shared-lib/oracle.jdbc/10.3 directory.
Define a corresponding TopLink shared library in server.xml, as Example 20-4 shows.
Example 20-4 Defining a Corresponding oracle.toplink Shared Library for Oracle JDBC Driver Version 10.3 in server.xml
```
...
<shared-library name="oracle.jdbc" version="10.3">
    <code-source path="ojdbc14_103.jar"/>
</shared-library>
<shared-library name="oracle.toplink" version="10.3" library-compatible="true">
    <code-source path="../../../../../toplink/jlib/toplink.jar"/>
    <code-source path="../../../../../toplink/jlib/antlr.jar"/>
    <code-source path="../../../../../toplink/jlib/cciblackbox-tx.jar"/>
    <import-shared-library name="oc4j.internal"/>
    <import-shared-library name="oracle.xml"/>
    <import-shared-library name="oracle.jdbc" max-version="10.3"/>
    <import-shared-library name="oracle.dms"/>
</shared-library>
...
```
Use the oracle.toplink shared library name with a different version number that corresponds to the version of Oracle JDBC driver you want to use: in this example, 10.3. In this oracle.toplink shared library, be sure to import the desired version of oracle.jdbc shared library: in this example, max-version="10.3".

Note:
If your new oracle.toplink library uses the same JAR files as the original and you created it simply to specify another version of oracle.jdbc, then to avoid having to create a corresponding folder under <ORACLE_HOME>/j2ee/home/shared-lib for this library, set its shared-library attribute library-compatible to true, as Example 20-4 shows.

Import your new shared libraries for your application by doing the following:

To make the new oracle.jdbc and oracle.toplink shared libraries the default for all applications in your OC4J instance, update the system-applications.xml, as Example 20-5 shows.

Example 20-5 Importing the Shared Libraries for all Applications in system-applications.xml

...
    <imported-shared-libraries>
...
        <import-shared-library name="oracle.jdbc" min-version="10.3" max-version="10.3"/>
        <import-shared-library name="oracle.toplink" min-version="10.3" max-version="10.3"/>
...
    </imported-shared-libraries>
...

To make the new oracle.jdbc and oracle.toplink shared libraries applicable to only a certain application, update that application's orion-applications.xml, as Example 20-6 shows.

In this case, you should define datasources in a data-sources.xml file located in the same folder as the orion-applications.xml file and referenced in the orion-applications.xml file as Example 20-6 shows.

Example 20-6 Importing the Shared Libraries for a Specific Application in orion-applications.xml

...
<orion-application>
    <ejb-module remote="true" path="simpleobject_ejb.jar" />
    <client-module path="simpleobject_ejb.jar" auto-start="false" />
    <persistence path="persistence" />
    <imported-shared-libraries>
        <import-shared-library name="oracle.jdbc" max-version="10.3"/>
        <import-shared-library name="oracle.toplink" max-version="10.3"/>
    </imported-shared-libraries>
    <log>
        <file path="application.log" />
    </log>
    <data-sources path="data-sources.xml" />
    <namespace-access>
        ..........
    </namespace-access>
</orion-application>

EJB 2.1 CMP Applications

For EJB 2.1 CMP applications, note the following restrictions:

You cannot use more than one Oracle JDBC driver version with TopLink.
If the version of imported shared library is not provided, then the original version is used. For example, if oracle.jdbc version 10.2 is defined in server.xml and system-application.xml imports oracle.jdbc without version, then oracle.toplink uses original oracle.jdbc version 10.1.
In this case, the TopLink run-time may use any oracle.toplink.platform.server.oc4j platform instance. For more information, see "Customizing the TopLink EJB 2.1 Persistence Manager".

EIS AQ Connector Applications

To associate an application that uses the EIS AQ connector with a specific version of Oracle JDBC driver other than the default, follow the procedure for "EJB 3.0 and EJB 2.1 non-CMP Applications".

In this case, in your new oracle.jdbc shared library, you must also reload the aqapi.jar file, as Example 20-7 shows.

Example 20-7 Defining a Shared Library for Oracle JDBC Driver Version 10.3 in server.xml

...
<shared-library name="oracle.jdbc" version="10.3">
    <code-source path="ojdbc14_103.jar"/>
    <code-source path="../../../../../rdbms/jlib/aqapi.jar"/>
</shared-library>
...