J2EE application client class loading: WAS v5.1

J2EE application client class loader hiearchy

Class loader Description
Bootstrap JAR files that make up the JVM 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.
Extensions 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.
System JAR files and classes that are defined by the -classpath parameter on the java command.
The WebSphere application client run time sets this parameter to the WAS_CLASSPATH environment variable.
WebSphere Loads the WebSphere application client run time and any classes placed in the WebSphere application client user directories.
The directories used are defined by the WAS_EXT_DIRS environment variable.
WAS_BOOTCLASSPATH, WAS_CLASSPATH, and the WAS_EXT_DIRS environment variables can be set using...
$WAS_INSTALL/bin/setupCmdLine.sh

...for WAS installations, or using...
$WAS_INSTALL/bin/setupClient

...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, JMS, or URL, 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 manifest repeatedly. The system class path, 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 the Java code loads a class, the class loader used to load that class is assigned to it. Any classes subsequently loaded by that class will use that class loader or any of its parents, but it will 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 on the hard drive. 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.

Configuring the classpath fields

When packaging your J2EE client application, configure various class path 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, you should not package such resources as JDBC APIs, JMS APIs, or URLs In the case of these resources, use class path 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 product J2EE applications do not use the system class path. Use the MANIFEST Class path entry to refer to other JAR files within the .ear file. Configure these values using the module Class path fields in the Application Assembly Tool. For example, if your client application needs to access the path of the EJB JAR file, add the deployed enterprise bean module name to your application client Class path field in the Assembly Tool. The format of the Class path field for each of the different modules (Application Client, EJB, 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.

This is the Java method for allowing applications to function platform independent.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 Class path 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.
For referencing .class files, specify the directory relative to the root of the .ear file. With the Assembly Tool you 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 Class path fields. If you add .class files to the root of the .ear file, add ./ to the module Class path fields.

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 class path values, which means multiple values are separated by semi-colons or colons. The client and the server are similar in this respect.

Resource class paths

When you configure resources used by your client application using the Application Client Resource Configuration Tool, you can specify class paths that are required by the resource. For example, if your application is using a JDBC to a DB2 database, add db2java.zip to the class path field of the database provider. These class path values are platform-specific and require semi-colons or colons to separate multiple values.

Using the launchClient API

If you use the launchClient, the WebSphere class loader hierarchy is created for you. However, if you use the launchClient API, perform this setup yourself. Copy the launchClient shell command in defining the Java system properties.

See Also
launchClient tool

Class loader	Description
Bootstrap	JAR files that make up the JVM 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.
Extensions	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.
System	JAR files and classes that are defined by the -classpath parameter on the java command. The WebSphere application client run time sets this parameter to the WAS_CLASSPATH environment variable.
WebSphere	Loads the WebSphere application client run time and any classes placed in the WebSphere application client user directories. The directories used are defined by the WAS_EXT_DIRS environment variable. WAS_BOOTCLASSPATH, WAS_CLASSPATH, and the WAS_EXT_DIRS environment variables can be set using... $WAS_INSTALL/bin/setupCmdLine.sh ...for WAS installations, or using... $WAS_INSTALL/bin/setupClient ...for client installations.