3 Utilizing the OC4J Class Loading Framework

What Is 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 classloaders, subclasses of the java.lang.ClassLoader class that find and load class files at runtime. Classloaders provide an abstraction that allows the JVM to load classes without any knowledge of where the class bytes come from, to enable both local and remote storage as well as dynamic class generation.

Each classloader works with one or more code sources - root locations from which the classloader 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 classloaders are linked together in a parent-child hierarchy, with each classloader having an associated parent classloader. This hierarchy represents a tree structure, ranging in complexity from simple chains to complex multi-branched trees.

In this hierarchy, a child classloader imports a set of classloaders 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 classloader created at the application level imports a set of classloaders from the system.root classloader.

See Figure 3-1 below for a graphical representation of the classloader tree structure used in OC4J.

Class Versioning with Shared Libraries in OC4J

The classloader 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 application hierarchy in OC4J.

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

Figure 3-1 below illustrates the classloader tree structure in OC4J.

Figure 3-1 The OC4J Classloader Tree

Description of the illustration jidev001.gif

• 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 classloader 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 classloaders each contain Web module - classes packaged within a WAR file.

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

The OC4J shared classloaders - 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:

• 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; and

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

Classloaders are created at runtime based on the shared library definitions within the OC4J instance. Classloaders 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.

Note how 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 classloaders 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.

What Shared Libraries Do Applications Import by Default?

The default set of shared libraries imported by all application classloaders within the OC4J instance is specified within the imported-shared-libraries element in ORACLE_HOME/j2ee/home/system-application.xml. This is the configuration file for the system application, which is the parent of all applications within the OC4J instance.

The following are the key Oracle shared libraries that an application deployed to an OC4J instance will inherit by default:

• oracle.jdbc:10.1.0_2

• oracle.xml:10.1.0_2

• oracle.cache:10.1.3

• oracle.http.client:10.1.3

• oracle.sqlj:10.1.3

• soap:10.1.3

• oracle.jwsdl:10.1.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, an earlier version of the Oracle JDBC driver than the version packaged with OC4J.

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 will illustrate this task using Application Server Control Console.

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 using Application Server Control Console.

1. Select Applications>Deploy to launch the Application Server Control Console 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. Note that both versions of the oracle.jdbc shared library are listed in the Import Shared Libraries frame. 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, notethe following entry in the application's orion-application.xml file:

   <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 this task using Application Server Control Console.

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 the shared library version, for example: 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 at the time the application is deployed using Application Server Control Console.

1. Select Applications>Deploy to launch the Application Server Control Console 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, notethe following entry in the application's orion-application.xml file:

   <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 using Application Server Control Console. 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 will illustrate this task using Application Server Control Console.

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 using Application Server Control Console.

1. Select Applications>Deploy to launch the Application Server Control Console 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 using Application Server Control Console.

1. Select Applications>Deploy to launch the Application Server Control Console 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. Un-check 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>
   

Example: 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. this at the time the application is deployed using Application Server Control Console.

1. Select Applications>Deploy to launch the Application Server Control Console 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 re-use.

When Should You Use a Shared Library?

Typically, applications deployed into 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 then 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/home/shared-lib directory and make the required entry in server.xml.

• Oracle Enterprise Manager 10g Application Server Control Console

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

• The publishSharedLibrary Ant task

  Allows you to install a shared library on a single OPMN-managed OC4J instance or on a standalone OC4J server.

• The -publishSharedLibrary command in admin_client.jar

  Also allows 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 following the process outlined in the next section, "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/home/shared-lib directory in OC4J. The process includes creating the correct directory structure within this directory, then copying the JAR files that comprise the library into it.

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

First, the following directory structure for the library is created within this directory:

ORACLE_HOME/j2ee/home/shared-lib
  /library_name
    /version
      filename.jar
      filenamejar
      ...

• 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.

Once these directories have been created, copy each JAR or ZIP file containing the classes that comprise the shared library into the version subdirectory. For example, assume the sample library consists of acme-apis.jar and acmeImpl.jar.

Given the examples above, the resulting directory structure within the OC4J server would be:

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

Multiple versions of the shared library are installed by creating a new subdirectory for each version's archive files within this directory structure, as illustrated below:

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

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

• 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.

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

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

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

Note that you can optionally 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 optionally take one or more <import-shared-library> elements, each specifying a shared library to be imported by the shared library being configured. Note that an imported shared library must also be installed and published on the OC4J host.

The following example 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 sample entries above would resolve to:

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

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 allow 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 file within a shared library. This is the standard J2EE mechanism for declaring dependencies on installed libraries.

To use this mechanism, the dependent JAR 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. Note that the value of the name-Extension-Name attribute exactly matches the Extension-Name specified in the JAR file's manifest:

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

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

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 other applications deployed to OC4J, any shared libraries it 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/home/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 and/or Replacing an Oracle Shared Library Imported by Default".

Overview of Troubleshooting

Most class loading errors in Java are related to visibility—either not enough or, more rarely, too much. Visibility in this case refers to the set of classes and resources that are available on the "class-path": the search path across a set of loaders and the code-sources (e.g. JARs and/or directories) they contain.

In JavaSE, the class-path is usually thought of as the list of code-sources specified on the command-line or in the manifest Class-Path of the main jar. These code-sources are all deployed in a single loader, usually referred to as the "system" loader. This loader is in turn wired up to two other loaders: the JRE extensions loader (normally for any JARs in the jre/lib/ext directory) and the JRE bootstrap loader (containing rt.jar etc.)

The idea that there is a class-path is often quite misleading. For each class lookup, the search begins at a specific loader, and (normally) can only visit loaders "above" it. This means that a search starting at the extensions loader would have a very different class-path than one starting at the system loader.

In JavaEE, the situation is substantially more complicated, as multiple class loaders are required in place of the single system loader. Each deployed application has at least one loader, separate from all other applications, so each has a distinct class-path. There are frequently different class-paths even within a single application, as each web module is deployed in a separate loader.

This can easily be seen by making the following call from within different modules, as OC4J ensures that the correct class-path is returned for the calling module:

System.getProperty("java.class.path");

There are many configuration options that affect class visibility for applications. Table (UNKNOWN STEP NUMBER) lists the most common options within OC4J. Given the possible combinations of loaders and code-sources in a JavaEE environment, it is easy to see how visibility errors can arise. Often, a simple configuration change is all that is required to eliminate the problem, but understanding what change to make can be tricky.

Classloader-Related Errors and 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() or toString() methods with information to help 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.

Note that 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);

Using Queries to Troubleshoot Class Loading Issues

OC4J provides a number of built-in queries that can be run to troubleshoot classloader-related problems. Queries can be executed at OC4J startup by setting the oc4j.start.query system property, or at runtime through the ClassLoading MBean.

• Summary of Available Queries

• Executing Queries at OC4J Startup

• Executing Queries at Runtime via the ClassLoading MBean

-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>())

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

-Doc4j.start.query=LoaderTree+Exit

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

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

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

-Doc4j.start.query=LoaderTree

java -Doc4j.start.query=<queryName>(arg0,arg1,...) -jar oc4j.jar

java -Doc4j.start.query=DuplicateCodeSources(-digest) -jar oc4j.jar

-Doc4j.start.query=DuplicateCodeSources(-digest)+UnusedCodeSources

Tracing Class Loading Events to Help Troubleshoot Issues

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

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

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

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

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

  -Dclass.load.trace=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.trace=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 Classloader Log Levels

By default, the classloader 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-15 below 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 - to WARNING, for example - to prevent these messages from being filtered from the Logger output.