InfoCenter Home >
4: Developing applications >
4.7: Java Clients >
4.7.2: J2EE application client programming model >
4.7.2.4: J2EE application client classloading overview

4.7.2.4: J2EE application client classloading overview

When you run your J2EE client application using the WebSphere Application Server launchClient command, a hierarchy of classloaders is created to load classes used by your application. The parent classloader is used to load the WebSphere Application Client runtime and any classes placed in the WebSphere Application Client user directories. The directories used by this classloader are defined by the WS_EXT_DIRS System property in the product_installation/bin/setupcmdline command shell.

As the J2EE Application Client runtime initializes, additional classloaders are created as children of this parent classloader. If your client application uses resources such as JDBC, JMS, or URLs, a different classloader is created to load each of those resources. Finally, a classloader is created to load classes within the .ear file. Before invoking your client application's main method, this classloader is set as the thread's context classloader.

  The system classpath is never used and is not part of the hierarchy of classloaders.

In order to package your client application correctly, you must understand which classloader loads your classes. When Java loads a class, the classloader used to load that class is assigned to it. Any classes subsequently loaded by that class will use that classloader or any of its parents, but it will not use children classloaders.

Unfortunately, Java does not provide a good way for determining which classloader loaded your classes. This makes it difficult to debug classloading problems. See the Configuring the classpath fields section for more information on configuring the classpath fields in your application.

In some cases the WebSphere Application Client runtime can detect when your client application class is loaded by a different classloader from the one created for it by the WebSphere Application Client runtime. When that occurs, you will see 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 classloaders in the hierarchy. This is typically caused by having the same classes in the .ear file and on the hard drive. If one of the parent classloaders locates a class, that classloader will load it before the Application Client runtime classloader. In some cases, your client application will still function correctly. In most cases, however, you will receive "class not found" exceptions.

Configuring the classpath fields

When packaging your J2EE client application, you must configure various classpath 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, JMS, or URLs. In the case of these resources, you want to 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 that 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 path. Instead, use the MANIFEST Class-Path entries to refer to other classes 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 an Enterprise Java Bean, you would add the deployed EJB module's name to your application client's Classpath field in the Application Assembly Tool. The format of the Classpath 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.

    Note:   This is Java's method for allowing applications to be 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 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. 

For referencing .class files, you must specify the directory relative to the root of the .ear file. While the Application Assembly Tool allows you to add individual class files to the .ear file, it is recommended that these additional class files are packaged in a .jar file. That .jar file should then be added to the module Classpath fields. If you add .class files to the root of the .ear file, add "./" to the module Classpath fields.

Consider the following example directory structure in which the file myapp.ear contains an application client JAR file named client.jar and an EJB module called mybeans.jar. Additional classes reside in class1.jar and utility/class2.zip. 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/mybeans.jar
myapp.ear/class1.jar
myapp.ear/utility/class2.zip
myapp.ear/xyz.class

View article the 6.4.1: Setting classpaths for more information.

Referencing classes that are not in the EAR file

You have two options to reference classes that are not contained in the .ear file. Which option you choose depends on the relationship of the external classes and the classes internal to the .ear file. You might use a combination of both options. Your options are:

  1. Use the product_installation/app directory.

    Use this option when your external classes do not reference classes within the .ear file. One example would be stand-alone utility classes. To use this option, add your .jar files to the product_installation/app directory. For .class files, add them to this directory in subdirectories that correspond to the package names.

  2. If the external classes reference classes within the .ear file, the first option will not work because of the hierarchy of WebSphere classloaders. In this case, you can do one of the following:
    • Package the external classes 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.

Refer to article 6.4.1 about installing application files into the environment, and setting classpaths, for a description of the WebSphere Application Server classloaders. There are many similarities between the client and the server in this respect.

Resource classpaths

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

Using the launchClient API

If you use the launchClient shell/bat command, the WebSphere classloader hierarchy is created for you. However, if you use the launchClient API, you must perform this setup yourself. You should mimic the launchClient shell command in defining the Java system properties.

Go to previous article: Troubleshooting guide for the J2EE application client Go to next article: Java thin application client programming model

 

 
Go to previous article: Troubleshooting guide for the J2EE application client Go to next article: Java thin application client programming model