8 Understanding WebLogic Server Application Classloading

Java Classloader Hierarchy

Classloaders contain a hierarchy with parent classloaders and child classloaders. The relationship between parent and child classloaders is analogous to the object relationship of super classes and subclasses. The bootstrap classloader is the root of the Java classloader hierarchy. The Java virtual machine (JVM) creates the bootstrap classloader, which loads the Java development kit (JDK) internal classes and java.* packages included in the JVM. (For example, the bootstrap classloader loads java.lang.String.)

The extensions classloader is a child of the bootstrap classloader. The extensions classloader loads any JAR files placed in the extensions directory of the JDK. This is a convenient means to extending the JDK without adding entries to the classpath. However, anything in the extensions directory must be self-contained and can only refer to classes in the extensions directory or JDK classes.

The system classpath classloader extends the JDK extensions classloader. The system classpath classloader loads the classes from the classpath of the JVM. Application-specific classloaders (including WebLogic Server classloaders) are children of the system classpath classloader.

Loading a Class

Classloaders use a delegation model when loading a class. The classloader implementation first checks its cache to see if the requested class has already been loaded. This class verification improves performance in that its cached memory copy is used instead of repeated loading of a class from disk. If the class is not found in its cache, the current classloader asks its parent for the class. Only if the parent cannot load the class does the classloader attempt to load the class. If a class exists in both the parent and child classloaders, the parent version is loaded. This delegation model is followed to avoid multiple copies of the same form being loaded. Multiple copies of the same class can lead to a ClassCastException.

Classloaders ask their parent classloader to load a class before attempting to load the class themselves. Classloaders in WebLogic Server that are associated with Web applications can be configured to check locally first before asking their parent for the class. This allows Web applications to use their own versions of third-party classes, which might also be used as part of the WebLogic Server product. The prefer-web-inf-classes Element section discusses this in more detail.

prefer-web-inf-classes Element

The weblogic.xml Web application deployment descriptor contains a <prefer-web-inf-classes> element (a sub-element of the <container-descriptor> element). By default, this element is set to False. Setting this element to True subverts the classloader delegation model so that class definitions from the Web application are loaded in preference to class definitions in higher-level classloaders. This allows a Web application to use its own version of a third-party class, which might also be part of WebLogic Server. See "weblogic.xml Deployment Descriptor Elements".

When using this feature, you must be careful not to mix instances created from the Web application's class definition with issuances created from the server's definition. If such instances are mixed, a ClassCastException results.

Example 8-1 illustrates the prefer-web-inf-classes element, its description and default value.

/** 
* If true, classes located in the WEB-INF directory of a web-app will be
* loaded in preference to classes loaded in the application or system
* classloader. 
* @default false 
*/ 
boolean isPreferWebInfClasses(); 
void setPreferWebInfClasses(boolean b);

Changing Classes in a Running Program

WebLogic Server allows you to deploy newer versions of application modules such as EJBs while the server is running. This process is known as hot-deploy or hot-redeploy and is closely related to classloading.

Java classloaders do not have any standard mechanism to undeploy or unload a set of classes, nor can they load new versions of classes. In order to make updates to classes in a running virtual machine, the classloader that loaded the changed classes must be replaced with a new classloader. When a classloader is replaced, all classes that were loaded from that classloader (or any classloaders that are offspring of that classloader) must be reloaded. Any instances of these classes must be re-instantiated.

In WebLogic Server, each application has a hierarchy of classloaders that are offspring of the system classloader. These hierarchies allow applications or parts of applications to be individually reloaded without affecting the rest of the system. WebLogic Server Application Classloading discusses this topic.

Configuring Class Caching

WebLogic Server now allows you to enable class caching for faster start ups. Once you enable caching, the server records all the classes loaded until a specific criterion is reached and persists the class definitions in an invisible file. When the server restarts, the cache is checked for validity with the existing code sources and the server uses the cache file to bulk load the same sequence of classes recorded in the previous run. If any change is made to the system classpath or its contents, the cache will be invalidated and re-built on server restart.

The advantages of using class caching are:

• Reduces server startup time.

• The package level index reduces search time for all classes and resources.

