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.

The following list describes the hierarchy of class loaders:

The Application Client for WebSphere Application Server (Application Client) run time sets this value to the WAS_LOGGING environment variable.
The extensions class loader 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 Application Client client run time does not set -Djava.ext.dirs parameters. So it uses the JAR files in the java/jre/lib/ext directory.
Note: For WebSphere Application Server for OS/400, the class loader contains JAR files in the install_root/java/ext directory, the java_home/lib/ext directory, and the /QIBM/UserData/Java400/ext directory. install_root is your product installation path. The default location is /QIBM/ProdData/WebSphere/AppServer/V6/edition. java_home is your installation path for Java files. The default location is /QIBM/ProdData/Java400/jdk14/lib/ext.
The system class loader 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 Application Client client run time and any classes placed in the 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 WebSphere Application 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 Java DataBase Connectivity (JDBC) API,
Java Message Service (JMS) API, or Uniform Resource Locator (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 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 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, you should 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 an assembly tool such as the Application Server Toolkit (AST) or Rational Web Developer. 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. 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 semicolons.

Note: 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 Application Server Toolkit (AST) or Rational Web Developer, you can add individual class files to the .ear file. IBM recommends 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. Consider the following example directory structure in which the file myapp.ear contains an application client JAR file named client.jar and a mybeans.jar EJB module. Additional classes reside in class1.jar and utility/class2.zip files. A class named xyz.class is not packaged in a JAR file but is in the root of the EAR file. Specify ./ mybeans.jar utility/class2.zip class1.jar as the value of the Classpath property. The search order is: myapp.ear/client.jar myapp.ear/xyz.class myapp.ear/mybeans.jar myapp.ear/utility/class2.zip myapp.ear/class1.jar

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.

Note: On WebSphere Application Server for OS/400, if you use the IBM Developer Kit for Java JDBC provider to access DB2/400, you do not have to add the db2_classes.jar file to the class path. However, if you use the IBM Toolbox for Java JDBC provider, you do need to specify the location of the jt400.jar file.

Using the launchClient API

If you use the launchClient script and bat command, 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.

Related reference
launchClient tool