Java EE client application class loading

When you run the Java EE application client, a hierarchy of class loaders is created to load classes used by the 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.

• (dist)(zos) 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 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.

• (iseries) The extensions class loader is a child to the bootstrap class loader. This class loader contains JAR files in the app_server_root /java/ext directory, the java_home/lib/ext or java_home/jre/lib/ext directory, and the /QIBM/UserData/Java400/ext directory. The app_server_root directory is the product installation path. The java_home directory is your installation path for Java files.

  (iseries) Attention: The java_home parameter can be any of three values, depending on which JVM is enabled. The three possible values are:

  • /QOpenSys/QIBM/ProdData/JavaVM/jdk60/32bit (Java SE 6 32 bit)

  • /QOpenSys/QIBM/ProdData/JavaVM/jdk60/64bit (Java SE 6 64 bit)

• The system class loader contains JAR files and classes 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 loads the Application 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 app_server_root/bin/setupCmdLine script for WebSphere Application Server installations, or in the app_server_root/bin/setupClient script for client installations.

As the Java EE application client run time initializes, additional class loaders are created as children of the WebSphere class loader. If the 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 the client application correctly, you must understand which class loader loads the 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 the 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 the 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 disk 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, the client application still functions correctly. In most cases, however, you receive "class not found" exceptions.

Configure the classpath fields

When packaging your Java EE client application, configure various class path fields. Ideally, you should package everything required by the application into the EAR file. This is the easiest way to distribute the Java EE client application to the 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 disk drive. We might also have other classes installed on the client machines that we do not need to redistribute. In this case, we also want to use classpath references to access the classes on the hard disk drive, as described later in this topic.

Referencing classes within the EAR file

WebSphere product Java EE 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. For example, if the client application needs to access the path of the EJB JAR file, add the deployed enterprise bean module name to the 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 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.

: This is the Java method for allowing applications to function platform independent.

Typically, we add modules (JAR files) to the root of the EAR file. In this case, we only need to specify the name of the module (JAR file) in the Class path field. If we choose to add a module with a path, 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 an assembly tool, we 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 we 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 myclient.jar and a mybeans.jar EJB module. Additional classes reside in class1.jar and utility/class2.zip files. A class file 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/myclient.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 the client application using the Application Client Resource Configuration Tool (ACRCT), or the z/OS ACRCT scripting tool, we can specify class paths required by the resource. For example, if the 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.

On WebSphere Application Server for i5/OS , if you use the IBM Developer Kit for Java JDBC provider to access DB2/400, we 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, specify the location of the jt400.jar file.

Use the launchClient API

If we use the launchClient 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 concepts

Development and assembly tools

launchClient tool