B Oracle ADF Problems and Solutions

This appendix describes common problems and solutions. It contains the following topics:

Section B.1, "Oracle ADF Runtime Installer Fails With Error"
Section B.2, "Previously Working Application Using ADF Business Components Starts Throwing JDBC Errors"
Section B.3, "Changes to ADF Business Components Parameters Have No Effect"
Section B.4, "ADF Business Components Throw ClassNotFoundException"
Section B.5, "ADF Business Components Deployed with Libraries Throw Exceptions"

B.1 Oracle ADF Runtime Installer Fails With Error

When using the Oracle ADF Runtime Installer in JDeveloper 9.0.5.x from a remote machine to upgrade the Oracle ADF libraries on Oracle Application Server, you may receive the error The selection is not an Oracle Application Server home directory. in the ADF Runtime Installer wizard.

Problem

Before you deploy and run your application, you must ensure that the ADF runtime libraries that reside on the target Oracle Application Server installation are the same version, or later, as the libraries that were used to develop the application in JDeveloper. While you attempt to run the ADF Runtime Installer, the ADF runtime libraries are not available on the same machine as the target Oracle Application Server installation. In this release, the ADF Runtime Installer is designed to run on the same machine as the target Oracle Application Server installation. In order to run the ADF Runtime Installer, you must be able to obtain the libraries from the correct JDeveloper installation.

Before performing any updates, verify that your application server is supported by JDeveloper 9.0.5. See the chart provided in the document at this link:

http://www.oracle.com/technology/products/jdev/collateral/papers/10g/as_supportmatrix.html.

Solution 1

Install JDeveloper on the same machine as the target Oracle Application Server installation and rerun the ADF Runtime Installer. In this case, because JDeveloper resides on the same machine as the Oracle Application Server installation, the ADF Runtime Installer can find Oracle Home and will automatically locate the ADF runtime libraries from JDeveloper.

It is important that the ADF runtime libraries that reside on the target Oracle Application Server installation are the same version, or later, as the libraries that were used to develop the application in JDeveloper. Be sure to install any maintenance releases of JDeveloper before you upgrade the target environment libraries.

Solution 2

Install JDeveloper on any machine, and then move the required ADF runtime libraries to the target Oracle Application Server machine.

It is important that the ADF runtime libraries that reside on the target Oracle Application Server installation be the same version, or later, as the libraries that were used to develop the application in JDeveloper. Be sure to install any maintenance releases of JDeveloper before you upgrade the target environment libraries.

Note:

This solution does not rely on the ADF Runtime Installer. Instead use the following list of runtime libraries to update the application server.

Before you install the ADF runtime libraries:

Optionally, create a backup directory of each directory that you plan to update (see the list below).
Stop all OC4J instances, including the Enterprise Manager instance. Only after completing the installation should you restart the server.
If your application works with TopLink mapping objects, you must edit the <oracle_home>/j2ee/home/config/application.xml file to include the following library paths:
```
<library path="../../../jlib/ojmisc.jar" />
<library path="../../../toplink/jlib/toplink.jar" />
<library path="../../../toplink/jlib/antrl.jar" />
```

Only TopLink users must edit the application.xml file on the server; the other supported business services do not require this modification.

After you have completed the above steps, you must remove these four files from the existing Oracle Application Server installation in the OC4J root directory:

<ORACLE_Home>/BC4J/lib/datatags.jar
<ORACLE_Home>/BC4J/lib/bc4juixtags.jar
<ORACLE_Home>/BC4J/lib/bc4jhtml.jar
<ORACLE_Home>/BC4J/lib/bc4j_jclient_common.jar

Then you can copy the files shown in the following tables from the JDeveloper source location to the OC4J root directory.

Copy these ADF runtime libraries:

From JDeveloper	To Server
`<jdev_home>/BC4J/lib/adfm.jar`	`<oracle_home>/BC4J/lib/adfm.jar`
`<jdev_home>/BC4J/lib/adfmweb.jar`	`<oracle_home>/BC4J/lib/adfmweb.jar`
`<jdev_home>/BC4J/lib/bc4jct.jar`	`<oracle_home>/BC4J/lib/bc4jct.jar`
`<jdev_home>/BC4J/lib/bc4jctejb.jar`	`<oracle_home>/BC4J/lib/bc4jctejb.jar`
`<jdev_home>/BC4J/lib/bc4jdomorcl.jar`	`<oracle_home>/BC4J/lib/bc4jdomorcl.jar`
`<jdev_home>/BC4J/lib/bc4jimdomains.jar`	`<oracle_home>/BC4J/lib/bc4jimdomains.jar`
`<jdev_home>/BC4J/lib/bc4jmt.jar`	`<oracle_home>/BC4J/lib/bc4jmt.jar`
`<jdev_home>/BC4J/lib/bc4jmtejb.jar`	`<oracle_home>/BC4J/lib/bc4jmtejb.jar`
`<jdev_home>/BC4J/jlib/adfjclient.jar`	`<oracle_home>/BC4J/jlib/adfjclient.jar`
`<jdev_home>/BC4J/lib/collections.jar`	`<oracle_home>/BC4J/lib/collections.jar`
`<jdev_home>/BC4J/jlib/bc4jdomgnrc.jar`	`<oracle_home>/BC4J/jlib/bc4jdomgnrc.jar`
`<jdev_home>/jlib/jdev-cm.jar`	`<oracle_home>/jlib/jdev-cm.jar`
`<jdev_home>/BC4J/lib/adfmtl.jar`	`<oracle_home>/BC4J/lib/adfmtl.jar`

