11 Understanding WebLogic Server Application Classloading
This chapter includes the following sections:
- Java Classloading
Classloaders are a fundamental module of the Java language. A classloader is a part of the Java virtual machine (JVM) that loads classes into memory; a classloader is responsible for finding and loading class files at run time. Every successful Java programmer needs to understand classloaders and their behavior. - 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. WebLogic Server application classloading allows WebLogic Server to host multiple isolated applications within the same JVM. - Resolving Class References Between Modules and Applications
WebLogic Server deploys applications in separate classloaders to maintain independence and to facilitate dynamic redeployment and undeployment. Because of this, you need to package your application classes in such a way that each module has access to the classes it depends on. - Using the Classloader Analysis Tool (CAT)
CAT is a Web-based class analysis tool that simplifies filtering classloader configuration and aids you in analyzing classloading issues, such as detecting conflicts, debugging application classpaths and class conflicts, and proposes solutions to help you resolve them. - Sharing Applications and Modules By Using Java EE Libraries
Java EE libraries provide an easy way to share one or more different types of Java EE modules among multiple enterprise applications. - Adding JARs to the Domain /lib Directory
WebLogic Server includes alib
subdirectory, located in the domain directory, that you can use to add one or more JAR files, so that the JAR file classes are available within a separate system level classloader to all Java EE applications running on WebLogic Server instances in the domain.
Java Classloading
Classloaders are a fundamental module of the Java language. A classloader is a part of the Java virtual machine (JVM) that loads classes into memory; a classloader is responsible for finding and loading class files at run time. Every successful Java programmer needs to understand classloaders and their behavior.
- Java Classloader Hierarchy
- Loading a Class
- prefer-web-inf-classes Element
- Changing Classes in a Running Program
- Class Caching With the Policy Class Loader
The Policy Class Loader (PCL) is the default system class loader when starting WebLogic Server using a startWebLogic script. The Policy Class Loader improves class loader performance and server startup time through class caching and indexing and is supported in any WebLogic mode (development or production). - Class Caching With Application Class Data Sharing
The Application Class Data Sharing (AppCDS) is a class loader optimization that supports archive files of predefined, validated, and linked classes.
Parent topic: 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.
Note:
What Oracle refers to as a "system classpath classloader" is often referred to as the "application classloader" in contexts outside of WebLogic Server. When discussing classloaders in WebLogic Server, Oracle uses the term "system" to differentiate from classloaders related to Java EE applications or libraries (which Oracle refers to as "application classloaders").
Parent topic: Java Classloading
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.
Parent topic: Java Classloading
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 instances created from the server's definition. If such instances are mixed, a ClassCastException
results.
Example 11-1 illustrates the prefer-web-inf-classes
element, its description and default value.
Example 11-1 prefer-web-inf-classes Element
/** * 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);
Parent topic: Java Classloading
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.
Parent topic: Java Classloading
Class Caching With the Policy Class Loader
The Policy Class Loader (PCL) is the default system class loader when starting WebLogic Server using a startWebLogic script. The Policy Class Loader improves class loader performance and server startup time through class caching and indexing and is supported in any WebLogic mode (development or production).
The Policy Class Loader caches loaded classes in a cache file. Upon subsequent starts, the cached classes are preloaded in bulk, improving performance in use cases that load a large number of classes from the system class loader, such as server startup. The Policy Class Loader also contains an eager index, which maps package names and JAR files containing the source code. This index improves lookup time for classes and reduces the time spent looking for missing classes or resources. Cached files are generated in the DOMAIN_HOME/servers/weblogic_name/cache/classloader
directory.
Note:
Class Caching with the Policy Class Loader is only supported for JDK 8.Policy Class Loader by default has the class caching not enabled. In WebLogic Server 12.1.3, you could enable class caching in development mode by setting the CLASS_CACHE
environment variable in the startWebLogic
script. For pre-existing 12.1.3 start scripts, continue to use the CLASS_CACHE
variable to enable class caching. See Configuring Class Caching in Developing Applications for Oracle WebLogic Server 12c (12.1.3).
As of WebLogic Server 12.2.1, new domains use the Policy Class Loader by default for class caching. Any 12.1.3 domains that upgrade to 12.2.1 also automatically use the Policy Class Loader.
Note:
If you want to disable the Policy Class Loader and use the standard system class loader in JVM, setUSE_JVM_SYSTEM_LOADER=true
when you run the startWebLogic
script.
Parent topic: Java Classloading
Class Caching With Application Class Data Sharing
The Application Class Data Sharing (AppCDS) is a class loader optimization that supports archive files of predefined, validated, and linked classes.
This implementation improves the startup time of Oracle WebLogic Server and allows multiple JVMs on the same machine to share memory pages, thereby reducing overall memory usage.
To use this feature, do the following:
- Generate Class List During WebLogic Server Trial
- Generate AppCDS Archive
- Run WebLogic Server With AppCDS Archive
Generate Class List During WebLogic Server Trial
Generate a class list by starting the WebLogic Server with the following option:
./startWebLogic.sh generateClassList
By default, the class list will be generated at $DOMAIN_HOME/WebLogic.classlist
. You can change this by setting the value of APPCDS_CLASS_LIST
when starting the WebLogic Server. For example:
APPCDS_CLASS_LIST=my.classlist ./startWebLogic.sh generateClassList
When you use class caching with AppCDS, the Policy Class Loader (PCL) will be disabled.
Generate AppCDS Archive
Generate an AppCDS archive using the command:
./generateArchive.sh
By default, the class list file will be available at $DOMAIN_HOME/WebLogic.classlist
, and the archive file will be generated at $DOMAIN_HOME/WebLogic.jsa
. You can change these filenames by setting the value of APPCDS_CLASS_LIST
and APPCDS_ARCHIVE
respectively, when running the generateArchive.sh
command. For example:
APPCDS_CLASS_LIST=my.classlist APPCDS_ARCHIVE=myArchive.jsa ./generateArchive.sh
Run WebLogic Server With AppCDS Archive
After you generate an AppCDS archive, run the WebLogic Server using this archive:
./startWebLogic.sh useArchive
You can change the default location of the AppCDS archive by setting the value of APPCDS_ARCHIVE
when starting the WebLogic Server. For example:
APPCDS_ARCHIVE=myArchive.jsa ./startWebLogic.sh useArchive
AppCDS is not compatible with Policy Class Loader. Therefore, Policy Class Loader will be disabled.
Parent topic: Java Classloading
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. WebLogic Server application classloading allows WebLogic Server to host multiple isolated applications within the same JVM.
- Overview of WebLogic Server Application Classloading
- Application Classloader Hierarchy
- Custom Module Classloader Hierarchies
- Declaring the Classloader Hierarchy
- User-Defined Classloader Restrictions
- Individual EJB Classloader for Implementation Classes
- Application Classloading and Pass-by-Value or Reference
- Using a Filtering ClassLoader
- What is a Filtering ClassLoader
- Configuring a Filtering ClassLoader
- Resource Loading Order
Parent topic: Understanding WebLogic Server Application Classloading
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.
Parent topic: WebLogic Server Application Classloading
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.
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.
Note:
The Web application classloader contains all classes for the Web application except for the JSP class. The JSP class obtains its own classloader, which is a child of the Web application classloader. This allows JSPs to be individually reloaded.
Parent topic: WebLogic Server Application Classloading
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 11-2 Standard Classloader Hierarchy
Description of "Figure 11-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
Parent topic: WebLogic Server Application Classloading
Declaring the Classloader Hierarchy
You can declare the classloader hierarchy in the WebLogic-specific application deployment descriptor weblogic-application.xml
.
<!ELEMENT classloader-structure (module-ref*, classloader-structure*)> <!ELEMENT module-ref (module-uri)> <!ELEMENT module-uri (#PCDATA)>
The top-level element in weblogic-application.xml
includes an optional classloader-structure
element. If you do not specify this element, then the standard classloader is used. Also, if you do not include a particular module in the definition, it is assigned a classloader, as in the standard hierarchy. That is, EJB modules are associated with the application root classloader, and Web application modules have their own classloaders.
The classloader-structure
element allows for the nesting of classloader-structure
stanzas, so that you can describe an arbitrary hierarchy of classloaders. There is currently a limitation of three levels. The outermost entry indicates the application classloader. For any modules not listed, the standard hierarchy is assumed.
Note:
JSP classloaders are not included in this definition scheme. JSPs are always loaded into a classloader that is a child of the classloader associated with the Web module to which it belongs.
For more information on the DTD elements, refer to Enterprise Application Deployment Descriptor Elements.
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>
The organization of the nesting indicates the classloader hierarchy. The above stanza leads to a hierarchy shown in the following diagram.
Parent topic: WebLogic Server Application Classloading
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.
- Servlet Reloading Disabled
- Nesting Depth
- Module Types
- Duplicate Entries
- Interfaces
- Call-by-Value Semantics
- In-Flight Work
- Development Use Only
Parent topic: WebLogic Server Application Classloading
Servlet Reloading Disabled
If you use a custom classloader hierarchy, servlet reloading is disabled for Web applications in that particular application.
Parent topic: User-Defined Classloader Restrictions
Nesting Depth
Nesting is limited to three levels (including the application classloader). Deeper nestings lead to a deployment exception.
Parent topic: User-Defined Classloader Restrictions
Module Types
Custom classloader hierarchies are currently restricted to Web and EJB modules.
Parent topic: User-Defined Classloader Restrictions
Duplicate Entries
Duplicate entries lead to a deployment exception.
Parent topic: User-Defined Classloader Restrictions
Interfaces
The standard WebLogic Server classloader hierarchy makes EJB interfaces available to all modules in the application. Thus other modules can invoke an EJB, even though they do not include the interface classes in their own module. This is possible because EJBs are always loaded into the root classloader and all other modules either share that classloader or have a classloader that is a child of that classloader.
With the custom classloader feature, you can configure a classloader hierarchy so that a callee's classes are not visible to the caller. In this case, the calling module must include the interface classes. This is the same requirement that exists when invoking on modules in a separate application.
Parent topic: User-Defined Classloader Restrictions
Call-by-Value Semantics
The standard classloader hierarchy provided with WebLogic Server allows for calls between modules within an application to use call-by-reference semantics. This is because the caller is always using the same classloader or a child classloader of the callee. With this feature, it is possible to configure the classloader hierarchy so that two modules are in separate branches of the classloader tree. In this case, call-by-value semantics are used.
Parent topic: User-Defined Classloader Restrictions
In-Flight Work
Be aware that the classloader switch required for reloading is not atomic across modules. In fact, updates to applications in general are not atomic. For this reason, it is possible that different in-flight operations (operations that are occurring while a change is being made) might end up accessing different versions of classes depending on timing.
Parent topic: User-Defined Classloader Restrictions
Development Use Only
The development-use-only feature is intended for development use. Because updates are not atomic, this feature is not suitable for production use.
Parent topic: User-Defined Classloader Restrictions
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 11-4 Example Classloader Hierarchy for a Single EJB Module
Description of "Figure 11-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:
Example 11-2 Performing a Partial File Update
java weblogic.Deployer -adminurl url -user user -password password -name myapp -redeploy myejb/foo.class
After the -redeploy
command, you provide a list of files relative to the root of the exploded application that you want to update. This might be the path to a specific element (as above) or a module (or any set of elements and modules). For example:
Example 11-3 Providing a List of Relative Files for Update
java weblogic.Deployer -adminurl url -user user -password password -name myapp -redeploy mywar myejb/foo.class anotherejb
Given a set of files to be updated, the system tries to figure out the minimum set of things it needs to redeploy. Redeploying only an EJB impl
class causes only that class to be redeployed. If you specify the whole EJB (in the above example, anotherejb
) or if you change and update the EJB home interface, the entire EJB module must be redeployed.
Depending on the classloader hierarchy, this redeployment may lead to other modules being redeployed. Specifically, if other modules share the EJB classloader or are loaded into a classloader that is a child to the EJB's classloader (as in the WebLogic Server standard classloader module) then those modules are also reloaded.
Parent topic: WebLogic Server Application Classloading
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.
Note:
Calls between applications are slower than calls within the same application. Deploy modules together as an EAR file to enable fast RMI calls and use of the EJB 2.0 local interfaces.
Parent topic: WebLogic Server Application Classloading
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:
Parent topic: WebLogic Server Application Classloading
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.
Parent topic: WebLogic Server Application Classloading
Configuring a Filtering ClassLoader
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>
The prefer-application-packages
descriptor element can also be defined in weblogic.xml
. See prefer-application-packages
.
You can specify that a certain package be loaded for a WAR file included within an EAR file by configuring the FilteringClassLoader
in the weblogic.xml
file of the WAR file.
For example, A.ear
contains B.war
. A.ear
defines the FilteringClassLoader
in weblogic-application.xml
, and B.war
defines a different FilteringClassLoader
in weblogic.xml
. When you deploy A.ear
, B.war
loads the package defined in the FilteringClassLoader
in weblogic.xml
. The WAR-level FilteringClassLoader
has priority over the EAR-level FilteringClassLoader
for this WAR file.
For aid in configuring filtering classloaders, see Using the Classloader Analysis Tool (CAT).
Parent topic: WebLogic Server Application Classloading
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 11-4.
Note:
The resources are returned in the default Java EE delegation model beneath the FilteringClassLoader
. Only the resources from the parent of the FilteringClassLoader
are appended to the end of the enumeration being returned.
Example 11-4 Using the System Classloader
System (3) | App (2) | Web (1)
To be more explicit, given a resource /META-INF/foo.xml
which exists in all the classloaders, would return the following list of URLs:
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)
When filtering is enabled, the resources from the child of the FilteringClassLoader
(an application classloader) down to the calling classloader are returned before the ones from the system classloader. In Example 11-5, if the same resource existed in all the classloaders (D), (B) and (A) one would get them in the following order if requested by the Web classloader:
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)
Example 11-5 Using a Filtering Classloading Implementation
System (D) | FilteringClassLoader (filterList := x.y.*) (C) | App (B) | Web (A)
If the application classloader requested the same resource, the following order would be obtained.
META-INF/foo.xml - from the App ClassLoader (B) META-INF/foo.xml - from the System ClassLoader (D)
For getResource()
, only the first descriptor is returned and getResourceAsStream()
returns the inputStream
of the first resource.
Parent topic: WebLogic Server Application Classloading
Resolving Class References Between Modules and Applications
WebLogic Server deploys applications in separate classloaders to maintain independence and to facilitate dynamic redeployment and undeployment. Because of this, you need to package your application classes in such a way that each module has access to the classes it depends on.
Your applications may use many different Java classes, including Enterprise Beans, servlets and JavaServer Pages, utility classes, and third-party packages. In some cases, you may have to include a set of classes in more than one application or module. This section describes how WebLogic Server uses multiple classloaders so that you can stage your applications successfully.
For more information about analyzing and resolving classloading issues, see Using the Classloader Analysis Tool (CAT).
Parent topic: Understanding WebLogic Server Application Classloading
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://docs.oracle.com/javase/7/docs/technotes/guides/jar/jar.html
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
.
See http://docs.oracle.com/javase/tutorial/deployment/jar/manifestindex.html
.
Using the Classloader Analysis Tool (CAT)
CAT is a Web-based class analysis tool that simplifies filtering classloader configuration and aids you in analyzing classloading issues, such as detecting conflicts, debugging application classpaths and class conflicts, and proposes solutions to help you resolve them.
CAT is a stand-alone Web application, distributed as a single WAR file, wls-cat.war
, exposing its features through a Web-based front end. CAT is deployed as an internal on-demand application only in development mode. Deployment happens upon first access. If the server is running in production mode, it is not deployed automatically. You can deploy it in production mode; there are no limitations on its use, but you must deploy it manually, just like any other Web application. The CAT Web application is located at WL_HOME
/server/lib/wls-cat.war
. You can deploy it to any WebLogic Server version 10.3.x and later.
Note:
CAT is not supported on IBM SDK for Java because some functions of the CAT application depend on HotSpot implementation.
- Opening the CAT Interface
- How CAT Analyzes Classes
- Identifying Class References through Manifest Hierarchies
Parent topic: Understanding WebLogic Server Application Classloading
Opening the CAT Interface
CAT has a simple Web GUI that displays all your currently running applications and modules.
To begin using CAT:
-
In the WebLogic Server Administration Console, select Deployments > app_name > Testing and then select the Classloader Analysis Tool link. Enter your console login credentials.
~ Or ~
-
Open your browser to
http://wls-host:port/wls-cat/
and then enter your console login credentials.
In the navigation pane, select the application or module that you want to analyze; a brief description of it is shown in the right-side pane. Use the right-side pane to perform actions and analyses on the selected application or module, such as:
-
Analyze classloading conflicts
-
View the system and application classloaders
-
Generate reports
Parent topic: Using the Classloader Analysis Tool (CAT)
How CAT Analyzes Classes
CAT analyzes classes loaded by the system classpath classloader and the WebLogic Server main application classloaders, defined here as the filtering, application, and module classloaders. You can perform analysis at the class, package, or JAR level. The results for each action you select can be shown in either a basic view or a detailed view.
Here are some of the tasks which you can perform using CAT:
-
Display basic information about applications and modules
-
Analyze classloading conflicts
-
Review proposed solutions
-
Get suggestions for configuring filtering classloaders
-
Display the classloader hierarchy and the entire classpath for each classloader
-
Search for a class (or a resource) on a classloader
Parent topic: Using the Classloader Analysis Tool (CAT)
Identifying Class References through Manifest Hierarchies
Applications can have multiple manifest references to classes that are not directly present in the applications's classpath, but which are chained into the Classpath by manifest references. In some cases, application developers may not be aware that additional classes have been unknowingly pulled into the application's classpath from other JARs, which in turn have manifest references to other JARs.
cat4mf.ear +- ejb.jar +- web-mf-in-root.war +- lib +- applib.jar +- apputil_1.jar +- apputil_1_1.jar +- apputil_1_1_1.jar +- apputil_1_2.jar +- apputil_1_2_1.jar +- ejbutil_1.jar +- ejbutil_1_1.jar +- ejbutil_1_2.jar +- ejbutil_1_2_1.jar +- webutil_1.jar +- webutil_1_1.jar +- webutil_1_1_1.jar +- webutil_2.jar +- webutil_2_1.jar
The ejb.jar
has a manifest reference to ejbutil_1.jar
, which has references to both ejbutil_1_1.jar
and ejbutil_1_2.jar
, which has a further reference to ejbutil_1_2_1.jar
, as follows:
ejb.jar -> ejbutil_1.jar -> ejbutil_1_1.jar -> ejbutil_1_2.jar -> ejbutil_1_2_1.jar
Using CAT to Display the Manifest References
Parent topic: Using the Classloader Analysis Tool (CAT)
Sharing Applications and Modules By Using Java EE Libraries
Java EE libraries provide an easy way to share one or more different types of Java EE modules among multiple enterprise applications.
A Java EE library is a single module or collection of modules that is registered with the Java EE application container upon deployment. For more information, see Creating Shared Java EE Libraries and Optional Packages.
Parent topic: Understanding WebLogic Server Application Classloading
Adding JARs to the Domain /lib
Directory
WebLogic Server includes a lib
subdirectory, located in the domain directory, that you can use to add one or more JAR files, so that the JAR file classes are available within a separate system level classloader to all Java EE applications running on WebLogic Server instances in the domain.
The JARS in the domain /lib
directory will not be appended to the system classpath. The classloader that gets created is a child of the system classloader. Any classes that are in JARs in the domain /lib
directory will only be visible to Java EE applications, such as EAR files. Classes in the system classpath cannot access classes in the domain /lib
directory.
The lib
subdirectory is intended for JAR files that change infrequently and are required by all or most applications deployed in the server. For example, you might use the lib
directory to store third-party utility classes that are required by all Java EE deployments in a domain. Third-party utility classes will be made available because the domain /lib
classloader will be the parent of any Java EE application.
The lib
directory is not recommended as a general-purpose method for sharing a JARs between one or two applications deployed in a domain, or for sharing JARs that need to be updated periodically. If you update a JAR in the lib
directory, you must reboot all servers in the domain in order for applications to realize the change. If you need to share a JAR file or Java EE modules among several applications, use the Java EE libraries feature described in Creating Shared Java EE Libraries and Optional Packages.
To share JARs using the lib
directory:
Parent topic: Understanding WebLogic Server Application Classloading