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:
- Go to the Download section and download the ClassLoaderViewer.zip and save it on your local machine.
- Unzip the downloaded file. This will create a top level
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
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:
- Make sure that Application Server is stopped, or the installation will not be successful.
- Back up your WebSphere configuration as follows:
<WAS_HOME>/bin/backupConfig.sh, where <WAS_HOME> is the WebSphere home directory
- Back up the directory
- 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
For all the operating systems we provide installation scripts which invoke
the PluginProcessor script automatically. These scripts can be found in the
sub-directory of the ClassLoader Viewer download.
Installing on Windows®
ClassLoaderViewer.bat file, supplying the location of your Application Server
directory. For example
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 on UNIX
With a few differences, the procedure for installing CLV on UNIX is similar to that for Windows.
- From the
/installsub-directory of the downloaded code, open the script
ClassLoaderViewer.shin 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
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.
- From the
/installsub-directory of the downloaded code, open the script
ClassLoaderViewerISeriesin 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:
- Copy the CLV code into the Integrated File System (IFS) of the iSeries system.
- Enter the Qshell using the STRQSH command.
- 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
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:
- Start the Administrative process. For example:
- Open the Application Server's administrative console in a Web browser using the default URL
- 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
Using the ClassLoader Viewer
Before displaying any ClassLoader information, you must select a J2EE module from which to view this information.
- 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
- 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
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
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
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.JarClassLoaderwithin 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
- Lists all the classes currently loaded in the JVM by this ClassLoader. The list of classes is displayed in a separate window.
- 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
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 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
The figure below shows the search results.
Figure 9. 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
Uninstalling the ClassLoader Viewer
To uninstall CLV, run the script
WAS_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
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.
|Code sample||ClassLoaderViewer.zip ( HTTP | FTP )||1.7 bMB|
- WebSphere Application Server V5.0 HandBook, SG24-6195, Chapter 17, which can be downloaded from http://www.redbooks.ibm.com
- ClassLoader discussion in the WebSphere Application Server V5 InfoCenter: http://publib.boulder.ibm.com/infocenter/wasinfo/index.jsp?topic=/com.ibm.websphere.base.doc/info/aes/ae/crun_ClassLoad.html