3 Utilizing the OC4J Class-Loading Framework

Overview of Class Loading

The term class loading refers to the process of locating the bytes for a given class name and converting them into a Java class instance. All class instances within a Java Virtual Machine (JVM) start as an array of bytes, structured in the class file format defined by the JVM specification.

Class loading is performed by the JVM during the startup process, and subsequently by class loaders, subclasses of the java.lang.ClassLoader class, which find and load class files at runtime. Class loaders provide an abstraction that enables the JVM to load classes without any knowledge of where the class bytes come from, for both local and remote storage as well as dynamic class generation.

Each class loader works with one or more code sources, root locations from which the class loader searches for classes. Code sources can be defined to represent physical storage of binary class files, Java sources that must first be compiled, or even classes generated on the fly.

Standard class loaders are linked together in a parent-child hierarchy, with each class loader having an associated parent class loader. This hierarchy represents a tree structure, ranging in complexity from simple chains to complex, multibranched trees.

In this hierarchy, a child class loader imports a set of class loaders from its parent loader. In the OC4J context, all J2EE applications running within an OC4J instance are children of the system application. As a result, a class loader created at the application level imports a set of class loaders from the system.root class loader.

Figure 3-1 shows the class-loader hierarchy for a running OC4J instance through Peek. This display is a result of selecting Loaders from the View menu of Peek. See "Peek Utility for Debugging Class Loaders" for detailed information about the Peek utility.

Figure 3-1 Class-Loader Hierarchy

Peek Utility for Debugging Class Loaders

Peek OC4J Runtime Inspector enables you to search shared libraries and code sources, view the OC4J class-loader tree, and execute predefined queries to examine various aspects of the OC4J Runtime. Built-in to the default Web application of an OC4J instance, Peek is accessible through the following URIs:

• OC4J Standalone (oc4j_extended.zip):

  http://localhost:8888/peek/
  

• Oracle Application Server

  http://localhost:instance_port/j2ee/peek
  

  See "OC4J in an Oracle Application Server Configuration" in the Oracle Containers for J2EE Configuration and Administration Guide for more information on OC4J in Oracle Application Server

To logon to Peek, use the oc4jadmin username and the password that was set during the first initialization of OC4J.

Using the Peek utility, you can perform the following tasks:

• Search for any code source (JAR, ZIP, or directory) by name or path component. The search string can include wildcard characters and regular expressions. Simply enter the name in the text field and click go.

  Figure 3-2 shows the output from a search for the oc4j.jar code source.

  Figure 3-2 Search for a Code Source in Peek

  
  

• Search the contents of all code sources for class or resource names. The search string can include wildcard characters and regular expressions. Simply enter the fully qualified classname in the text field and click go.

  Figure 3-3 shows the output from a search for java.lang.String resource. The output indicates from which code source and class loader the resource was found.

  Figure 3-3 Search for a File in Peek

  
  

• View the class-loader tree, as Figure 3-1 shows, and browse its contents:

  • Each loader name and category, and for shared libraries, a description and contact information if available

  • Code sources

  • Loaded classes

  • All classes, with hyperlinks

  • All text-based resources

• Execute predefined queries to examine various aspects of the OC4J Runtime.

  For example, you can use the loadClass query to attempt to load a class from a specified class loader. Also, you can use the AuditLoader query to validate a class loader (shared library).

• Link to or bookmark any query run, because all operations are driven through a URL

  For example, you can bookmark a URL like the following one to list any duplicate classes that were loaded into an OC4J instance:

  http://localhost:8888/query?q=DuplicateClasses
  

Class Versioning with Shared Libraries in OC4J

The class-loader hierarchy ensures that a J2EE application deployed into the OC4J instance inherits a set of libraries by default from the default application. A Web module bound to this application, in turn, inherits a set of classes from the application, as well as the classes inherited from the system application, which sits at the root of the application hierarchy in OC4J.

However, this inheritance model is not always desirable, such as when a nondefault version of a library or class is needed by an application or module. The OC4J class-loading infrastructure addresses this problem by enabling class loaders created for an application or module to import a different version of a shared library than the default version imported by the parent class loader. An application or loader can even remove a class loader from the set of inherited class loaders entirely.

Figure 3-4 illustrates the class-loader tree structure in OC4J.

Figure 3-4 The OC4J Class-Loader Tree

Description of "Figure 3-4 The OC4J Class-Loader Tree"

• The jre.bootstrap loader is a proxy for the native bootstrap loader built into the JVM. The native bootstrap loader itself is not directly visible at runtime.

• The jre.extension loader is a custom replacement for the JRE-supplied "extension" loader.

• The api loader contains J2EE and OC4J API classes that must be visible to all applications as well as to all OC4J internal classes.

• The oc4j loader contains OC4J system classes.

• The system.root loader is created for the OC4J system application.

  Because system is at the root of the application hierarchy, the classes in this loader are inherited by default by all other applications deployed into the OC4J instance.

• global.root is the class loader created for the default application, which is the default parent of all J2EE applications deployed to the OC4J instance.

• app-name.root is the root loader for a deployed application.

• app-name.web.web-mod-name class loaders each contain Web module - classes packaged within a WAR file.

• app-name.jsp.jsp name loads a compiled JSP implementation class.

