WebSphere Application Server - Express, Version 6.0.x     Operating Systems: AIX, HP-UX, Linux, Solaris, Windows

Class loading exceptions

What kind of class-loading error do you see when you develop an application or start an installed application?

ClassCastException

A class cast exception results when the following conditions exist and can be corrected by the following actions:

The type of the source object is not same as the type of the target object.
You can diagnose a mismatch in the types of source and target objects using a simple print statement in your code. For example:
System.out.println( source.getClass().getName() + “:” + target.getClass().getName() );
Or use a javap command. For example:
javap java.util.HashMap
Compiled from "HashMap.java"
public class java.util.HashMap extends java.util.AbstractMap
             implements java.util.Map,java.lang.Cloneable,java.io.Serializable {
The class loader that loads the source object is different from the class loader that loads the target object.
A class cast exception results when two different class loaders load a particular class. To correct this problem, use the Search and Search by Class Name console pages used to diagnose problems with class loaders:
  1. Click Troubleshooting > Class Loader Viewer > module_name > Search to access the Search page.
  2. For Search String, type the name of the class that is loaded by two class loaders.
  3. For Search Type, select Class/Package.
  4. Click OK. The Search by Class Name page is displayed, listing all class loaders that load the class.

    If there is more than one class loader listed, then the class loader that loads the source object is different from the class loader that loads the target object.

  5. Return to the Class Loader Viewer page and examine the classpath to determine why two different class loaders load the class.
  6. Correct your code so that the class is visible only to the appropriate class loader.
The application fails to perform a narrow operation.
If the class cast exception occurs during a narrow operation in the code, verify that the narrow operation is properly used for a remote lookup. A narrow is not used for local lookups. Examine the application or module deployment descriptor to ensure that the object being narrowed is not a local object.

A class cast exception can occur because, when the application is caching a resolved enterprise bean (EJB) object, the application code does not perform a narrow operation as required. The code must perform a narrow operation after looking up a remote object. Examine your code to determine if it looks up a remote object and, if so, a narrow operation follows.

The code attempts to override a class provided by WebSphere Application Server.

A class cast exception also can occur because the code attempts to override a class provided by WebSphere Application Server. To correct this problem, use the Search and Search by Class Name console pages:

  1. Click Troubleshooting > Class Loader Viewer > module_name > Search to access the class loader Search page.
  2. For Search String, type the name of the class that is loaded by two class loaders.
  3. For Search Type, select Class/Package.
  4. Click OK. The Search by Class Name page is displayed, listing all class loaders that load the class.
  5. See which class loaders load the class. There may be more than one.
  6. Return to the Class Loader Viewer page and examine the classpath of the class loader.
  7. If the overridden .jar file is not in the classpath before the .jar file to be overridden, change the Class loader mode setting on the console enterprise application settings page to Parent Last. This enables the appropriate class loader to load the class in the desired order.

Class-loader modes provides information on the Parent First and Parent Last values for Class loader mode.

The context class loader at the time of the class cast exception is not correct.
An application class can cause a class cast exception by modifying the context class loader and then loading a class or resource. Third party code providers, such as Jakarta Commons Logging, typically do this, unexpectedly circumventing the class loading sequence specified by the class loader polices and modes and ultimately causing a class cast exception. The fix for this problem depends on the intent of your application. As to Jakarta Commons Logging, the intent is to override the logging factory packaged with WebSphere Application Server. If a search of the application-specific LogFactory class yields no results, the class is not loaded. Other classes packaged with the application are loaded

To correct this problem, check your class-loader settings on a console enterprise application settings page. Set the application Class loader mode to Parent Last and WAR class loader policy to Application . Class-loader modes provides information on the Parent First and Parent Last values for Class loader mode. WAR class-loader policy provides information on the Application and Module values for WAR class-loader policy.

  1. Click Troubleshooting > Class Loader Viewer > module_name > Search to access the class loader Search page.
  2. For Search String, type the name of the class that generated the class cast exception.
  3. For Search Type, select Class/Package.
  4. Click OK. The Search by Class Name page is displayed, listing all class loaders that load the class.
  5. See which class loaders load the class.
  6. Return to the Class Loader Viewer page, examine the classpaths of the class loaders, and determine which classes the class loaders load.
  7. Change the Class loader mode setting on the console enterprise application settings page to enable the appropriate class loader to load the class that generated the exception.

Class-loader modes provides information on the Parent First and Parent Last values for Class loader mode.

ClassNotFoundException

A class not found exception results when the following conditions exist and can be corrected by the following actions:

The class not found is not the path of the current class loader.
The class not found is not in the logical class path of the class loader. To correct this problem, use the Search page to search by class name and by Java archive (JAR) name:
  1. Click Troubleshooting > Class Loader Viewer > module_name > Search to access the class loader Search page.
  2. For Search String, type the name of the class that is not found.
  3. For Search Type, select Class/Package.
  4. Click OK. The Search by Class Name page is displayed, listing all class loaders that load the class.
  5. Examine the page to see if the class exists in the list.
  6. If the class is not in the list, return to the Search page. For Search String, type the name of the .jar file for the class; for Search Type, select JAR/Directory.
  7. Click OK. The Search by Path page is displayed, listing all directories that hold the JAR file.

If the JAR file is not in the list, the class likely is not in the logical class path, not readable or an alternate class is already loaded. Move the class to a location that enables it to be loaded.

The class is loaded by a child class loader while the application uses its parent class loader.
An application can obtain a context class loader and call a loadClass method on that class loader. If the application calls a Class.forName(class_name, initialize, class_loader) application programming interface (API), the application might be using the wrong class loader for the current context.

To correct this problem, determine whether the class exists and whether the proper API is used. Follow the steps in The class not found is not the path of the current class loader to determine whether the class is loaded. If the class has not been loaded, attempt to correct the application and see if the class loads. If the class is in the class path with proper permission and is not being overridden by another factory class, examine the API used to load the class.

  1. Click Troubleshooting > Class Loader Viewer > module_name > Search to access the class loader Search page.
  2. For Search String, type the name of the class.
  3. For Search Type, select Class/Package.
  4. Click OK. The Search by Class Name page is displayed, listing all class loaders that load the class.
  5. Examine the page to see if the class exists in the list.
  6. If the class is in the list and a ClassNotFound exception was thrown, then the .jar file or class is not in the correct context or a wrong API call in the current context was used.
    If the class is not in the list, return to the Search page and do the following:
    1. Search for the class that generated the exception; that is, the class calling Class.forName.
    2. See which class loader loads the class.
    3. Determine whether the class loader has access or can load the class not found by evaluating the class path of the class loader.
A class dependent on the current class is not visible to the parent class loader.
For a dependent class to be accessible, the dependent class must be visible to the parent class loader. Dependent classes are not visible when users make WebSphere Application Server classes visible to the Java virtual machine (JVM) or make application classes visible to the JVM or to the WebSphere extensions class loader. For example:
  • Class A depends on Class B.
  • Class A is visible to the WebSphere extensions class loader.
  • Class B is not visible to the WebSphere extensions class loader.
  • When Class A tries to load Class B, a class not found exception occurs.

To correct this problem:

  1. Move the classes away from the JVM or WebSphere extensions class loader.
  2. Search for the class not found (Class B).
  3. If Class B is in the proper location, search for the class that loads the dependent class (Class A) in the Class Load Viewer.
  4. If the class is loaded and a ClassNotFound exception was thrown, then the .jar file or class is not in proper context or the wrong API call in the current context was used.
    If no class was found, do the following:
    1. Search for the class that generated the exception; that is, the class calling Class.forName.
    2. See which class loader loads the class.
    3. Determine whether the class loader has access or can load the class not found by evaluating the class path of the class loader.
  5. Ensure that the caller class (Class B) is visible to the JVM or WebSphere extensions class loader.

NoClassDefFoundException

A no class definition found exception results when the following conditions exist and can be corrected by the following actions:

The class is not in the logical class path.
Refer to ClassNotFoundException for information.
The class cannot load.
There are various reasons for a class not loading. The reasons include: failure to load the dependent class, the dependent class has a bad format, or the version number of a class.

UnsatisfiedLinkError

A linkage error results when the following conditions exist and can be corrected by the following actions:

A user action caused the error.

Several user actions can result in a linkage error:

A library extension name is incorrect for the platform.

[Windows]A library has the dynamic link library name library_name.dll.

[UNIX]A library has the name library_name.so or library_name.a.

System.loadLibrary is passed an incorrect parameter.

[Windows]To load a dynamic link library named Name.dll, Name has to be passed to a loadLibrary call.

[UNIX]To load a library named libName.so or libName.a, libName is passed to the load library.

System.mapLibraryName returns the wrong library file.
When loading a shared library, JVM calls mapLibraryName(libName) to convert libName to a platform specific name. On UNIX systems, this call sometimes returns files with a similar name and the wrong extension. To debug this, write a program to test this condition or search for a duplicate file name.
The JVM class loader is intended to find or load a library.
WebSphere Application Server prints java.library.path when starting up. Verify that the correct WebSphere class loader is intended to load a library. If WebSphere class loaders are intended to load a library, then define the proper scope for nativelibpath.

The Java virtual machine invokes findLibrary() on the class loader xxx that loads the class that calls System.loadLibrary(). If xxx.findLibrary() fails, the Java virtual machine attempts to find the library using the JVM class loader, which searches the JVM library path. If the library cannot be found, the Java virtual machine throws an UnsatisfiedLinkError.

Ensure that the correct WebSphere class loader loads the class that calls System.loadLibrary() and that the native library is visible on the Native Library Path setting.

The native library is already loaded.
This condition can result from either of the following errors:
User error
Check for multiple System.loadLibrary and remove any extraneous reference.
Error when an application restarts
Invoke System.loadLibrary() within the static initialization of a class within a server-scoped shared library:
  1. Remove all instances of the System.loadLibrary(MyNativeLib) call from the application source code.
  2. Create a new class named LibLoader that calls System.loadLibrary(MyNativeLib) within a static block. For example:
    public class LibLoader {
       static {System.loadLibrary(MyNativeLib);}
       public LibLoader();
    }
  3. Create a server-scoped shared library.
    1. Create a shared library, set its scope to server, and name it MySharedLib.
    2. Go to the settings page for the shared library.
    3. Set Classpath to the path containing the class LibLoader.
    4. Set Native Library Path to the path containing the native library MyNativeLib.
    5. Create a class loader on the server hosting the application.
    6. Associate MySharedLib to the new server class loader. Refer to step 2 in Associating shared libraries with servers.
  4. Save your changes.
  5. Redeploy the application and rerun the scenario.

Classes within server-scoped libraries are loaded once for each server lifecycle, ensuring that the native library required by the application is loaded once for each Java virtual machine, regardless of the application’s lifecycle.

A dependent native library was used.
Dependent native libraries must be found or loaded by the JVM class loader. That is, if a native library NL is dependent on another native library, DNL, the JVM class loader must find DNL on the JVM library path. This is because the Java virtual machine executes native code when loading NL; when it encounters the dependency on DNL, the JVM native code can only call to the JVM class loader to resolve the dependency. A WebSphere class loader cannot load a dependent native library.

Modify the java.library.path system property, or the platform-specific environment variable, to include the path containing the unresolved native library.




Related concepts
Class loaders

Related tasks
Class loading
Troubleshooting class loaders

Related reference
Class loader viewer settings
Enterprise application topology
Search settings
A web resource does not display
Errors starting an application

Reference topic    

Terms of Use | Feedback

Last updated: Jun 8, 2005 12:45:23 PM EDT
http://publib.boulder.ibm.com/infocenter/wasinfo/v6r0/index.jsp?topic=/com.ibm.websphere.express.doc/info/exp/ae/rtrb_classload_viewer.html

© Copyright IBM Corporation 2005. All Rights Reserved.
This information center is powered by Eclipse technology. (http://www.eclipse.org)