Using the WebSphere Application Server V5 ClassLoader Viewer to Simplify ClassLoaders

Java ClassLoaders have long been a source of confusion, becoming ever more complex as the language evolved. With the advent of J2EE application servers, the complexity has increased yet again. Now, potentially every application within a JVM can have its own ClassLoader hierarchy, leading to possibly dozens of ClassLoaders within a single JVM. This article shows you how to use the ClassLoader Viewer (CLV) with IBM ® WebSphere® Application Server to simplify ClassLoader complexity by allowing users to visualize the ClassLoader information real-time.

Sharad Cocasse (SharadCocasse@us.ibm.com), Staff Software Engineer, IBM

Sharad Cocasse is a member of the WebSphere Execution Team. His experience includes several years of writing object-oriented applications and developing and delivering WebSphere education to customers and IBM field technical personnel. Most recently, he has been working directly with customers to help them succeed with their use of WebSphere Application Server. Sharad holds a Masters Degree in Electrical Engineering from the University of Alabama and lives and works in Rochester, Minnesota.



Thomas Gissel (gissel@us.ibm.com), Advisory Software Engineer, IBM

Tom Gissel is a member of the WebSphere Technology Institute. In this role, he works on emerging technologies for future WebSphere releases. Formerly, Tom was team leader of the WebSphere Execution Team, where his primary responsibility was to resolve IBM customer business-critical situations involving WebSphere Application Server.



17 December 2003

Introduction

Since the inception of the Java programming language, ClassLoaders have been a source of confusion, becoming ever more complex as the language evolved. The first iteration of Java had only one ClassLoader defined by the-classpath command line parameter or CLASSPATH environment variable. For security and other reasons it was decided that having one ClassLoader load all the classes within the Java Virtual Machine (JVM) was undesirable, so Java 2 modified the ClassLoading mechanism from a flat structure to a ClassLoader hierarchy. This hierarchy consists of three specialized ClassLoaders namely, bootstrap ClassLoader, extensions ClassLoader, and application ClassLoader; each with a distinct job within the JVM. Although this improved ClassLoading, it also significantly increased its complexity. With the advent of J2EE application servers, the complexity is increased yet again, because potentially every application within a JVM can have its own ClassLoader hierarchy, leading to possibly dozens of ClassLoaders within a single JVM.

The ClassLoader Viewer (CLV) is a downloadable tool that can be installed in a WebSphere® Application Server V5 (Application Server) run-time environment. CLV simplifies ClassLoader complexity by allowing users to visualize the ClassLoader information in real-time, which resolves a lot of the confusion inherent in J2EE ClassLoading. CLV is available for all operating systems and can also be run inside the WebSphere Test Environment of WebSphere Studio Application Developer (Application Developer). With the help of CLV, you can get a detailed understanding of how the various classes have been loaded by the Application Server's Java process. CLV's output can be used to troubleshoot some of the tough ClassLoading issues faced during application development and test phases. Use CLV in production only when advised to do so by IBM Support to help debug a specific issue.

In this article, you'll learn how to install and use CLV in both Application Server and Application Developer. You'll see that CLV's functions have been integrated into WebSphere Application Server's Web-based administration client, which makes it very easy to use.

The ClassLoader Viewer is provided as-is with no guarantee of support from IBM. The authors of this article will do their best to provide support for the tool on a case-by-case basis.


Downloading the ClassLoader Viewer

First let's download the ClassLoader Viewer:

  1. Go to the Download section and download the ClassLoaderViewer.zip and save it on your local machine.
  2. Unzip the downloaded file. This will create a top level ClassLoaderViewer directory.

Installing ClassLoader Viewer

The following examples demonstrate how to install CLV in the administrative console for the Application Server Base edition. However, you can follow the same general procedure the Application Server Network Deployment edition as well. In the case of Network Deployment, CLV should be installed only on the deployment manager's node. CLV is essentially a Web Application (WAR file), which is accessible through the WebSphere administrative console. This WAR file is provided to you as part of the CLV code under the /lib sub-directory. During the installation process, this Web application is made a part of WebSphere's Web-based administrative enterprise application. The inclusion of CLV's Web application into WebSphere's administrative application is performed by the script <WAS_HOME>/bin/PluginProcessor.sh. The installation scripts that we provide for installing CLV make a call to this PluginProcessor. In the case of Application Server Network Deployment, the Web application is installed within the administrative application of the deployment manager.

Important:Before installing the ClassLoader Viewer, complete the following steps:

  1. Make sure that Application Server is stopped, or the installation will not be successful.
  2. Back up your WebSphere configuration as follows:
    1. Run <WAS_HOME>/bin/backupConfig.sh, where <WAS_HOME> is the WebSphere home directory
    2. Back up the directory <WAS_HOME>/installedApps/<node>/adminconsole.ear
  3. During the installation, the Application Server's configuration is backed up into a temporary directory. This disk space is used only during the install and is released at the end of the install. Make sure you have enough disk space to hold the Application Server's configuration. For UNIX systems, this space is needed in the /tmp directory's mount.