The cache uses optimization techniques to minimize the initial cache recording time. Cache recording continues until a specific class has been recorded.

1. To enable class caching, set an environment variable (CLASS_CACHE=true for UNIX, set CLASS_CACHE=true for Windows) in the startWebLogic script.

2. Configure class caching using the following properties:

   • Logging: To debug class caching issues, turn on logging by placing the following system properties in the JAVA_OPTIONS for the section of the startup script that enables caching.

     -Dclass.load.log.level=finest -Dclass.load.log.file=/tmp/class-load-log.txt

     There are three levels of logging: fine, finer, finest. Do not enable logging during regular cache operation. Logging will slow the start up of the server. Use logging for debugging only.

   • Recording limit: Though the recording limit for class caching is set to a specific class, you can configure this class in your environment to a different class.

     -Dlaunch.complete=<fully qualified class name> for example com.oracle.component.Foo

     The class used in this property must be in the system classpath for WebLogic Server.

Example 8-2 illustrates modified UNIX and Windows startWebLogic scripts with class caching enabled and logging turned on.

On UNIX

# CLASS CACHING
CLASS_CACHE=true
if [ "${CLASS_CACHE}" = "true" ] ; then
        echo "Class caching enabled..."
        JAVA_OPTIONS="${JAVA_OPTIONS} -Dlaunch.main.class=${SERVER_CLASS} 
        -Dlaunch.class.path="${CLASSPATH}" 
        -Dlaunch.complete=weblogic.store.internal.LockManagerImpl 
        -Dclass.load.log.level=finest 
        -Dclass.load.log.file=/tmp/class-load-log.txt 
        -cp ${WL_HOME}/server/lib/pcl2.jar"
        export JAVA_OPTIONS
        SERVER_CLASS="com.oracle.classloader.launch.Launcher"
fi


On Windows

@REM CLASS CACHING
set CLASS_CACHE=true
if "%CLASS_CACHE%"=="true" (
    echo Class caching enabled...
    set JAVA_OPTIONS=%JAVA_OPTIONS% -Dlaunch.main.class=%SERVER_CLASS% 
    -Dlaunch.class.path="%CLASSPATH%" -Dclass.load.log.level=finest 
    -Dclass.load.log.file=C:\class-load-log.txt 
    -Dlaunch.complete=weblogic.store.internal.LockManagerImpl 
    -cp %WL_HOME%\server\lib\pcl2.jar
    set SERVER_CLASS=com.oracle.classloader.launch.Launcher
)

Overview of WebLogic Server Application Classloading

WebLogic Server classloading is centered on the concept of an application. An application is normally packaged in an Enterprise Archive (EAR) file containing application classes. Everything within an EAR file is considered part of the same application. The following may be part of an EAR or can be loaded as standalone applications:

• An Enterprise JavaBean (EJB) JAR file

• A Web application WAR file

• A resource adapter RAR file

  Note:

  See the following sections for more information:

  • For information on Resource Adapters and classloading, see About Resource Adapter Classes.

  • For information on overriding generic application files while classloading, see "Generic File Loading Overrides" in Deploying Applications to Oracle WebLogic Server.

If you deploy an EJB and a Web application separately, they are considered two applications. If they are deployed together within an EAR file, they are one application. You deploy modules together in an EAR file for them to be considered part of the same application.

Every application receives its own classloader hierarchy; the parent of this hierarchy is the system classpath classloader. This isolates applications so that application A cannot see the classloaders or classes of application B. In hierarchy classloaders, no sibling or friend concepts exist. Application code only has visibility to classes loaded by the classloader associated with the application (or module) and classes that are loaded by classloaders that are ancestors of the application (or module) classloader. This allows WebLogic Server to host multiple isolated applications within the same JVM.

Application Classloader Hierarchy

WebLogic Server automatically creates a hierarchy of classloaders when an application is deployed. The root classloader in this hierarchy loads any EJB JAR files in the application. A child classloader is created for each Web application WAR file.

Because it is common for Web applications to call EJBs, the WebLogic Server application classloader architecture allows JavaServer Page (JSP) files and servlets to see the EJB interfaces in their parent classloader. This architecture also allows Web applications to be redeployed without redeploying the EJB tier. In practice, it is more common to change JSP files and servlets than to change the EJB tier.