Copy this OJMisc runtime library:

From JDeveloper	To Server
`<jdev_home>/jlib/ojmisc.jar`	`<oracle_home>/jlib/ojmisc.jar`

Install these interMedia Runtime Libraries:

From JDeveloper	To Server
`<jdev_home>/ord/jlib/ordhttp.jar`	`<oracle_home>/ord/jlib/ordhttp.jar`
`<jdev_home>/ord/jlib/ordim.jar`	`<oracle_home>/ord/jlib/ordim.jar`

Copy these TopLink runtime libraries:

From JDeveloper	To Server
`<jdev_home>/toplink/jlib/toplink.jar`	`<oracle_home>/toplink/jlib/toplink.jar`
`<jdev_home>/toplink/jlib/antlr.jar`	`<oracle_home>/toplink/jlib/antlr.jar`

Copy these BC4J EAR application files:

From JDeveloper	To Server
`<jdev_home>/BC4J/redist/bc4j.ear`	`<oracle_home>/BC4J/redist/bc4j.ear`
`<jdev_home>/BC4J/redist/bc4j.ear`	`<oracle_home>/j2ee/home/applications/BC4J.ear`

Solution 3

Map a local drive from a machine that already has JDeveloper installed to the target Oracle Application Server machine and rerun the ADF Runtime Installer. Use the mapped drive for the JDeveloper installation.

Be sure to install any maintenance releases of JDeveloper when you want to upgrade the target environment libraries.

B.2 Previously Working Application Using ADF Business Components Starts Throwing JDBC Errors

An application that previously successfully retrieved data suddenly starts throwing JDBC errors such as Connection Reset By Peer, Connection Closed, or Socket Reset By Peer.

Problem

The connections in the pool have become stale. This can happen for any of the following reasons:

The database was shut down or restarted without a corresponding restart of the JVM running the business components.
The connections were timed out by a firewall.
There were network problems.

Stale connections, when accessed, will throw errors.

Solution

If your ADF Business Components are deployed to Oracle Application Server 10g, you can set the parameter clean-available-connections-threshold to periodically clean up stale connections.

B.3 Changes to ADF Business Components Parameters Have No Effect

You have changed ADF Business Components runtime parameters, but the new parameters appear not to have taken effect.

Problem

ADF Business Components runtime parameters can be specified in several separate locations. A location with a higher precedence is overriding your changes. Runtime properties can be specified in the following locations, in descending order of precedence:

The ADF application module configuration being used by the client application
Applet tags
-D flags passed to the JVM
The bc4j.properties file in the directory holding your business components
The /oracle/jbo/BC4J.properties resource
The /oracle/jbo/common.jboserver.properties resource
The /oracle/jbo/common.Diagnostic.properties resource
The ADF BC library's own defaults

Solution

Check the locations with higher precedence to ensure that they are not overriding your changes.

B.4 ADF Business Components Throw ClassNotFoundException

When your application attempts to access business components, it throws a class not found exception that mentions an ADF BC framework class. You can diagnose the cause of this problem by searching for the JAR file which contains the class mentioned in the exception.

Problem 1

Your application was designed against a newer version of the ADF BC libraries than is available on the server, and the old version does not contain some of the classes your application is expecting.

Solution 1

Use the ADF Runtime Installer to install a newer version of the ADF BC libraries on the server.

Problem 2

A JClient application has been distributed without the required libraries in its archive.

Solution 2

Redeploy the JClient application with the missing libraries.

Problem 3

The archive containing the needed class is not on the classpath.

Solution 3

Ensure that the OC4J classpath includes the archive containing the needed class.

B.5 ADF Business Components Deployed with Libraries Throw Exceptions

You have deployed an application with ADF Business Components to a version of Oracle Application Server 10g with a different version of the ADF Business Components libraries installed. Even though you deployed the appropriate version of the libraries with your application, the application continues to throw exceptions as if it were attempting to run against the incorrect version.

Problem

The libraries installed on the application server appear earlier in the classpath than the appropriate libraries included in the application's EAR file.

Solution

Check the class loader hierarchy in the server.xml and orion-web.xml files to ensure that the libraries your application needs are loaded first. Ideally, you should avoid this problem by installing the latest version of the libraries using the ADF Runtime Installer.