Troubleshooting
Problem
Learning more about the class loader is the first step in the troubleshooting process. This document provides you with educational information that can help you learn more about this topic.
Resolving The Problem
Tab navigation
- Learning more- selected tab,
- Troubleshooting
- Collecting data
Class loaders are responsible for loading Java classes dynamically in the JVM (Java Virtual Machine) at runtime. Classes are loaded into the JVM primarily on an as-needed basis. If a loaded class depends on another class, that dependent class is loaded as well. Failure to set up the class loading environment properly can lead to class loading exceptions (e.g. ClassNotFoundException, NoClassDefFoundError, and ClassCastException) when trying to start your JVM and/or application.
Class loading is based on three principles: Delegation, Visibility, and Uniqueness.
Delegation principle: Every class loader is created with another class loader defined as its “parent”. By default, a class loader initially forwards the request for class loading to its parent class loader. The parent delegation model is a key concept to understand when dealing with class loaders. A class loader only attempts to find a class if its parent does not return the class.
WebSphere Application Server allows users to modify this pattern, enabling a non-default pattern called “parent-last delegation”. In a parent-last class loader, the current class loader is searched before delegating the load to its parent class loader.
Visibility principle: A class loader is typically able to to access all the classes loaded by its parent class loader. The inverse is not true - a parent class loader cannot access classes loaded by its child class loader(s).
Uniqueness principle: A class with a specific package and name can only be loaded once by a class loader. This uniqueness is supported by the delegation principle, which ensures that a child class loader doesn't reload a class that is already loaded by the parent. Note that, because it does not follow the default delegation principle, parent-last delegation can lead to issues with uniqueness across parent and child class loaders.
Below is the WebSphere Application Server traditional Class Loader Hierarchy
Class Loader usage:
1) Java system loaders: These class loaders are responsible for loading core Java libraries and other items required globally at the JVM level. Class paths come from a variety of sources, including:
- JAVA_HOME/lib
- JAVA_HOME/jre/lib/ext
- Server JVM class path and bootstrap class path
- java.ext.dirs system property
- java.endorsed.dirs system property
2) OSGi Framework: The OSGi Framework class loaders load the classes from the WAS_HOME/plugins.
3) WAS Extension Class Loader: The WAS Extension Class Loader loads the classes from locations specified in the ws.ext.dirs property, non-isolated resource providers, JDBC drivers, and security extensions. Default ws.ext.dirs locations include:
- <WAS_HOME>/classes
- <WAS_HOME>/lib
- <WAS_HOME>/lib/ext
- <USER_INSTALL_ROOT>/classes
Note: The JVM and WAS server each have a class loader known as the “extension class loader”, of a type named ExtClassLoader (in separate packages). These are separate, unique extension class loaders.
4) Application Class Loaders: EJB jars, module class paths, and application library directories (e.g. EAR/lib)
5) WAR Class Loaders: WEB-INF/lib & WEB-INF/classes
The type of application and WAR class loaders is com.ibm.ws.classloader.CompoundClassLoader.
Application and WAR Module Class Loaders: By default, each application’s EAR and WAR modules have their own class loaders. The EAR loader is parent of its WARs' loaders. Applications can be configured to use a single class loader for the EAR and its WAR modules.
Separate class loaders can also be created for shared libraries. There are two types of shared library class loaders:
a) Isolated shared library loaders: If a shared library is configured with the “use an isolated class loader for this shared library” setting, a separate loader is created for the shared library. Applications or modules that reference this library will search the library class loader before searching their own class loader.
b) Server-level shared library loaders: A custom class loader can be created on a server, and non-isolated shared libraries can be associated with it. This class loader serves as a parent to all application (EAR) class loaders.
ClassLoader hierarchy view from the admin console (Class loader viewer):
Note: This Class Loader viewer is available only in WebSphere Application Server traditional.
Class Loader configuration in WebSphere Application Server
The default class loading delegation mode is parent-first. In a parent-first class loader configuration, a class loader will delegate class loading operations to its parent loader before attempting to find a class locally. Application and shared library class loaders can also be configured to use parent-last class loading delegation, in which the class loader searches locally before delegating to a parent class loader.
Note: The “Server-specific Application Settings” options can affect the behavior of all applications installed on the server. Use these settings with caution.
Class loader policy: Select whether there is a single, shared class loader for all applications installed on the server, or a separate class loader for each application. Default is Multiple.
Class loading mode: Specifies whether the class loader searches in the parent class loader or in the application class loader first to load a class. This field only applies if you set the Class loader policy field to Single. If you select Application first, your application can override classes contained in its parent class loaders, but this action can potentially result in ClassCastException or LinkageErrors if you have mixed use of overridden classes and non-overridden classes.
Class loader order: classes loaded with parent class loader first: Load and search in the parent class loader first before searching in the application class loader to load a class. This is the default option.
Classes loaded with local class loader first (parent last): Application classes load first. With this option application can override classes contained in the parent class loader, but this action can potentially result in ClassCastException or LinkageErrors if you have mixed use of overridden classes and non-overridden classes.
WAR class loader policy: Specifies whether to use a single class loader to load all WAR files of the application or to use a different class loader for each WAR file. The default is to use a separate class loader to load each WAR file.
Web Module ClassLoader settings: Applications > Application Types > WebSphere enterprise applications > application_name > Manage Modules > Web_module_instance.
Class loader order: Specifies whether the class loader searches in the parent class loader or in the application class loader first to load a class. Default is parent class loader first. By specifying Classes loaded with application class loader first, application can override classes contained in the parent class loader, but this action can potentially result in ClassCastException or LinkageErrors if you have mixed use of overridden classes and non-overridden classes.
Shared Libraries
Shared libraries are files outside an application that can be made available to applications’ class loaders, and can be used by multiple applications. Each shared library consists of a symbolic name, a Java™ class path, and a native path for loading Java Native Interface (JNI) libraries. You can use shared libraries to reduce the number of duplicate library files on your system.
Shared library configuration: You can create/configure shared libraries for any application or server.
In the administrative console page, click Environment > Shared libraries.
You can configure/create the Shared libraries at any scope cell, a node, cluster, or a server.
To associate a shared library with an application or module, use the Shared library references page for the application. Click Applications > Application Types > WebSphere enterprise applications > application name > Shared library references.
To associate a shared library with a server class loader, use the settings page for the library reference for the server class loader. Click Servers > Server Types > WebSphere application servers > server name > Java and Process Management > Class loader > class_loader_ID > Shared library references > shared_library_name.
If you come across any configuration issues you may need to check the following files.
a) server.xml
b) libraries.xml
c) deployment.xml
You can associate a shared library with an application or module. Classes represented by the shared library are then loaded in the application's class loader, making the classes available to the application.
Associating shared libraries with applications or modules
Associating shared libraries with servers
Class loader viewer
Configure Class loader viewer service settings:
Servers > Server Types > WebSphere application servers > server_name > Class loader viewer service.
The Class Loader Viewer provides an overview of the class paths and delegation order of the class loaders in your server, which can be used to aid in diagnosing and resolving problems. To use the Class Loader Viewer service, enable it on this page, then access the Class Loader Viewer in the console to examine class loaders and the classes loaded by them.
Click Troubleshooting > Class loader viewer to access the Class loader viewer in the console.
Enable service at server startup: Specifies whether or not the server attempts to start the class loader viewer service when the server starts. The default is not to start the class loader viewer service.
Parent-first search order
Parent-last search order
For a detailed explanation on classloaders, refer to the Information Center for your release. For detailed information on classloader settings, refer to Best Practice for using Common Application Files.
[{"Type":"MASTER","Line of Business":{"code":"LOB67","label":"IT Automation \u0026 App Modernization"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSEQTP","label":"WebSphere Application Server"},"ARM Category":[{"code":"a8m50000000CdLaAAK","label":"WebSphere Application Server traditional-All Platforms-\u003EClassloader-\u003EClassloader: TroubleShooting"}],"ARM Case Number":"","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"}],"Version":"8.5.5;9.0.5"},{"Product":{"code":"SSNVBF","label":"Runtimes for Java Technology"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Component":"Java SDK","Platform":[{"code":"","label":""}],"Version":"","Edition":"","Line of Business":{"code":"LOB36","label":"IBM Automation"}}]
Was this topic helpful?
Document Information
Modified date:
19 February 2024
UID
swg21242692