The OC4J shared class loaders, oracle.jdbc:10.1.0_2, oracle.jdbc:9.2.0_5, oracle:xml:10_1_02 and xerces:xml:2.6.2, represent shared libraries declared in the OC4J instance. Each shared library definition consists of these items:

• A shared library name, such as xerces.xml

• A version number that typically represents the shared library's implementation version, such as 2.6.2

• One or more code sources, JAR or ZIP files, containing the classes that comprise the library

Class Loaders are created at runtime based on the shared library definitions within the OC4J instance. Class Loaders are registered using a concatenation of the shared library name and the version number; for example, xerces.xml:2.6.2.

See "Installing and Publishing a Shared Library in OC4J" for detailed instructions on creating and installing shared libraries.

The JDBC driver and XML parser classes are loaded by the three deployed applications: While Application 1 follows the default behavior of inheriting the classes contained in the oracle.jdbc:10_1_02 and oracle:xml:10_1_02 shared loaders from its parent, Application 2 and Application 3 each import alternative driver and parser class loaders for their use.

By default, an application inherits the same set of shared libraries present in its parent application, including libraries inherited from the system application. This means, for example, that an application will by default use the Oracle JDBC driver and Oracle XML parser, which are inherited from the system application.

However, using OC4J's class versioning capabilities, you can override an inherited library with a different version, or even remove a library from the list of inherited libraries altogether.

Shared Libraries That Applications Import by Default

The default set of shared libraries imported by all application class loaders within the OC4J instance is specified within the <imported-shared-libraries> element in ORACLE_HOME/j2ee/instance/system-application.xml. This is the configuration file for the system application, an internal component of Oracle Containers for J2EE that sits at the root of the application hierarchy and provides classes and configuration required at OC4J startup. To view the imported shared libraries using peek, use the following URL:

http://localhost:8888/peek/loader/system.root:0.0.0

By default, an application deployed to an OC4J instance will inherit the following Oracle shared libraries:

• oracle.dms:3.0

• oracle.jdbc:10.1.0_2

• oracle.gdk:10.1.0_2

• oracle.xml:10.1.0_2

• oracle.xml.security:10.1.3

• oracle.toplink:10.1.3

• oracle.persistence:1.0

• oracle.ws.jaxrpc:1.1

• oracle.ws.client:10.1.3

• oracle.cache:10.1.3

• soap:10.1.3

• oracle.sqlj:10.1.3

• oracle.jwsdl:10.1.3

• global.libraries:1.0

• global.tag.libraries:1.0

• oracle.http.client:10.1.3

• org.jgroups:2.3

Example: Importing an Earlier Version of the Oracle JDBC Driver

The following example shows you 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 OC4J 10g (10.1.3.5.0). This example applies only to thin JDBC drivers and does not apply to the Oracle Call Interface (OCI) drivers.

Step 1: Create the Shared Library in OC4J

You can install a shared library for the 9.2.x JDBC driver using any of the mechanisms described in "Options for Installing and Publishing a Shared Library". This example illustrates how to do this task with Application Server Control.

1. Click Administration>Shared Libraries. Note the default JDBC driver shared library, oracle.jdbc:10.1.0_2.

2. Click Create on the Shared Libraries page.

3. Enter the name for the shared library. In this case, you will enter the same name as the existing library, which is oracle.jdbc.

4. Enter the shared library version, which in this case is 9.2.0_5.

5. Click Add to upload the library JAR file to the OC4J instance. The following shared library declaration is added to the ORACLE_HOME/j2ee/instance/server.xml file:

   <shared-library name="oracle.jdbc" version="9.2.0_5">
                   <code-source path="ojdbc14.jar"/>
           </shared-library>
   

Step 2: Configure an Application to Use the Shared Library

Once the shared library has been created in OC4J, you can configure an application to use it instead of the default shared library installed with OC4J.

The following example illustrates how to do this at the time the application is deployed with Application Server Control.

1. Select Applications>Deploy to launch the Application Server Control deployment wizard.

2. Supply the path to the application in the first page of the wizard.

3. Specify the application name and supply any context URI mappings in the second page.

4. Click Configure Class Loading in the third page of the wizard (Deploy: Deployment Settings).

   Both versions of the oracle.jdbc shared library are listed under Import Shared Libraries.

5. Specify the version number you want to use, 9.2.0_5, in the Maximum Version To Use column.

6. Deploy the application.

   After the application is deployed, the following entry is in the orion-application.xml deployment descriptor for the application:

   <imported-shared-libraries>
     <import-shared-library name="oracle.jdbc" max-version="9.2.0_05"/>
   </imported-shared-libraries>
   

Example: Configuring an Application to Use a DataDirect JDBC Driver

The Oracle Application Server distribution includes several JDBC drivers to provide connectivity to non-Oracle databases. The following example shows you how to configure an application to use the DataDirect Sybase driver to connect to a Sybase database.

Step 1: Create the Shared Library in OC4J

You can install a shared library for the driver using any of the mechanisms described in "Options for Installing and Publishing a Shared Library". This example will illustrate how to do this task with Application Server Control.

1. Click Administration>Shared Libraries.

2. Click Create on the Shared Libraries page.

3. Enter the name for the shared library; for example, sybase.jdbc.

4. Enter a version number for the shared library, such as 1.0.

