Where to put common ("utility") classes in releases of WebSphere Application Server V4.0
 Technote (FAQ)
 
Problem
WebSphere® Application Server administrators and developers often ask where to put common classes or shared library "utility" Java™ archive (JAR) files. This document helps clarify this issue.
 
Solution
You have common classes (which are in a "utility" JAR file) and want to know where to put the "utility" JAR file. To truly be a "utility" JAR, this JAR cannot depend on any classes within your application. The answer will depend on the following questions:
  1. Where are the classes that depend on the common classes or shared library JAR files?
    • Are they located within the same enterprise archive (EAR) file or within separate EAR files?
    • Are they located in the same Java virtual machine (JVM™) (application server) or multiple JVMs?

  2. Will multiple versions of these utility JARs be maintained for use by different applications installed on the same node (for example: one set of applications uses version A of the classes while another set of applications uses version B of the classes)? If yes, are these applications deployed in the same or different application servers?

  3. Does the utility JAR have dependencies on "WebSphere/J2EE APIs"? For example, does it depend on javax.servlet.ServletRequest found in install_root\lib\j2ee.jar?


In order to understand the options presented in this document, it is necessary to have an understanding of the different classloaders in WebSphere. Read the following document focusing on the The classloaders and their search orders section:

http://www.software.ibm.com/wsdd/WASInfoCenter/infocenter/wasa_content/rnclassholders.html


After reading the preceding article, it is important to remember the following picture and understand the classloader visibility:

"The relationship among the classloaders represents the fact that classes loaded by a particular classloader can reference other classes as long as these other classes can be loaded by the same classloader or any of its ancestors (but not its children).

After a class is loaded, its scope is everything in scope for its classloader plus everything that is in scope for its parent classloader. Scope does not extend downward in the classloader hierarchy."

In the above hierarchy, the JVM runtime classloader is the parent of all classloaders. A few examples of visibility follow:
  • Classes loaded by the JVM runtime classloader do not have visibility to any classes loaded by any of the other classloaders.
  • Classes loaded by the WebSphere runtime classloader only have visibility to classes loaded in the same classloader or its parent, JVM runtime classloader.
  • Classes loaded by the Application extensions classloader only have visibility to classes loaded in the same classloader or its parent classloaders, WebSphere runtime classloader and JVM runtime classloader.
  • Classes loaded by the Application classloaders only have visibility to classes loaded in the same classloader or its parent classloaders: Application extensions classloader,WebSphere runtime classloader, and JVM runtime classloader.

For the remainder of this document, "WAR" will refer to WebModule and "EAR" will refer to Enterprise Applications.

The following chart lists the possible locations that you can place the "utility" JAR based upon the answers to questions 1, 2, and 3 at the beginning of this document.

Note the following designations for the graph below
XX = preferred location
X = possible location
X1 = possible location that requires multiple copies of the same version of the "utility" JAR being maintained (for example: the same JAR is going to be deployed in multiple EAR files)
X2 = possible location that is only an option when all of the EARs deployed to a JVM depend on the same version of the "utility" JAR



How the location of the "utility" JAR affects which classloader loads the classes

The following chart illustrates how the location of the "utility" JAR file affects which classloader the classes will be loaded in:

Location of "utility" JAR Classloader that will load the classes
Root of each EAR file Application classloader
install_root\lib\app Application extensions classloader
ws.ext.dirs WebSphere runtime classloader
Classpath of each JVM JVM Runtime classloader


How to add the "utility" JAR to the root of the EAR file

Use the Application Assembly Tool (AAT). Ensure that you reference this JAR file in the MANIFEST Class-Paths of any EJB JARs and WAR files that depend on the "utility" JAR.


How to add the "utility" JAR to install_root\lib\app

Simply copy the JAR file to the install_root\lib\app directory. The Application Extensions Classloader will automatically pick it up. Each JVM that needs to use the JAR file will need to be restarted for the changes to take effect.

How to put the "utility" JAR on the classpath of the JVM

  1. Open up the administrative client
  2. Navigate to the Application Server (JVM) that you want to add the classpath to.
  3. Click on the JVM Settings tab.
  4. Click Add under the Classpaths section.
  5. Enter a fully qualified path to the JAR file.
  6. Click apply.
  7. Restart the application server for the changes to take effect.





How to add the "utility" JAR to ws.ext.dirs

Note: The value for ws.ext.dirs only needs to be a directory name and should not contain the JAR file. The classloader will pickup all JARs in that directory. Furthermore, the value specified is appended to the current ws.ext.dirs value.
  1. Open up the administrative client.
  2. Navigate to the Application Server (JVM) that you want to add the classpath to.
  3. Click on the JVM Settings tab.
  4. Click Add under the System Properties section.
  5. Enter ws.ext.dirs for the name and then enter the directory where the JARs are located for the value.

    For example: The JAR is named utility.jar and is located in the directory D:\Utility_classes. Name=ws.ext.dirs and value=D:\Utility_classes

  6. Click apply.
  7. Restart the application server for the changes to take effect




Can I modify ws.ext.dirs in the admin.config?

The name ws.ext.dirs is also configured in the admin.config file in the com.ibm.ejs.sm.util.process.Nanny.adminServerJvmArgs property. It is set as a -D command line argument (-Dws.ext.dirs=). It is not recommended that you make any changes to this entry. All additions to the ws.ext.dirs should be made at the JVM (application server) level through a system property.
 
 
 


Document Information


Product categories: Software > Application Servers > Distributed Application & Web Servers > WebSphere Application Server > Classloader
Operating system(s): HP-UX
Software version: 4.0.7
Software edition:
Reference #: 1112925
IBM Group: Software Group
Modified date: Jan 31, 2005