For all the operating systems we provide installation scripts which invoke the PluginProcessor script automatically. These scripts can be found in the /install sub-directory of the ClassLoader Viewer download.

Installing on Windows®

Run the ClassLoaderViewer.bat file, supplying the location of your Application Server directory. For example \WebSphere\AppServer as seen in the figure below. This installation file is under the /install sub-directory of the downloaded code. Please note that this process could take several minutes to complete. If there are multiple copies of Application Server on the system, this step installs CLV only on the WebSphere installation specified.

Figure 1. Installing ClassLoader Viewer on Windows
Installing ClassLoader Viewer on Windows

Installing on UNIX

With a few differences, the procedure for installing CLV on UNIX is similar to that for Windows.

  1. From the /install sub-directory of the downloaded code, open the script ClassLoaderViewer.sh in a text editor and specify the value for WAS_HOME. This variable represents Application Server's home directory where you wish to install CLV. The default value is WAS_HOME=/opt/WebSphere/AppServer, which is the default directory on Solaris and HP-UX platforms. For AIX, the default directory is /usr/WebSphere/AppServer.
  2. Run ClassLoaderViewer.sh. This process could take several minutes to complete.

Installing on iSeries

The procedure for installing CLV on an iSeries system is similar to that for UNIX-based systems.

  1. From the /install sub-directory of the downloaded code, open the script ClassLoaderViewerISeries in a text editor and specify the value for WAS_HOME. This variable represents the Application Server's home directory where you wish to install CLV. The default is: WAS_HOME=/QIBM/ProdData/WebAS5/Base.
  2. Copy the CLV code into the Integrated File System (IFS) of the iSeries system.
  3. Enter the Qshell using the STRQSH command.
  4. Run the script ClassLoaderViewerISeries. This process could take several minutes to complete.

Installing on zSeries

Installation of the CLV on zSeries is quite different than that of other operating systems. For zSeries, you have to perform several installation steps manually. You can use a JCL script like the one below as a template. This JCL is provided in the /install sub-directory of the downloaded code in the file ClassLoaderViewerZSeries.

Listing 1: Sample JCL to install ClassLoader Viewer on a zSeries system
//INSTCL
JOB (ACCOUNT),'COMMENT',CLASS=A,REGION=0M,NOTIFY=&SYSUID 
//* //* This job installs the
Class Loader plug-in. 
//* 
//INSTCL EXEC
PGM=IKJEFT01,DYNAMNBR=250,REGION=0M 
//SYSPRINT DD SYSOUT=*//SYSTSPRT DD SYSOUT=*
//STDOUT DD SYSOUT=* 
//STDERR DD SYSOUT=*
//SYSTSIN DD * 
BPXBATCH SH + 
 /WebSphere/V5R0M0/AppServer/bin/+
 PluginProcessor.sh -install
-moduleExtension + 
       /home/user1/ClassLassloaderViewer.war
> + /WebSphere/V5R0M0/AppServer/logs/classLoaderInstall.log
      //* 
			//INSTCOPY EXEC
PGM=IKJEFT01,REGION=0M
//SYSEXEC DD
DISP=SHR,DSN=WAS.V50.SBBOEXEC 
//SYSTSIN DD *BBOHFSWR +
'/WebSphere/V5R0M0/AppServer/logs/classLoaderInstall.log'

In this JCL, you'll notice that we invoke the PluginProcessor.sh script during installation. The WAR file ClassLoaderViewer.war contains the code to be installed. This WAR file is the same as that used for distributed platforms and is found under the /lib sub-directory of the installation package.

Installing on WebSphere Studio Application Developer

Application Developer V5 includes a complete Application Server runtime that can be used for test purposes. This installation is similar to the Windows version of the installation discussed in Installing on Windows.

Run the batch file ClassLoaderViewer.bat supplying the home directory of the built-in Application Server. For example: C:\download\ClassLoaderViewer\install>ClassLoaderViewer.bat <WSAD_HOME>\runtimes\base_v5, where <WSAD_HOME> is the location of your Application Developer installation.


Starting the ClassLoader Viewer

Once the installation is complete, the CLV is fully integrated into the WebSphere administrative console. To start the ClassLoader Viewer, do the following:

  1. Start the Administrative process. For example: C:\WebSphere\AppServer\bin>startServer.bat server1
  2. Open the Application Server's administrative console in a Web browser using the default URL http://localhost:9090/admin
  3. Log in to the Administrative Console and then navigate to the ClassLoader Viewer by expanding the Troubleshooting tree. Click on ClassLoader Viewer as seen in the figure below.
    Figure 2. Navigating to the ClassLoader Viewer using the administrative console
    Navigating to the ClassLoader Viewer using the administrative console

Using the ClassLoader Viewer