The following graphic illustrates this WebLogic Server application classloading concept.

Figure 8-1 WebLogic Server Classloading

If your application includes servlets and JSPs that use EJBs:

• Package the servlets and JSPs in a WAR file

• Package the Enterprise JavaBeans in an EJB JAR file

• Package the WAR and JAR files in an EAR file

• Deploy the EAR file

Although you could deploy the WAR and JAR files separately, deploying them together in an EAR file produces a classloader arrangement that allows the servlets and JSPs to find the EJB classes. If you deploy the WAR and JAR files separately, WebLogic Server creates sibling classloaders for them. This means that you must include the EJB home and remote interfaces in the WAR file, and WebLogic Server must use the RMI stub and skeleton classes for EJB calls, just as it does when EJB clients and implementation classes are in different JVMs. This concept is discussed in more detail in the next section Application Classloading and Pass-by-Value or Reference.

Custom Module Classloader Hierarchies

You can create custom classloader hierarchies for an application allowing for better control over class visibility and reloadability. You achieve this by defining a classloader-structure element in the weblogic-application.xml deployment descriptor file.

The following diagram illustrates how classloaders are organized by default for WebLogic applications. An application level classloader exists where all EJB classes are loaded. For each Web module, there is a separate child classloader for the classes of that module.

For simplicity, JSP classloaders are not described in the following diagram.

Figure 8-2 Standard Classloader Hierarchy

This hierarchy is optimal for most applications, because it allows call-by-reference semantics when you invoke EJBs. It also allows Web modules to be independently reloaded without affecting other modules. Further, it allows code running in one of the Web modules to load classes from any of the EJB modules. This is convenient, as it can prevent a Web module from including the interfaces for EJBs that it uses. Note that some of those benefits are not strictly Java EE-compliant.

The ability to create custom module classloaders provides a mechanism to declare alternate classloader organizations that allow the following:

• Reloading individual EJB modules independently

• Reloading groups of modules to be reloaded together

• Reversing the parent child relationship between specific Web modules and EJB modules

• Namespace separation between EJB modules

Declaring the Classloader Hierarchy

You can declare the classloader hierarchy in the WebLogic-specific application deployment descriptor weblogic-application.xml.

The DTD for this declaration is as follows:

