Troubleshooting class loaders

Overview

Class loaders find and load class files.

To diagnose and problems, use the admin console class loader viewer to examine class loaders and their classes.

The modules can be...

• Web modules (.war files)
• EJB modules (.jar files)

The class loader viewer enables you to examine class loaders in a runtime environment.

Enable the class loader viewer service...

Servers | Server Types | WebSphere application servers | server_name | Class loader viewer service

...and restart the server.

The runtime environment of WAS uses the following class loaders to find and load new classes for an application in the following order:

1. The bootstrap, extensions, and CLASSPATH class loaders created by the JVM
2. A WebSphere extensions class loader
3. One or more application module class loaders that load elements of enterprise applications running in the server
4. Zero or more Web module class loaders

Each class loader is a child of the previous class loader. That is, the application module class loaders are children of the WebSphere extensions class loader, which is a child of the CLASSPATH Java class loader. Whenever a class needs to be loaded, the class loader usually delegates the request to its parent class loader. If none of the parent class loaders can find the class, the original class loader attempts to load the class. Requests can only go to a parent class loader; they cannot go to a child class loader. After a class is loaded by a class loader, any new classes that it tries to load reuse the same class loader or go up the precedence list until the class is found.

If the class loaders that load the artifacts of an application are not configured properly, the JVM might throw a class loading exception when starting or running that application. Class loading exceptions describes the types of exceptions caused by improperly configured class loaders and suggests ways to use the class loader viewer to correct configurations of class loaders. The types of exceptions include:

• ClassCastException
• ClassNotFoundException
• NoClassDefFoundException
• UnsatisfiedLinkError

 

Use class loader viewer to examine class loaders

1. Examine a tree view that lists all installed applications and their modules. The modules can be Web modules (.war files) or EJB modules (.jar files).

   Click Troubleshooting > Class loader viewer to access the Enterprise applications topology page.

2. Examine the class loader delegation hierarchy.

   On the Enterprise applications topology page, select a module to access the Class loader viewer page. The page lists the class loaders visible to Web and EJB modules in an installed enterprise application. This page helps you to determine which class loaders loaded files of a module and to diagnose problems with class loaders.

   The delegation hierarchy is determined by the class loader delegation mode, or class loader order, specified for an application or Web module. The value can be either Classes loaded with parent class loader first or Classes loaded with local class loader first (parent last). Refer to the Set class loaders step for more information.

3. Export information on class loaders.

   1. On the Class loader viewer page, click Export.

   2. Select to open a browser or editor on the class loader information or to save the information to disk in XML format.

   3. Click OK, and specify any additional information requested by the system.

4. Display information about class loaders visible to the module in an HTML table format.

   On the Class loader viewer page, click Table View. The Table View page displays the following information:

   Class loader attribute	Description
   Delegation	Indicates whether the class loader delegates the loading of the module to its parent class loader. A value of true implies that the class loader of the parent application is being used (Classes loaded with parent class loader first). A value of false implies that the module class loader is being used (Classes loaded with local class loader first (parent last)). Refer to the Configure class loaders step for more information.
   Classpath	Lists the paths over which the class loader searches for classes and resources.
   Classes	Lists the names of classes loaded in the JVM by this class loader.

   The Table View option does not return a value when out-of-memory errors are generated. The out-of-memory errors might be related to a memory leak. To examine information about class loaders in a table, resolve the out-of-memory problem, and then click Table View again.

5. Search class loaders. On the Class loader viewer page, click Search to access the Search page, on which we can search class loaders for the following:
   • Specific strings
   • Specific .jar files
   • The names of files in a specific directory
   • The names of files loaded by a specific class loader

   The search is case-sensitive. Class loading exceptions describes several uses of the Search page.

6. Set class loaders. We can configure class loaders for the following:
   • All applications installed on a specific server
   • A specific application
   • A specific Web module

   Class loader configuration determines which class loader loads the classes and resource files for an application or Web module. Application and WAR module class loader settings include Class loader order and WAR class loader policy.

   A Class loader order value can be either Classes loaded with parent class loader first or Classes loaded with local class loader first (parent last). The default is Classes loaded with parent class loader first. A class loader with the Classes loaded with parent class loader first mode delegates loading a class or resource to its immediate parent class loader before searching its classpath.

   When troubleshooting class loading problems, we might need to override classes visible to a parent class loader. To override such classes with those specific to an application, set the Class loader order to Classes loaded with local class loader first (parent last) on the class loader that contains the application classes on its classpath. An application can override classes visible to a parent class loader, but doing so can result in a ClassCastException or UnsatisfiedLinkError if there is a mixed use of overridden classes and non-overridden classes.

   For example, under default class loader policies, a Web module has its own Web module (WAR) class loader to load its artifacts, which are typically in the WEB-INF/classes and WEB-INF/lib directories. An application module class loader is the immediate parent of this WAR class loader. To verify the Web module class loader searches these paths for a particular class or resource first, before delegating the load operation to the application module class loader, set the Class loader order of the Web module to Classes loaded with local class loader first (parent last).

   Class loader policies determine the structure of the application and WAR module class loaders. Under the default policies, every running application EAR has its own application module class loader, and every Web module has its own WAR module class loader. The default policies ensure Java EE compliance regarding visibility and isolation among application artifacts. Changing the default policies is not suggested when troubleshooting class loading problems.

 

Next steps

If we continue to have class loader problems, refer to Class loading exceptions and to Class loading.

Class loading exceptions
Class loader viewer service settings
Enterprise application topology
Class loader viewer settings
Search settings

 

Related concepts

Class loaders

 

Related tasks

Class loading
Set Web module class loaders
Diagnose problems (using diagnosis tools)

 

Related information

Demystifying class loading problems, Part 1: An introduction to class loading and debugging tools
Demystifying class loading problems, Part 2: Basic class loading exceptions
Demystifying class loading problems, Part 3: Tackling more unusual class loading problems