5. Click Add to upload the library JAR files to the OC4J instance. Note that the YMbase.jar and YMutil.jar files are required to use any of the DataDirect drivers provided with Oracle Application Server.

   • YMsybase.jar

   • YMbase.jar

   • YMutil.jar

   The following shared library declaration is added to the ORACLE_HOME/j2ee/instance/server.xml file:

   <shared-library name="sybase.jdbc" version="1.0">
                   <code-source path="YMbase.jar"/>
                   <code-source path="YMutil.jar"/>
                   <code-source path="YMsybase.jar"/>
           </shared-library>
   

Step 2: Configure an Application to Use the Shared Library

Once the shared library has been created in OC4J, you can configure an application to use it instead of the default shared library installed with OC4J.

The following example illustrates how to do this task at the time the application is deployed with Application Server Control.

1. Select Applications and then Deploy to launch the Application Server Control deployment wizard.

2. Supply the path to the application in the first page of the wizard.

3. Specify the application name and supply any context URI mappings in the second page.

4. Click Configure Class Loading in the third page of the wizard (Deploy: Deployment Settings).

5. Check the Import checkbox for the sybase.jdbc shared library. Optionally specify 1.0 as the maximum version to use.

6. Deploy the application.

   After the application is deployed, the following entry is in the orion-application.xml deployment descriptor for the application:

   <imported-shared-libraries>
     <import-shared-library name="sybase.jdbc" max-version="1.0"/>
   </imported-shared-libraries>
   

Example: Replacing the Oracle XML Parser with the Xerces Parser

The following example illustrates how to remove the Oracle XML parser from the default set of shared libraries inherited from the system application with Application Server Control. It will also force the application to use the Xerces XML parser in its place.

Step 1: Create the Shared Library in OC4J

You can install a shared library for the Xerces parser using any of the mechanisms described in "Options for Installing and Publishing a Shared Library". This example illustrates how to do this task with Application Server Control.

1. Click Administration>Shared Libraries.

2. Click Create on the Shared Libraries page.

3. Enter the name for the shared library. In this case, you will enter xerces.xml.

4. Enter the shared library version, which in this case is 2.5.0.

5. Click Add to upload the library JAR files to the OC4J instance. Upload the following Apache libraries:

   • xercesImpl.jar

   • xml-apis.jar

   The following shared library declaration is added to the ORACLE_HOME/j2ee/instance/server.xml file:

   <shared-library name="xerces.mxl" version="2.5.0">
                   <code-source path="xercesImpl.jar"/>
     <code-source path="xml-apis.jar"/>
           </shared-library>
   

Step 2: Configure an Application to Use the Shared Library

Once the shared library has been created in OC4J, you can configure an application to use the Xerces parser instead of the default parser installed with OC4J.

The following example illustrates how to do this at the time the application is deployed with Application Server Control.

1. Select Applications>Deploy to launch the Application Server Control deployment wizard.

2. Supply the path to the application in the first page of the wizard.

3. Specify the application name and supply any context URI mappings in the second page.

4. Click Configure Class Loading in the third page of the wizard (Deploy: Deployment Settings).

5. Check the Import checkbox for the xerces.xml shared library. Optionally specify 2.5.0 as the maximum version to use.

6. To explicitly remove the Oracle parser, un-check the Import checkbox for the oracle.xml shared library to remove it from the list of shared libraries inherited by the application.

7. Optionally click the Save Deployment Plan button, and save the plan for re-use.

8. Deploy the application. After the application is deployed, note the following entry in the application's orion-application.xml file:

   <orion-application>
     <imported-shared-libraries>
       <remove-inherited name="oracle.xml"/>
       <import-shared-library name="xerces.xml" max-version="2.5.0"/>
     </imported-shared-libraries>
   </orion-application>
   

Example: Removing an Oracle Shared Library at Deployment Time

The following example illustrates how to remove the Oracle TopLink shared library at the time the application is deployed with Application Server Control.

1. Select Applications>Deploy to launch the Application Server Control deployment wizard.

2. Supply the path to the application in the first page of the wizard.

3. Specify the application name and supply any context URI mappings in the second page.

4. Click Configure Class Loading in the third page of the wizard (Deploy: Deployment Settings).

5. Uncheck the Import checkbox for the oracle.toplink shared library to remove it from the list of shared libraries inherited by the application.

6. Optionally click the Save Deployment Plan button, and save the plan for re-use.

7. Deploy the application. After the application is deployed, note the following entry in the application's orion-application.xml file:

   <orion-application>
     <imported-shared-libraries>
       <remove-inherited name="oracle.toplink"/>
     </imported-shared-libraries>
   </orion-application>
   

Configuring an Application to Use Its Own Shared Library

In this case, you will specify the default inherited Oracle library in the <remove-inherited> tag in orion-application.xml, which is then packaged with the JAR in the application's EAR file. After deployment to OC4J, the application will not import the default library installed with OC4J, causing the application's class loader to find and load your packaged library instead.

The following notation in orion-application.xml will prevent the application's class loader from importing the Oracle XML parser:

<imported-shared-libraries>
  <remove-inherited name="oracle.xml"/>
</imported-shared-libraries>

In the case of Web applications, you can specify that classes bundled within the application's WAR file be used through a notation in the application's orion-web.xml descriptor file.