<!ELEMENT classloader-structure (module-ref*, classloader-structure*)>
<!ELEMENT module-ref (module-uri)>
<!ELEMENT module-uri (#PCDATA)>

For more information on the DTD elements, refer to Appendix A, "Enterprise Application Deployment Descriptor Elements."

The following is an example of a classloader declaration (defined in the classloader-structure element in weblogic-application.xml):

<classloader-structure> 
   <module-ref> 
      <module-uri>ejb1.jar</module-uri> 
   </module-ref>
   <module-ref> 
      <module-uri>web3.war</module-uri> 
   </module-ref>

   <classloader-structure> 
      <module-ref> 
         <module-uri>web1.war</module-uri> 
      </module-ref> 
   </classloader-structure>

   <classloader-structure> 
      <module-ref> 
         <module-uri>ejb3.jar</module-uri> 
      </module-ref> 
      <module-ref> 
         <module-uri>web2.war</module-uri> 
      </module-ref>

      <classloader-structure> 
         <module-ref> 
            <module-uri>web4.war</module-uri> 
         </module-ref> 
      </classloader-structure> 
      <classloader-structure> 
         <module-ref> 
            <module-uri>ejb2.jar</module-uri> 
         </module-ref> 
      </classloader-structure>
   </classloader-structure>
</classloader-structure>

Figure 8-3 Example Classloader Hierarchy

User-Defined Classloader Restrictions

User-defined classloader restrictions give you better control over what is reloadable and provide inter-module class visibility. This feature is primarily for developers. It is useful for iterative development, but the reloading aspect of this feature is not recommended for production use, because it is possible to corrupt a running application if an update includes invalid elements. Custom classloader arrangements for namespace separation and class visibility are acceptable for production use. However, programmers should be aware that the Java EE specifications say that applications should not depend on any given classloader organization.

Some classloader hierarchies can cause modules within an application to behave more like modules in two separate applications. For example, if you place an EJB in its own classloader so that it can be reloaded individually, you receive call-by-value semantics rather than the call-by-reference optimization Oracle provides in our standard classloader hierarchy. Also note that if you use a custom hierarchy, you might end up with stale references. Therefore, if you reload an EJB module, you should also reload the calling modules.

There are some restrictions to creating user-defined module classloader hierarchies; these are discussed in the following sections.

Individual EJB Classloader for Implementation Classes

WebLogic Server allows you to reload individual EJB modules without requiring you to reload other modules at the same time and having to redeploy the entire EJB module. This feature is similar to how JSPs are currently reloaded in the WebLogic Server servlet container.

Because EJB classes are invoked through an interface, it is possible to load individual EJB implementation classes in their own classloader. This way, these classes can be reloaded individually without having to redeploy the entire EJB module. Below is a diagram of what the classloader hierarchy for a single EJB module would look like. The module contains two EJBs (Foo and Bar). This would be a sub-tree of the general application hierarchy described in the previous section.

Figure 8-4 Example Classloader Hierarchy for a Single EJB Module

To perform a partial update of files relative to the root of the exploded application, use the following command line:

java weblogic.Deployer -adminurl url -user user -password password 
-name myapp -redeploy myejb/foo.class

java weblogic.Deployer -adminurl url -user user -password password 
-name myapp -redeploy mywar myejb/foo.class anotherejb

Application Classloading and Pass-by-Value or Reference

Modern programming languages use two common parameter passing models: pass-by-value and pass-by-reference. With pass-by-value, parameters and return values are copied for each method call. With pass-by-reference, a pointer (or reference) to the actual object is passed to the method. Pass by reference improves performance because it avoids copying objects, but it also allows a method to modify the state of a passed parameter.

WebLogic Server includes an optimization to improve the performance of Remote Method Interface (RMI) calls within the server. Rather than using pass by value and the RMI subsystem's marshalling and unmarshalling facilities, the server makes a direct Java method call using pass by reference. This mechanism greatly improves performance and is also used for EJB 2.0 local interfaces.

RMI call optimization and call by reference can only be used when the caller and callee are within the same application. As usual, this is related to classloaders. Because applications have their own classloader hierarchy, any application class has a definition in both classloaders and receives a ClassCastException error if you try to assign between applications. To work around this, WebLogic Server uses call-by-value between applications, even if they are within the same JVM.

Using a Filtering Classloader

In WebLogic Server, any JAR file present in the system classpath is loaded by the WebLogic Server system classloader. All applications running within a server instance are loaded in application classloaders which are children of the system classloader. In this implementation of the system classloader, applications cannot use different versions of third-party JARs which are already present in the system classloader. Every child classloader asks the parent (the system classloader) for a particular class and cannot load classes which are seen by the parent.

For example, if a class called com.foo.Baz exists in both $CLASSPATH as well as the application EAR, then the class from the $CLASSPATH is loaded and not the one from the EAR. Since weblogic.jar is in the $CLASSPATH, applications can not override any WebLogic Server classes.

The following sections define and describe how to use a filtering classloader:

• What is a Filtering ClassLoader

• Configuring a FilteringClassLoader

• Resource Loading Order

What is a Filtering ClassLoader

The FilteringClassLoader provides a mechanism for you to configure deployment descriptors to explicitly specify that certain packages should always be loaded from the application, rather than being loaded by the system classloader. This allows you to use alternate versions of applications such as Xerces and Ant. Though the FilteringClassLoader lets you bundle and use 3rd party JARs in your application, it is not recommended that you filter out API classes, like classes in javax packages or weblogic packages.

The FilteringClassLoader sits between the application classloader and the system classloader. It is a child of the system classloader and the parent of the application classloader. The FilteringClassLoader intercepts the loadClass(String className) method and compares the className with a list of packages specified in weblogic-application.xml file. If the package matches the className, the FilteringClassLoader throws a ClassNotFoundException. This exception notifies the application classloader to load this class from the application.

Configuring a FilteringClassLoader

To configure the FilteringClassLoader to specify that a certain package is loaded from an application, add a prefer-application-packages descriptor element to weblogic-application.xml which details the list of packages to be loaded from the application. The following example specifies that org.apache.log4j.* and antlr.* packages are loaded from the application, not the system classloader:

<prefer-application-packages>
  <package-name>org.apache.log4j.*</package-name>
  <package-name>antlr.*</package-name>
</prefer-application-packages>

For aid in configuring filtering classloaders, see Using the Classloader Analysis Tool (CAT).

Resource Loading Order

The resource loading order is the order in which java.lang.ClassLoader methods getResource()and getResources() return resources. When filtering is enabled, this order is slightly different from the case when filtering is disabled. Filtering is enabled implies that there are one or more package patterns in the FilteringClassLoader. Without any filtering (default), the resources are collected in the top-down order of the classloader tree. For instance, if Web (1) requests resources, the resources are grouped in the following order: Sys (3), App (2) and Web(1). See Example 8-7.

System (3)
   |
  App (2) 
   |
  Web (1)

META-INF/foo.xml - from the System ClassLoader (3)
META-INF/foo.xml - from the App ClassLoader (2)
META-INF/foo.xml - from the Web ClassLoader (1)

META-INF/foo.xml - from the App ClassLoader (B)
META-INF/foo.xml - from the Web ClassLoader (A)
META-INF/foo.xml - from the System ClassLoader (D)

System (D)
  |
  FilteringClassLoader (filterList := x.y.*) (C)
   |
  App (B)
   |
  Web (A)

META-INF/foo.xml - from the App ClassLoader (B)
META-INF/foo.xml - from the System ClassLoader (D)

About Resource Adapter Classes

Each resource adapter now uses its own classloader to load classes (similar to Web applications). As a result, modules like Web applications and EJBs that are packaged along with a resource adapter in an application archive (EAR file) do not have visibility into the resource adapter's classes. If such visibility is required, you must place the resource adapter classes in APP-INF/classes. You can also archive these classes (using the JAR utility) and place them in the APP-INF/lib of the application archive.

Make sure that no resource-adapter specific classes exist in your WebLogic Server system classpath. If you need to use resource adapter-specific classes with Web modules (for example, an EJB or Web application), you must bundle these classes in the corresponding module's archive file (for example, the JAR file for EJBs or the WAR file for Web applications).

Packaging Shared Utility Classes

WebLogic Server provides a location within an EAR file where you can store shared utility classes. Place utility JAR files in the APP-INF/lib directory and individual classes in the APP-INF/classes directory. (Do not place JAR files in the /classes directory or classes in the /lib directory.) These classes are loaded into the root classloader for the application.

This feature obviates the need to place utility classes in the system classpath or place classes in an EJB JAR file (which depends on the standard WebLogic Server classloader hierarchy). Be aware that using this feature is subtly different from using the manifest Class-Path described in the following section. With this feature, class definitions are shared across the application. With manifest Class-Path, the classpath of the referencing module is simply extended, which means that separate copies of the classes exist for each module.

Manifest Class-Path

The Java EE specification provides the manifest Class-Path entry as a means for a module to specify that it requires an auxiliary JAR of classes. You only need to use this manifest Class-Path entry if you have additional supporting JAR files as part of your EJB JAR or WAR file. In such cases, when you create the JAR or WAR file, you must include a manifest file with a Class-Path element that references the required JAR files.

The following is a simple manifest file that references a utility.jar file:

Manifest-Version: 1.0 [CRLF]
Class-Path: utility.jar [CRLF]

In the first line of the manifest file, you must always include the Manifest-Version attribute, followed by a new line (CR | LF |CRLF) and then the Class-Path attribute. More information about the manifest format can be found at: http://java.sun.com/j2se/1.4/docs/guide/jar/jar.html#JAR

The manifest Class-Path entries refer to other archives relative to the current archive in which these entries are defined. This structure allows multiple WAR files and EJB JAR files to share a common library JAR. For example, if a WAR file contains a manifest entry of y.jars, this entry should be next to the WAR file (not within it) as follows:

/<directory>/x.war
/<directory>/y.jars

The manifest file itself should be located in the archive at META-INF/MANIFEST.MF.

For more information, see http://download-llnw.oracle.com/javase/tutorial/deployment/jar/manifestindex.html.