Before displaying any ClassLoader information, you must select a J2EE module from which to view this information.

  1. When you click the ClassLoader Viewer link, the first page displayed is a tree listing all running J2EE modules within the WebSphere Application Server cell. Navigate to the J2EE module you wish to analyze as shown in the figure below.
    Figure 3. Select the J2EE module to analyze
    Select the J2EE module to analyze
  2. You can view ClassLoader information at a J2EE module level. The module could be a Web module (WAR file) or an EJB module (JAR file). Once you've selected the WAR or JAR file, you can choose the appropriate CLV display option by clicking on it. The ClassLoader Properties page is displayed as shown in Figure 4.
    Figure 4. ClassLoader Properties
    Class Loader Properties

    Let's discuss the ClassLoader Properties options shown above.

    ClassLoader Delegation Hierarchy
    The ClassLoader Delegation Hierarchy, displays the hierarchy for delegation for the ClassLoader. The delegation hierarchy can either be PARENT_FIRST or PARENT_LAST. For more information on this, see the WebSphere V5 InfoCenter at http://publib.boulder.ibm.com/infocenter/wasinfo/index.jsp?topic=/com.ibm.websphere.base.doc/info/aes/ae/crun_ClassLoad.html. Figure 5 shows a sample delegation hierarchy for the DefaultWebApplication.war module5.

    Figure 5. ClassLoader Delegation Hierarchy for the sample Web module
    ClassLoader Delegation Hierarchy for the sample Web module

    Notice that there are two ClassLoaders with the same name in the ClassLoader Delegation Hierarchy, this ClassLoader is com.ibm.ws.ClassLoader.JarClassLoader. This means that there are actually two instances of com.ibm.ws.ClassLoader.JarClassLoader within the ClassLoader Delegation Hierarchy. The main characteristic that distinguishes one instance from another is their respective classpaths. This can better be seen in the ClassLoader Attributes view, which is discussed next.

    ClassLoader Attributes
    This view lists details about each ClassLoader being used by the J2EE module. For each ClassLoader there are up to three attributes shown:
    Delegation Mode
    This can be either True or False. TRUE implies PARENT_FIRST and FALSE implies PARENT_LAST.
    Classes
    Lists all the classes currently loaded in the JVM by this ClassLoader. The list of classes is displayed in a separate window.
    ClassPath
    Lists the classpath of this ClassLoader

    You can see attributes of every ClassLoader used by DefaultWebApplication.war in Figure 6.

    Figure 6. ClassLoader Attributes of the sample WAR module
    ClassLoader Attributes of the sample WAR module

    Click to see larger image

    ClassLoader Attributes of the sample WAR module

    The ClassLoader Attributes view is intended to provide an appealing and intuitive display of the ClassLoader information. Hhowever, there are times when you may need all the information detailed in plain HTML, without the tree structure. The ClassLoader Display view has been provided for this purpose.

    ClassLoader Display
    The ClassLoader Display view shows much of the same information as the ClassLoader Attributes view, but does so in a tabular form, which allows all the data to be shown on one page.

    Figure 7. ClassLoader Attributes of the sample WAR module - Display View
    ClassLoader Attributes of the sample WAR module- Display View

    ClassLoader Search
    The ClassLoader Search view allows you to perform three distinct searches: class and/or package names, ClassLoader names, and source JARs and directories. For instance, you search for classes containing the phrase "Buffer", any class whose name or package contains the string "Buffer" will be returned, therefore, this query would most likely return many results.

    Figure 8. ClassLoader search option
    ClassLoader search option

    The figure below shows the search results.

    Figure 9. ClassLoader search results
    ClassLoader search results

    The search is case-sensitive. For example, if the same search was performed with a typographical error such as "BuffEr" (instead of "Buffer"), there will probably not be any results returned because it's unlikely for a class or package to be named in this way.

    Save ClassLoader Information
    The final feature available within the CLV is the ability to save all the ClassLoader information to a file. The information is saved to an XML file that can be viewed in any text or XML editor. This feature has two benefits. First, it allows the administrator to view the ClassLoader information in a text editor or other application of their choice. Second, if ClassLoader problems are encountered, it allows administrators to send the information to IBM Support to aid in troubleshooting of the problem.

    Figure 10. Save the ClassLoader Viewer output
    Save the ClassLoader Viewer output

Uninstalling the ClassLoader Viewer

To uninstall CLV, run the scriptWAS_HOME/bin/PluginProcessor.sh and uninstall the plug-in com.ibm.ws.console.ClassLoader. For example:

PluginProcessor.bat -uninstall
-pluginId com.ibm.ws.console.ClassLoader

Conclusion

CLV greatly increases the application developers' and architects' ability to fully understand the functioning of ClassLoaders within WebSphere Application Server and significantly improves ClassLoader usability.


Download

DescriptionNameSize
Code sampleClassLoaderViewer.zip  ( HTTP | FTP )1.7 bMB

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=13782
ArticleTitle=Using the WebSphere Application Server V5 ClassLoader Viewer to Simplify ClassLoaders
publish-date=12172003