First, add or uncomment the <web-app-class-loader> element in this file. Next, set the search-local-classes-first attribute to true in this element, which causes the class loader to find and load any libraries packaged in the WAR and to use these libraries rather than the corresponding libraries packaged with OC4J.

For information about how you can do this at deployment time with Application Server Control, see "Specifying search-local-classes-first at Deployment Time".

The entry in orion-web.xml looks like this:

<orion-web-app ...>
  ...
  <web-app-class-loader search-local-classes-first="true"
   include-war-manifest-class-path="true" />
  ...
</orion-web-app>

This approach is not a guaranteed solution; if an application further up the hierarchy imports a shared library that includes the same classes, a collision is likely, and such collisions are difficult to debug. Ideally, you should use the shared library mechanism documented in this chapter to ensure that your Web applications use the correct library.

Specifying search-local-classes-first at Deployment Time

The following example illustrates how to set the search-local-classes-first attribute in the orion-web.xml file generated for the Web module at deployment time, with Application Server Control.

1. Select Applications>Deploy to launch the Application Server Control deployment wizard.

2. Supply the path to the application in the first page of the wizard.

3. Specify the application name and supply any context URI mappings in the second page.

4. Click Configure Class Loading in the third page of the wizard (Deploy: Deployment Settings).

5. Under Configure Web Module Class Loaders, check the Search Local Classes First checkbox next to the name of the Web module containing the local JAR file to use.

6. Optionally click the Save Deployment Plan button, and save the plan for reuse.

When You Should Use a Shared Library

Typically, applications deployed to OC4J will use the set of shared libraries packaged with OC4J, which are inherited from the system application. However, there are scenarios in which replacing or removing a library inherited from the application's parent is necessary. Example use cases include:

• Using a different version of the Oracle JDBC driver than the version packaged with OC4J

• Replacing the Oracle XML parser packaged with OC4J with a different parser for use by your application

• Sharing proprietary classes across one or more specific applications, rather than across all applications

• Making an open source library, such as Struts or the Spring Framework, available to multiple Web applications

Options for Installing and Publishing a Shared Library

OC4J provides several options for installing and publishing shared libraries within one or more OC4J instances. Each of these mechanisms will install the shared library in the ORACLE_HOME/j2ee/instance/shared-lib directory and make the required entry in server.xml.

• Oracle Enterprise Manager 10g Application Server Control

  This option enables you to install a shared library on a specific OC4J instance through the Administration>Administration Tasks>Shared Libraries pages.

• The publishSharedLibrary Ant task

  This option enables you to install a shared library on a standalone OC4J server or on a single OC4J instance in an Oracle Application Server environment managed by Oracle Process Manager and Notification Server (OPMN).

• The -publishSharedLibrary command in admin_client.jar

  This option also enables you to install a shared library on a single OPMN-managed OC4J instance or on a standalone OC4J server.

You can also manually install and publish a shared library within an OC4J instance by following the process described under "How a Shared Library Is Installed and Published in an OC4J Instance".

How a Shared Library Is Installed and Published in an OC4J Instance

Shared libraries are installed in the ORACLE_HOME/j2ee/instance/shared-lib directory in OC4J. The process includes creating the correct directory structure within this directory and then copying one or more JAR or ZIP files that compose the library into the directory.

OC4J provides several tools that automate this process. See "Options for Installing and Publishing a Shared Library" for an overview.

To manually install a shared library:

1. Ensure that the classes are not already present in the OC4J instance by searching for the classes through Peek, which is described in "Peek Utility for Debugging Class Loaders".

   Figure 3-5 shows the results of searching a running OC4J instance in Peek for any classes whose path name contains *acme*.

   Figure 3-5 Class Search with Peek

   
   

2. Create the following directory structure:

   ORACLE_HOME/j2ee/instance/shared-lib
     /library_name
       /version
         filename.jar
         filename.zip
         ...
   

   The variables in the directory structure have these values:

   • instance is the name of an OC4J instance, which is home by default in an Oracle Application Server environment and always home on a standalone OC4J server.

   • library_name is a directory named with the name of the shared library; for example, acme.common.

     In cases where common APIs are implemented by multiple vendors, the name should include both the vendor name and the name of the technology; for example, oracle.jdbc or xerces.xml. If the technology is implemented by a single vendor, the technology name alone is sufficient.

   • version is a subdirectory named for the shared library version number; for example, 2.5. This value should ideally reflect the code implementation version.

3. copy each JAR or ZIP file containing the classes that compose the shared library into the version subdirectory. For example, assume the sample library consists of acme-apis.jar and acmeImpl.jar. Given the preceding examples, the resulting directory structure within the OC4J server would be as follows:

   ORACLE_HOME/j2ee/instance/shared-lib
     /acme.common
       /2.5
         acme-apis.jar
         acmeImpl.jar
   

4. To create multiple versions of the shared library, install each version's archive files in the version subdirectory, as the following example illustrates:

   ORACLE_HOME/j2ee/instance/shared-lib
     /acme.common
       /2.5
         acme-apis.jar
         acmeImpl.jar
       /3.0
         acme-apis.jar
         acmeImpl.jar
   

After the code sources are installed, the shared library is defined within a <shared-library> element that is added to the ORACLE_HOME/j2ee/instance/server.xml file, which contains the configuration data for the OC4J instance. The <shared-library> element takes the following attributes and subelements:

