J2EE application client class loading

J2EE application client class loading

When you run your J2EE application client, a hierarchy of class loaders is created to load classes used by your application.

This list describes the hierarchy of class loaders:

The topmost class loader, the bootstrap class loader, contains the JAR files that make up the Java virtual machine code, such as rt.jar, plus those JAR files defined by the -Xbootclasspath parameter on the Java command. The WebSphere application client run time sets this value to the WAS_BOOTCLASSPATH environment variable.

The extensions class loader is a child to the bootstrap class loader. This class loader contains JAR files in the java/jre/lib/ext directory or those JAR files defined by the -Djava.ext.dirs parameter on the Java command. The WebSphere application client run time does not set -Djava.ext.dirs parameters, so it uses the JAR files in the java/jre/lib/ext directory.

The system class loader contains JAR files and classes that are defined by the -classpath parameter on the java command. The application client run time sets this parameter to the WAS_CLASSPATH environment variable.

The WebSphere class loader class loader loads the WebSphere Application Client run time and any classes placed in the WebSphere Application Client user directories. The directories used by this class loader are defined by the WAS_EXT_DIRS environment variable. The WAS_BOOTCLASSPATH, WAS_CLASSPATH, and the WAS_EXT_DIRS environment variables are set in the installation_root/bin/setupCmdLine command shell for WAS server installations, or in the installation_root/bin/setupClient command shell for client installations.

As the J2EE application client run time initializes, additional class loaders are created as children of the WebSphere class loader. If your client application uses resources such as JDBC API, Java Message Service (JMS) API, or URL API, a different class loader is created to load each of those resources. Finally, the application client run time sets the WebSphere class loader to load classes within the EAR file by processing the client JAR manfest repeatedly. The system classpath that is defined by the CLASSPATH environment variable is never used and is not part of the hierarchy of class loaders.

To package your client application correctly, understand which class loader loads your classes. When Java loads a class, the class loader used to load that class is assigned to it. Any classes subsequently loaded by that class uses that class loader or any of its parents, but it does not use children class loaders.

In some cases the WebSphere application client run time can detect when your client application class is loaded by a different class loader from the one created for it by the WebSphere application client run time. When this detection occurs, you see the following message:

WSCL0205W: The incorrect class loader was used to load [0]

This message occurs when your client application class is loaded by one of the parent class loaders in the hierarchy. This situation is typically caused by having the same classes in the EAR file and in an alternate JAR file in a different classloader. If one of the parent class loaders locates a class, that class loader loads it before the application client run time class loader. In some cases, your client application still functions correctly. In most cases, however, you receive "class not found" exceptions.

Configure the classpath fields

When you package your J2EE client application, configure various classpath fields. Ideally, package everything required by your application into your EAR file. This is the easiest way to distribute your J2EE client application to your clients. However, not package such resources as JDBC APIs, JMS APIs, or URLs. In the case of these resources, use classpath references to access those classes on the hard drive. You might also have other classes installed on your client machines that you do not need to redistribute. In this case, you also want to use classpath references to access the classes on the hard drive, as described below.

Referencing classes within the EAR file

WebSphere J2EE applications do not use the system class path. Use the MANIFEST Classpath entry to refer to other JARs within the EAR file. Configure these values using the module Classpath fields in the application assembly tool. For example, if your client application needs to access the path of the enterprise bean JAR, add the deployed enterprise bean module name to your application client Classpath field in the application assembly tool. The format of the Classpath field for each of the different modules (application client, enterprise bean, Web) is the same:

The values must refer to JAR and class files that are contained within the EAR file.

The values must be relative to the root of the EAR file.

The values cannot refer to absolute paths in the file systems.

Multiple values must be separated by spaces, not colons or semi-colons.

Note: This is the Java method for allowing applications to function in a platform-independent way.

Typically, you add modules (JAR files) to the root of the EAR file. In this case, you only need to specify the name of the module (JAR file) in the Classpath field. If you choose to add a module with a path, you need to specify the path relative to the root of the EAR file.

When you reference class files, specify the directory relative to the root of the EAR file. With the Application Assembly Toolyou can add individual class files to the EAR file. It is recommended that these additional class files are packaged in a JAR file. Add this JAR file to the module Classpath fields. If you add class files to the root of the EAR file, add ./ to the module Classpath fields.

Consider this example. The file myapp.ear contains an application client JAR file named client.jar. Additional classes reside in class1.jar and class2.zip files. A class named xyz.class is not packaged in a JAR file but resides in the root of the EAR file. Specify class1.jar class2.zip ./ as the value of the Classpath property. (You need only name the directory for class files, which in this case is the root.)

Referencing classes that are not in the EAR file

Use the launchClient -CCclasspath parameter. This parameter is specified at run time and takes platform-specific classpath values, which means multiple values are separated by semi-colons or colons. There are many similarities between the client and the server in this respect. For more information, see The launchClient script.

Resource classpaths

When you configure resources used by your client application with the Application Client Resource Configuration Tool, you can specify classpaths that are required by the resource. These classpath values are platform-specific and require semi-colons or colons to separate multiple values.

Use the launchClient API

If you use the launchClient shell and bat command, the WebSphere class loader hierarchy is created for you. However, if you use the launchClient API, perform this setup yourself. You should mimic the launchClient shell command in defining the Java system properties. For more information, see The launchClient script.