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 an instance of the target class (type).
This is the typical class cast exception. We can diagnose whether the source object of a cast statement is not an instance of the target class (type) by examining the class signature of the source object class, then verifying that it does not contain the target class in its ancestry and the source object class is different than the target class. We can obtain class information by inserting 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 loaded the source object (class) is different from the class loader that loaded the target class.
Assuming that the type of the source object is an instance of the target class, a class cast exception occurs when the class loader that loaded the source object's class is different that the class loader that loaded the target class. This condition might occur when the target class is visible on the classpaths of more than one class loader in the WAS runtime environment. 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 Type, select Class/Package.
  3. For Search String, type the name of the class that is loaded by two class loaders.
  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 target class was loaded by more than one class loader. Because the source object is an instance of the target class, the class loader that loaded the source object class is different from the class loader that loaded the target class.

  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 or improperly performs a narrow operation.
A class cast exception can occur because, when the application is resolving a remote enterprise bean (EJB) object, the application code does not perform a narrow operation as required. The application must perform a narrow operation after looking up a remote object. Examine the application and determine whether it looks up a remote object and, if so, the result of the lookup is submitted to a narrow method.

The narrow method must be invoked according to the EJB 2.0 programming model. In particular, the target class submitted to the narrow method must be the exact, most derived interface of the EJB. This also causes a class cast exception in the WAS runtime environment. Examine the application and determine whether the target class submitted to the narrow method is a super-interface of the EJB that is specified, not the exact EJB type; if so, modify the application to invoke narrow with the exact EJB interface.

Lastly, if a class cast exception occurs during a narrow operation, verify that the narrow method is being applied to the result of a remote EJB lookup, not to a local enterprise bean. 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.

ClassNotFoundException

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

The class is not visible on the logical classpath of the context class loader.
The class not found is not in the logical class path of the class loader associated with the current thread. The logical classpath is the accumulation of all classpaths searched when a load operation is invoked on a 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 Type, select Class/Package.
  3. For Search String, type the name of the class that is not found.
  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 application incorrectly uses a class loader API.
An application can obtain an instance of a class loader and call either the loadClass method on that class loader, or it can call Class.forName(class_name, initialize, class_loader) with that class loader. The application may be incorrectly using the class loader application programming interface (API). For example, the class name is incorrect, the class is not visible on the logical classpath of that class loader, or the wrong class loader was engaged.

To correct this problem, determine whether the class exists and whether the application is properly using the class loader API. Follow the steps in The class is not visible on the logical classpath of the context 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 Type, select Class/Package.
  3. For Search String, type the name of the class.
  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 dependent class is not visible.
When a class loader clsldr loads a class cls, the Java virtual machine (JVM) invokes clsldr to load the classes on which cls depends. Dependent classes must be visible on the logical classpath of clsldr, otherwise an exception occurs. This condition typically occurs when users make WAS classes visible to the JVM, or make application classes visible to the JVM or to the WebSphere extensions class loader. For example:

When the JVM loads class A using the WebSphere extensions class loader, it then attempts to load Class B using the same class loader and ultimately creates a class not found exception.

To correct this problem:

  1. Make the application-specific classes visible to the appropriate application 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.

[AIX HP-UX Solaris] 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.

[AIX HP-UX Solaris] To load a library named libName.so or libName.a, libName is passed to the load library.

The library is not visible.
As a best practice, use the JVM class loader to find or load native libraries. WAS prints the Java library path (java.library.path) when starting up. If the JVM class loader is intended to load the library, verify that the path containing the native library file is in the Java library path. If not, append the path to the platform-specific native library environment variable or to the java.library.path system property of the server process definition.

In general, 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 creates an UnsatisfiedLinkError exception.

Thus, if a WebSphere class loader is intended to find a native library myNativeLib, the library must be visible on the nativelibpath of the class loader that loads the class that calls System.loadLibrary(myNativeLib). This practice is necessary or desirable in the following situation:

  • Shared libraries have a Native Library Path in their configuration. Because shared libraries enable the versioning of application-specific libraries, consider specifying the paths to any native libraries used by the shared library code in the shared library configuration.

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.

[AIX HP-UX Solaris]
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 might return a file name with the wrong extension (for example, libName.so rather than libName.a). To debug this, write a program to that calls System.mapLibraryName() and verify that it returns the correct file name.
The native library is already loaded.
This condition can result from either of the following errors:
User error
Check for multiple calls to System.loadLibrary and remove any extraneous calls.
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 life cycle.

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 Java library path. This is because the JVM runs native code when loading NL; when it encounters the dependency on DNL, the JVM native code can call only to the JVM class loader to resolve the dependency. A WebSphere class loader cannot load a dependent native library.

Modify the platform-specific environment variable defining the Java library path (LIBPATH) to include the path containing the unresolved native library.