• A required name attribute, the value of which must match the name of the shared library directory created within the /shared-lib directory.

• A required version attribute, the value of which must match the version number that serves as the name of the subdirectory containing the shared library's archive files in the /shared-lib/library_name directory.

• One or more <code-source> subelements, each containing a path attribute defining the path to a JAR or ZIP file belonging to the library.

  A path can be absolute if it is outside of the /shared-lib directory, or it can be relative to the subdirectory containing the JAR or ZIP files within the /shared-lib/library_name directory. If a path is relative, only the archive file name needs to be supplied as the value for path.

The following example illustrates a shared library definition in the server.xml configuration file for the example shared library. The code source paths are relative to the subdirectory containing the JAR or ZIP files within the /shared-lib/acme.common directory; therefore, only the archive file names are specified as path values.

<shared-library name="acme.common" version="2.5">
  <code-source path="acme-apis.jar">
  <code-source path="acmeImpl.jar"/>
</shared-library>

You can set path="*" to force OC4J to consume all of the archives within the subdirectory. For example:

<shared-library name="acme.common" version="2.5">
  <code-source path="*" />
</shared-library>

Additionally, a shared library can be configured to import one or more other shared libraries. The <shared-library> element can take one or more <import-shared-library> elements, each specifying a shared library to be imported by the shared library being configured. An imported shared library must also be installed and published on the OC4J host.

The following sample code causes the acme.common shared library to import the xyz.log shared library:

<shared-library name="acme.common" version="2.5">
  <import-shared-library name="xyz.log"/>
  <code-source path="acme-apis.jar"/>
  <code-source path="acmeImpl.jar"/>
</shared-library>

When a relative code-source path is encountered at runtime, the full path is constructed by concatenating the shared library directory (/shared-lib), the shared library name, and the version number. For example, the preceding sample entries would resolve to these paths:

ORACLE_HOME/j2ee/instance/shared-lib/acme.common/2.5/acme-apis.jar
ORACLE_HOME/j2ee/instance/shared-lib/acme.common/2.5/acmeImpl.jar

Declaring Dependencies in an Application's OC4J Deployment Descriptor

A dependency can be declared by adding notations in the dependent application's orion-application.xml deployment descriptor.

Dependencies are declared by adding an <imported-shared-libraries> element in the application-specific orion-application.xml configuration file. This element takes one or more <import-shared-library> subelements, each specifying a shared library to import.

The <import-shared-library> element has the following attributes:

• name: The name of the shared library.

• min-version and max-version: These are optional attributes that enable you to specify a minimum or maximum version of the library to be specified for inclusion. To use the latest installed version of the library, do not specify a version number.

The following entry in orion-application.xml will import the acme.common:2.5 shared library for use by the application:

<imported-shared-libraries>
  <import-shared-library name="acme.common" max-version="2.6"/>
</imported-shared-libraries>

Declaring Dependencies in an Application's Manifest File

The standard Java extension mechanism, also known as optional packages, can be utilized to declare an application dependency on a JAR or ZIP file within a shared library. This is the standard J2EE mechanism for declaring dependencies on installed libraries.

To use this mechanism, the dependent JAR or ZIP file must be declared as a named extension in its MANIFEST.MF file. This name is specified as the value of the Extension-Name attribute. For example, the following manifest entry defines acme.common as an extension:

Extension-Name: acme.common
Specification-Vendor: Acme, Inc 
Specification-Version: 2.5 
Implementation-Vendor-Id: com.acme 
Implementation-Vendor: Acme, Inc 
Implementation-Version: 2.5 

The application that is dependent on the shared library then declares the dependency in its own manifest file. The following manifest attributes will cause the application to import the acme.common:2.5 shared library. The value of the name-Extension-Name attribute matches the Extension-Name value specified for the JAR or ZIP file's manifest file:

Extension-List: acme
acme-Extension-Name: acme.common
acme-Implementation-Version: 2.5

Version numbers in the Specification-Version and Implementation-Version attributes of a MANIFEST.MF file can have up to eight elements:

n1.n2.n3.n4.n5.n6.n7.n8

The maximum allowed value for an element is 99999999.

For more information on declaring dependencies using manifest files, see the following Web site:

http://java.sun.com/j2se/1.4.2/docs/guide/extensions/versioning.html

Configuring All Deployed Applications to Import a Specific Shared Library

You can ensure that all applications deployed to an OC4J instance use the same version of a shared library by configuring the default application to import it. Because default is the parent of all applications deployed to OC4J, any shared libraries that default imports will also be imported by these applications.

The configuration is managed by adding the XML notations described in "Declaring Dependencies in an Application's OC4J Deployment Descriptor" to the ORACLE_HOME/j2ee/instance/application.xml file, the configuration file for the default application.

The following entry in application.xml will ensure that all deployed applications use version 2.0 of the acme.common shared library:

<imported-shared-libraries>
  <import-shared-library name="acme.common" max-version="2.0"/>
</imported-shared-libraries>

Note that an application will use the version of a shared library imported from the default application—even if the application includes its own version of the shared library. If this is not desirable, you can "remove" the version imported from default using the process described in "Removing or Replacing an Oracle Shared Library Imported by Default".

Specifying a Built-In Query

You can use any of the following tools to specify the built-in queries for troubleshooting:

• Peek

  To retrieve information about an OC4J instance at run time, you can specify a query in the Peek command-line window. For more information, see "Specifying a Query in Peek".

• Startup property

  To have a query execute at OC4J startup, you can specify it in the oc4j.start.query system property for standalone OC4J or for an OC4J instance. For information about setting this system property from the command line, see "Specifying a Query in a Startup Property" For information about setting this system property for an OC4J instance through Application Server Control, see Oracle Containers for J2EE Configuration and Administration Guide.

• ClassLoading MBean

  You can specify a query through the ClassLoading MBean programatically or through the System MBean Browser of Application Server Control. For information about using MBeans programatically, see "Accessing MBeans From a Client Application" For more information about using MBeans through Application Server Control, see Oracle Containers for J2EE Configuration and Administration Guide.

Specifying a Query in Peek

In the Peek command-line window, you can enter a query to get information about a running OC4J instance or to show the arguments of a query.

To specify a query in Peek, enter the query name with any argument in the Peek command-line window.

Figure 3-7 shows a query for the ascontrol.web.ascontrol.jsp33119438:0.0.0 loader. The figure has been truncated, because the list that is returned is large.

Figure 3-7 Peek Display of ClassPath Query Arguments

You can also display the arguments of a query by clicking its name in the list of queries, which Figure 3-6 shows.

Auditing Class Loaders

You can use the AuditLoader query to audit one or more of the class loaders available in an OC4J instance by performing diagnostics on their contents. This query enables you to specify the level of audit output and to include JRE classes in the audit.

The output from AuditLoader includes information about errors. If you are adding a new shared library, you should try to remove all errors reported for the new library.

How to Audit Class Loaders with Peek

In Peek you can audit class loaders by entering AuditLoader in the command-line window and specifying the class loaders, optionally followed by additional arguments. Table 3-2 describes the arguments.

To audit class loaders with Peek:

1. In the list of queries on the initial Peek screen, click AuditLoader.

   Peek places the query name in the command-line window and displays the query arguments.

2. If you want to specify one or more class loaders to audit, select each class loader from the list under -- loaderName --.

   Peek places each name you select in the command line after AuditLoader.

   Alternatively, you can type the list of class loaders, separating each name from the next with a space.

3. If you want to audit all class loaders available in the OC4J instance, type * after AuditLoader.

   If you specify AuditLoader * immediately after another AuditLoader query, Peek uses the arguments from the preceding query.

4. Click go or press the Enter key.

   Peek displays the results of the query.

5. If you want to run the same query later, save the URL for reuse.

6. If you are adding a new shared library, try to remove all errors reported in the AuditLoader results for that library and then rerun the query to verify that the errors are gone.

For example, to audit the oracle.jdbc loader with detailed output, you would specify the query as follows:

AuditLoader oracle.jdbc:10.1.0_2 -verbose

Figure 3-8 shows part of the output from an execution of this query. The figure has been truncated, because the list that is returned is large.

Figure 3-8 AuditLoader Query

Note:

it is possible to audit all loaders; however, the system may run out of memory if the user tries to Audit all loaders. Users may specify * to audit all shared loaders (try -XX:MaxPermSize=512m).

loaderName [loaderName] . . . | * [-verbose] [-includeJREClasses]

Finding Classes That Call a Method

The Callers query reports all classes that call the specified method or methods. You can limit the query by specifying the name of a class loader.

-Doc4j.start.query=Callers(java.lang.System.currentTimeMillis()long)

-Doc4j.start.query=Callers(-MyApp.root,java.lang.System.currentTimeMillis()long)

-Doc4j.start.query=Callers(java.lang.Class.forName(java.lang.
String)java.lang.Class,java.lang.Class.forName(java.lang.String;boolean;java.lang.
ClassLoader)java.lang.Class)

-Doc4j.start.query=Callers(java.util.Date.init())

[-loaderName,]signature . . .

Monitoring Metrics for Class Loaders

The ClassLoadMetrics query reports metrics for one or more specified class loaders or for all class loaders if none is specified.

-Doc4j.start.query=ClassLoadMetrics(MyApp.root,MyOtherApp.root)

[-verbose] [loaderName] ...

Listing Code Sources in Use

The ClassPath query lists the code sources in use.

The ClassPath query has the following arguments:

[-list] [loaderName]

Table 3-5 describes these arguments.

Determining the Dependencies of a Class

The Dependencies query reports all dependencies of the specified class.

The Dependencies query has the following arguments:

className [loaderName] [-r]

Table 3-6 describes these arguments.

Determining Dependent Classes

The Depends query reports on all classes that are dependent on the specified class.

The Depends query has the following arguments:

[-loaderName] className 

Table 3-7 describes these arguments.

Finding Duplicate Classes

The DuplicateClasses query reports the existence of classes and resources with the same name in different code sources.

The DuplicateClasses query has the following arguments:

[[-loaderName] [-systemCodeSources]

Table 3-8 describes these arguments.

Finding Duplicate Code Sources

The DuplicateCodeSources query reports code sources that have the same name or have more than one subscriber.

The DuplicateCodeSources query has the following argument:

[-digest]

Table 3-9 describes this argument.

Exiting a Query Process

The Exit query exits the process and shuts down OC4J, if it is running. This is useful if you only want to execute a query without leaving the OC4J server running. For example:

-Doc4j.start.query=LoaderTree+Exit

The Exit query has the following argument:

[-force]

Table 3-10 describes this argument.

Finding a Resource in Code Sources

The FindResource query reports the code sources that contain a specified resource. The code sources are identified by either class name or resource path.

For a simple wildcard search, you can use a leading or trailing asterisk (* )

To indicate that the argument should be treated as a regular expression, you can use a leading tilde (~ )

How to Use the FindResource Query in Peek

In Peek, you can use FindResource to display any code sources that contains a resource.

Figure 3-9 FindResource Query

-Doc4j.start.query=FindResource(Foo.class)

-Doc4j.start.query=FindResource(*myconfig.xml)

[[-list] resourcePath|className

Getting Resources Used by a Class Loader

The GetResource query calls getResource() or getResources() on a specified loader and reports the results.

The GetResource query has the following arguments:

resourcePath [loaderName] [-all]

Table 3-12 describes these arguments.

Monitoring HTTP Sessions for Deployed Applications

The HttpSessions query reports a summary of active HTTP sessions for deployed applications.

The HttpSessions query has the following argument:

[details]

Table 3-13 describes this argument.

Detecting Class-Loader Leaks

The LeakedLoaders query controls detection of class-loader leaks and lists results.

The LeakedLoaders query has the following arguments:

[activate|list|deactivate]

Table 3-14 describes these arguments.

Listing Classes Available from a Class Loader

The ListClasses query lists all classes available from a given class loader.

java -Doc4j.start.query=ListClasses:loaderName -jar oc4j.jar

ListClasses apache.commons.logging:1.0.4

org.apache.commons.logging.Log
org.apache.commons.logging.LogConfigurationException
org.apache.commons.logging.LogFactory
org.apache.commons.logging.LogFactory$1
org.apache.commons.logging.LogFactory$2
org.apache.commons.logging.LogFactory$3
org.apache.commons.logging.LogSource
org.apache.commons.logging.impl.AvalonLogger
org.apache.commons.logging.impl.Jdk14Logger
org.apache.commons.logging.impl.Log4JCategoryLog
org.apache.commons.logging.impl.Log4JLogger
org.apache.commons.logging.impl.Log4jFactory
org.apache.commons.logging.impl.LogFactoryImpl
org.apache.commons.logging.impl.LogFactoryImpl$1
org.apache.commons.logging.impl.LogKitLogger
org.apache.commons.logging.impl.NoOpLog
org.apache.commons.logging.impl.SimpleLog
org.apache.commons.logging.impl.SimpleLog$1

loaderName

Listing Queries

The ListQueries query lists all of the available queries in OC4J, by oracle.oc4j.query.Query subclass name.

java  -Dstart.query="ListQueries(-l)"  -jar oc4j.jar

[[-l] [queryclass] ...

Loading a Class

You can use the loadClass query to perform a class-loading test run. This query attempts to load a specified class using the specified class loader, or using the internal class loader if none is specified, and reports the result.

The loadClass query is useful for troubleshooting a ClassNotFoundException error. You can use the query to load classes from different initial loaders and get reports on the results.

What Happens When You Use the loadClass Query in Peek

Peek loads the specified class and then displays a report with the class name, defining class loader, and code source from which the class was loaded. Figure 3-10 shows a loadClass report.

Figure 3-10 loadClass Query

[className [ loaderName] [-forName] [-depends] [-r] [-sort] 

Listing Loaded Classes

The LoadedClasses query lists the names of all loaded classes (if available) in an OC4J instance.

How to Use the LoadedClasses Query in Peek

in Peek you can specify the LoadedClasses query in the command-line window to list loaded classes.

To Use the LoadedClasses Query in Peek:

Figure 3-11 shows the output from a LoadedClasses query.

Figure 3-11 LoadedClasses Query in Peek

Listing the Contents of a Class-Loader Tree

The LoaderTree query reports the contents of the class-loader tree for the specified root class loader, or for the JRE bootstrap class loader if none specified. By default, only the names of the class loaders within the tree are reported.

This query is useful if you want to focus on a specific part of the class-loader tree, such as from the root of a specific application downwards. Peek can also be used to list the contents of a class-loader tree. See "Viewing a Class-Loader Tree with Peek" later in this section.

-Doc4j.start.query=LoaderTree(MyApp.root)

-Doc4j.start.query=LoaderTree

[[rootLoaderName] [-verbose]

Listing Packages in Code Sources

The Packages query lists the package names contained within one or more code sources.

The Packages query has the following arguments:

[loaderName | codeSourcePath]

Table 3-19 describes these arguments.

Monitoring Replication Statistics

The SessionReplicationStats query retrieves statistics for replicated HTTP and EJB sessions for a given application.

The SessionReplicationStats query has the following argument:

[application name]

Table 3-20 describes this argument.

Listing Installed Shared Libraries and Their Class Loaders

The SharedLibraries query lists all installed shared libraries and the class loaders that import the libraries.

The SharedLibraries query has the following argument:

[loaderName]

Table 3-21 describes this argument.

Listing and Setting System Properties

The SystemProperties query lists or sets system properties.

The SystemProperties query has the following argument:

[key=value] ...

Table 3-22 describes this argument.

Figure 3-12 shows a Peek query that returns all system properties that are currently set. The figure has been truncated, because the list that is returned is large.

Figure 3-12 System Property Query from Peek

Listing Thread-Pool Information

The ThreadPools query lists information about thread pools for the current JVM.

The ThreadPools query has the following arguments:

(list [sys|req|cx]|pool [sys|req|cx]|state [sys|req|cx][id])

Table 3-23 describes these arguments.

Listing Thread Information

The Threads query lists thread information for the current JVM. For JDK 1.5, checks for thread deadlocks or gets thread memory usage for the current JVM.

The Threads query has the following arguments:

[list|groups|deadlock|memory]

Table 3-24 describes these arguments.

Finding Unused Code Sources

The UnusedCodeSources query reports code sources that have never retuned any data.

The UnusedCodeSources query has no arguments.

Determining the Uptime for an OC4J Instance

The Uptime query reports the length of time the current OC4J instance has been running.

The Uptime query has no arguments.

Monitoring JVM Statistics

The VMStat query lists statistics information for the current JVM.

The VMStat query has the following arguments:

[jps|pid|mem]

Table 3-25 describes these arguments.

Resolving Class-Loading Exceptions

Most class-loading errors in J2EE often surface as one of a small set of exceptions. The OC4J class-loading infrastructure provides "annotated" subclasses for each of the following standard class-loading configuration exceptions:

• ClassNotFoundException

• NoClassDefFoundError

• ClassFormatError

• LinkageError

• ClassCastException

The subclasses enhance the output of the getMessage(), printStackTrace(), and toString() methods with information to help you understand and correct the configuration. Often, this extra information is all that is needed to fix the problem; when it isn't, the logging, tracing, and query features can be used to dig further.

For each error, a diagnostic search may be performed to provide additional information. This search is not restricted by standard loader visibility rules and can visit any loader or code source known to the system. Results are reported as part of the error message.

Under some conditions it would be possible for the loader runtime to act on the results and attempt recovery (such as automatically find and load a missing class). However, this might lead to further problems that would then be more difficult to diagnose.

Thread thread = Thread.currentThread();
ClassLoader loader = thread.getContextClassLoader();
Class cls = loader.loadClass(name);

Class cls = Class.forName(name, true, loader);

Missing class: acme.Dynamite

        Dependent class: acme.RoadRunner
Loader: acme.root:0.0.0
Code-Source: /myapps/acme/acme.jar
Configuration: <ejb> in /myapps/acme/application.xml

The missing class is available from the following locations:

1.      Code-Source: /shared/bang/0.0.0/bang.jar (from <code-source> 
in j2ee/home/server.xml)

This code-source is available in loader bang:0.0.0. This 
shared-library can be imported by the "acme" application.

Object source = new Integer(0);
String target = (String) source; // Exception

import com.acme.Foo;
...
// Get the loader that resolves our static dependency
// on class Foo

ClassLoader expected = Foo.class.getClassLoader();

// Dynamically load Foo from another loader and
// create an instance

Class fooClass = aLoader.loadClass("com.acme.Foo");
Object source = fooClass.newInstance();
ClassLoader actual = fooClass.getClassLoader();

// Compare and cast

System.out.println(actual == expected); // "false"
Foo target = (Foo) source; // Exception

ClassLoader expected = Foo.class.getClassLoader();
System.out.println("Expected: " + expected);
ClassLoader actual = obj.getClass().getClassLoader();
System.out.println("  Actual: " + actual);

Tracing Class-Loading Events to Help Troubleshoot Issues

OC4J provides the class.load.log system property that can be set to trace class loading, class-loader life cycle, and code-source life-cycle events. The tracing output generated can be extremely useful in troubleshooting issues related to class loading.

The class.load.log property is set at OC4J startup. The syntax follows:

class.load.log=<event>[[:<string-filter>[,<string-filter>]] |
 [~<pattern-filter>]]

• <event> is the event to trace. See Table 3-26 for valid values.

  Multiple event values can be strung together with a + character.

  -Dclass.load.log=class+loader 
  

• <string-filter> is a filter applied to manage trace output. Note that a colon (:) separates the initial filter from the event. See "Using Filters to Manage Trace Output" for details on the types of filters that can be applied to manage trace output.

  Multiple filters can be separated by a comma:

  -Dclass.load.log=class:com.acme.Foo,com.acme.Bar
  

• <pattern-filter> is a single filter that is interpreted as a regular expression. Note that a ~ character precedes the filter.

Trace output is written to the console by default, but can be written to a file specified using the class.load.log.file system property. For example:

java -Dclass.load.log.file=C:\logs\logfile.txt -jar oc4j.jar

<event>[[:<string-filter>[,<string-filter>]] | [~<pattern-filter>]]

Setting Class-Loader Log Levels

By default, the class-loader logger messages are filtered at the CONFIG Java log level. If necessary, you can use the class.load.log.level system property to change the log level. Table 3-28 lists the values that can be set on this property.

For example, to set the log level to SEVERE:

-Dclass.load.log.level=severe

Note that tracing-related messages are written at the INFO log level. As a result, avoid setting the log level above INFO, such as to WARNING, to prevent these messages from being filtered from the logger output.