This article was originally published in March, 2002.

IBM® Rational® PurifyPlus® is a multifunctional runtime analysis package with extensive support for testing Java applications for memory and performance problems as well as for code coverage during testing. PurifyPlus consists of three tools, each addressing one of the aspects of runtime analysis: Rational Purify (memory profiling), IBM® Rational® Quantify® (performance profiling), and IBM® Rational® PureCoverage® (code coverage analysis).

PurifyPlus collects profiling and coverage information from the Java Virtual Machine (JVM) used by the Java application server. It supports all Sun Java 2-compatible virtual machines.

This document gives detailed instructions on running your Java application server with PurifyPlus, as well as some general tips on using each of the tools. It also gives examples of using each of the tools to profile some J2EE demo applications. The four main parts are as follows:

• Part 1: Setting up the Java environment for profiling
• Part 2: Running the PurifyPlus tools
• Part 3: Examples of PurifyPlus usage
• Part 4: Information on specific Java application servers

Part 1: Setting up the Java environment for profiling

This part contains general information about how to set up your Java application server to run with the PurifyPlus tools.

Before you start collecting data

Before collecting data with PurifyPlus, you should do the following:

• Make sure the Java application server is installed and that your application is running correctly without the Rational PurifyPlus tools engaged.
• Download and install on the machine that hosts the Java application server the latest version of Rational PurifyPlus, or contact Technical Support for the latest proto build available. You'll need to have at least PurifyPlus v2002 installed.

Running profiling tools with Java application servers can decrease the performance of the server application. This is because collecting profiling information requires the JVM to run in profiling mode with the profiling tools attached to the JVM Profiling Interface, a mode of operation that slows down the JVM. Memory usage of the major industrial Java application servers is immense even when running without the profiling tools attached, and the profiler will increase the memory footprint significantly. Here are some suggestions to minimize the performance hit:

• Make sure you have at least 512 MB of physical memory installed on the profiling machine, as well as 1+ GHz CPU. In general, the profiling machine should be approximately four times better than the typical production system.
• Stop or disable all unnecessary processes (such as anti-virus real-time scanners) running concurrently with the Java application server and Rational PurifyPlus.
• When collecting the profiling and coverage information for the server application, make sure to perform the tests after the server application is fully initialized.
• Monitor the memory and CPU usage on the Windows Task Manager and proceed with testing when the CPU usage for the process java.exe drops to 0.

Most application servers can be configured to run in two modes: as a Windows service or as a standalone process. The latter is highly recommended for use with PurifyPlus.

Important note! Never do profiling on a production server. This may open a huge hole in the server security.

Four steps to use PurifyPlus with a Java application server

To successfully collect profiling and coverage information on the J2EE components running on the server side, you must complete the following four steps:

1. Make sure the JAVA_HOME system environmental variable is set and pointing to the Java Runtime Environment (JRE) directory of the JVM that's going to be used by the Java application server.
2. Automatically update the JRE directory with PurifyPlus binaries by executing the appropriate utility (pstart, qstart, or cstart) with the option /setup from the home directory of the PurifyPlus tool you'll be using. For example: pstart /setup
3. Update the Profile.ini file of the selected PurifyPlus tool with the list of prefilters for your Java application server.
4. Start the Java application server with PurifyPlus.

Further details on each of these steps are given below.

Steps 1 and 2: Setting up the JVM runtime environment

The Java environment used for running the Java application server needs to be updated in order to allow the PurifyPlus tools to attach to the running Java process and collect memory profiling information from the JVM. The JRE can be updated by running the pstart, qstart, or cstart utility with the option /setup. It will read the path set in the system environmental variable JAVA_HOME, copy the Rational PurifyPlus add-ins into the JRE directories, and update the java.policy file with grants to execute functions from the Rational add-in.

Here's an example of setting up the JVM of the BEA WebLogic Java application server to run with PurifyPlus.

1. Set the system environmental variable with Control Panel > System Settings > Advanced > Environmental Variables.
2. Set up the JRE with the Quantify utility qstart.

Note that this utility won't return any confirmation of successful execution. You can check whether the environment is set correctly by opening the java.policy file in the directory JRE/lib/security. It should have the following section added at the end of the file:

/* RATIONAL SOFTWARE. BCI grant */
/* DO NOT EDIT BELOW THIS LINE */
grant {
   permission java.lang.RuntimePermission "loadLibrary.QProfJ";
   permission java.io.FilePermission 
   "C:/bea/jdk131/jre/lib/ext/x86/QProfJ.dll", "read";
};

Additionally, QProfJ.dll will be copied into the JRE/lib/ext/x86 directory and the Rational.jar package added to the JRE/lib/ext directory.

This step has to be performed in case the Java application server is installed on the system after PurifyPlus, or if the default JVM for the system is changed after PurifyPlus installation, or if the Java application server doesn't use the default JVM.

Note that if the %JAVA_HOME%\lib\ext and %JAVA_HOME%\\lib\ext\x86 folders aren't created by the installation script of the Java SDK, the directories must be added manually before updating the JRE.

Step 3: Updating the prefilter list for PurifyPlus tools

PurifyPlus has two ways of excluding profiling and coverage data for certain Java packages:

• By removing the profiling and coverage data for Java packages or methods in the Filter Manager after data is collected.
• By creating a list of Java packages for prefiltering. PurifyPlus tools won't collect profiling or coverage data for the packages in the prefilter list.

Prefiltering Java packages is much more effective than just filtering, and it also significantly increases the performance of the run in PurifyPlus. Each of the three PurifyPlus tools stores the list of prefilters in the file called Profile.ini in its home directory. New filters have to be added manually to the \[PreFilters\] section, as shown in Figure 1.

Figure 1: The \[PreFilters\] section of the Profile.ini file

Prefilters are listed in Part 4 for each of these major Java application servers and JSP and servlet engines:

• IBM WebSphere 4
• BEA WebLogic 6.1
• Apache Jakarta Tomcat 4
• Sun J2EE SDK 1.3.1
• Silverstream 3.7

Make sure the list in the \[PreFilters\] section of the Profile.ini file of the PurifyPlus tool you're going to use includes all the prefilters for the appropriate application server or engine. If one or more of the prefilters for your particular application server or engine aren't on the list in the Profile.ini file of the PurifyPlus tool you're going to use, open the Profile.ini file and append them to the list manually. (Note: When listing a Java package, don't forget to add the dot \["."\] at the end of the string if you want to exclude the subpackages as well.)

Putting the java., javax., and sun. packages on the list helps with test performance, but adding these modules can affect Call Graph View results. If you're using Call Graph View for detailed analysis, remove these packages from the prefilter list. You can also add to the list any other Java packages that you don't want to collect any profiling or coverage data from.

Step 4: Starting a Java application server with PurifyPlus

You can start a Java application server with PurifyPlus in any of four ways, described here. Details relevant to particular servers are given later, in Part 4.

From the command line

Use the following commands to start each of the PurifyPlus tools with the Java application server from the command line:

Purify /java startserver.bat
Quantify /java startserver.bat
Coverage /java startserver.bat

where startserver.bat is the batch file for starting the Java application server.

From the PurifyPlus GUI

The Java application server doesn't have to be started from the command line. To start a Java application server from the PurifyPlus GUI, the executable for the run should be the utility pstart, qstart, or cstart from the home directory of the PurifyPlus tool you'll be using. The working directory should be the directory of the startup batch file. In the example shown in Figure 2, it's E:\WebSphere\AppServer\bin.

Figure 2: Starting WebSphere from the PurifyPlus GUI

Finally, specify the batch file for starting the server, in the "Command-line arguments" field, and specify the kind of data you want to collect.

From the startup batch file

To start a Java application server with PurifyPlus from the startup batch file, you'll need to add one line to the batch file that will set up the environmental variable for the JVM. For the Sun Java implementation, this command line is

SET _JAVA_OPTIONS=-XrunPureJVMPI:Tool

where Tool is either purify, quantify, or coverage, depending on the type of runtime analysis you want to perform.

For the IBM WebSphere implementation, the command line is

SET IBM_JAVA_OPTIONS=-XrunPureJVMPI:Tool

Figure 3 is an example of starting Quantify with BEA WebLogic 6.1 from the startup batch file.

Figure 3: Starting Quantify from the batch file

(click here to enlarge)

Automatically, with every Java application

PurifyPlus can also be permanently integrated with the default JVM by setting up a new system environmental variable for the JVM. This technique is recommended for profiling Java application servers running as Windows services.

To set this option for the Sun Java implementation, choose Settings > Control Panel > System > Advanced > Environmental Variables and create a new environmental variable by entering the command line

SET _JAVA_OPTIONS=-XrunPureJVMPI:Tool

where Tool is either purify, quantify, or coverage, depending on the type of runtime analysis that you want to perform.

For the IBM WebSphere implementation, the command line is

SET IBM_JAVA_OPTIONS=-XrunPureJVMPI:Tool

Back to top

Part 2: Running the PurifyPlus Tools

This part gives tips on running each of the three PurifyPlus tools, as well as information about using the PureAPI functions.

Rational Purify tips

Rational Purify is a memory-profiling tool. Like Rational PureCoverage and Rational Quantify, it collects information about the Java process by listening to events executed by the JVM.

Changing the instrumentation level to reduce Purify's memory needs

To reduce Purify's memory footprint, decrease the default instrumentation level to Function. Purify will still provide comprehensive information about the memory usage of the analyzed application, but its performance during the data collection phase will be much better. This option is mandatory for running Purify with IBM WebSphere 4; it can be entered from the command line or through the Purify GUI.

The command-line option for specifying Function as the default instrumentation level is

-PurifyDefaultInstrumentationType=Function

For example, to start WebSphere 4 with Purify from the command line you would execute the following command:

purify /java /PurifyDefaultInstrumentationType=Function startServer.bat

When the application server is started through the Purify GUI, this option can be added to the executable settings for the run, under "Additional options" on the Files tab, as shown in Figure 4.

Figure 4: Setting the default instrumentation level to Function through the GUI

In PurifyPlus v2002, this option when entered through the Purify GUI won't be displayed in the "Additional options" edit box even though the program has accepted it. Consequently, Java applications will be profiled with this option without warning the user. This defect will be fixed in future releases.

To remove this option manually, open the ASCII file pstart_pure.ini from the home directory of Purify and delete the line with this option, as shown in Figure 5.

Figure 5: Line that sets the instrumentation type in the pstart_pure.ini file

If this option is set in the Purify default settings, the ASCII file containing this additional option is located under Drive\Documents and Settings\user\Application Data\Rational\Purify; the name of the file is purifyw_pure.ini.

Setting options for object-level profiling

Memory profiling in Purify can be modified and fine tuned with a set of Purify options for manipulating the dataset collected for object-level profiling. Here's a list of the options, set to their default values:

• -MEMPROF_OBJECT_DUMP=ON
• -MEMPROF_OBJECT_DUMP_ALL=OFF
• -MEMPROF_OBJECT_GCAGE=ON
• -MEMPROF_OBJECT_CREATETIME=ON
• -MEMPROF_HEAP_DUMP_ON_EXIT=ON
• -MEMPROF_HEAP_DUMP_ON_SNAPSHOT=ON

These options are valid only for PurifyPlus v2002 and v2002A Beta-1. The names of the options and their descriptions will change for the release version of PurifyPlus 2002A.

These options can be set in the command line or entered in the executable settings or the default settings for the run, as shown in Figure 6.

Figure 6: Entering memory-profiling options in the default settings for the run

If taking snapshots in Purify doesn't have acceptable performance, try setting the option /MEMPROF_HEAP_DUMP_ON_SNAPSHOT=OFF. This will reduce the size of data collected and disable object-level profiling for the snapshot.

To fully disable object-level profiling, set the following options:

• -MEMPROF_OBJECT_DUMP=OFF
• -MEMPROF_HEAP_DUMP_ON_EXIT=OFF
• -MEMPROF_HEAP_DUMP_ON_SNAPSHOT=OFF

Using the Purify Filter manager

Prefiltering Java packages to screen out those that aren't intended for analysis is only one possible way to decrease the data volume displayed in a report. Purify, just like Quantify and PureCoverage, has a Filter Manager that enables quick filter creation and management.

For example, we could filter a run of BEA WebLogic in Purify to remove from the report all WebLogic methods that contain the pattern $Proxy*. Here's how we would proceed:

1. Start Purify and open the Filter Manager. In the Filter Manager Selection window, check "Memory profiling data":
2. Click the Functions tab and create a new filter for the $Proxy* pattern:

This filter will remove the methods with this pattern in their name from the report and will also remove the contribution these methods make to the overall memory footprint.

Discarding excess memory profiling data

By default, Purify will continue to collect data about memory usage by the Java application server when the run is over. In most cases, you'll want to create and analyze snapshots captured before the termination of the run. To avoid the unnecessary performance burden imposed by data collection after the end of the run, choose Settings > Preferences, click the Workspace tab, and check "Discard excess memory profiling data," as shown in Figure 7.

Figure 7: To discard excess memory profiling data

Rational Quantify tips

Rational Quantify is the performance-profiling tool for Java applications. Named the best Java profiling tool in the JDJ Readers Choice contest, Quantify pinpoints performance bottlenecks in an application in a way similar to what Purify does for memory.

Using the Quantify Filter Manager

Quantify, just like Purify and PureCoverage, has a Filter Manager that enables quick filter creation and management.

For example, we could filter a run of BEA WebLogic in Quantify to remove from the report all WebLogic methods that contain the pattern $Proxy*. To do this, we would start Quantify and open the Filter Manager, click the Functions tab, and create a new filter for the $Proxy* pattern, as shown in Figure 8.

Figure 8: Creating a custom filter in the Quantify Filter Manager

This filter will remove the methods with this pattern in their name from the report and will also remove the contribution these methods make to the overall memory footprint.

Rational PureCoverage tips

Rational PureCoverage is PurifyPlus's code coverage analysis tool. It provides an extensive list of functions available in the modules executed during recording and marks those that weren't tested on both method level and line level. Code coverage analysis is very important for determining the quality of tests performed on the developed application. Thus, PureCoverage is important both to developers, to help them make sure that all their methods are tested, and for system testers, to assure that the system tests provide a suitable basis for judging the quality of the application.

Using the PureCoverage Filter Manager

PureCoverage, just like Purify and Quantify, has a Filter Manager that enables quick filter creation and management.

For example, we could filter a run of BEA WebLogic in PureCoverage to remove from the report all WebLogic methods that contain the pattern $Proxy*. To do this, we would start PureCoverage and open the Filter Manager, click the Functions tab, and create a new filter for the $Proxy* pattern, as shown in Figure 9.

Figure 9: Creating a custom filter in the PureCoverage Filter Manager

This filter will remove the methods with this pattern in their name from the report and will also remove the contribution these methods make to the overall memory footprint.

Disabling Automatic Merge

PureCoverage will automatically merge coverage data from all the runs in a session. This is a useful feature, but it may negatively impact performance. To improve performance, merge the collected data sets manually instead.

In PureCoverage, choose Settings > Preferences and uncheck "Automatic merge," as shown in Figure 10.

Figure 10: To disable automatic merge

Determining which Java packages to prefilter

If your Java application server isn't one of those listed in the Purify documentation or if you want to prefilter additional Java packages, you can use PureCoverage to determine which Java packages to prefilter.

Simply launch the Java application server in PureCoverage and monitor the methods that are getting called during the execution. They'll be displayed in a summary view as shown in Figure 11.

Figure 11: PureCoverage summary view

(click here to enlarge)

In the PureCoverage report, right-click any of the methods, click the option Method Name, and check the option "Show fully qualified name," as shown in Figure 12.

Figure 12: To show the fully qualified name of the selected method

When this option is checked, PureCoverage will show all the method names together with the names of the packages they belong to. Sorting the list of methods by method name can give you an overview of packages recorded during the session. Adding the package name with a dot at the end to the list of prefilters in the Profile.ini file will instruct the selected PurifyPlus tool not to collect profiling or coverage information from that Java package and its subpackages.

Using the PureAPI functions

PurifyPlus v2002 provides a set of PureAPI functions to control data collection during program execution. These functions need to be embedded in the source code.

Program status functions:

• IsRunning -- Checks whether a Java or managed code program is running under a Rational product. This function is especially useful for enclosing special-purpose code when you're collecting measurement data for a program. For example, if you have a custom memory manager, you can disable it for memory profiling runs.
• IsRecordingData -- Checks whether measurement data is being recorded.

Data collection functions:

• AddAnnotation -- Displays the specified annotation in the Log tab in the Properties dialog and includes it in the log file. Use this function to note any special data collection circumstances for a specific data file, such as the version number of the program being measured.
• ClearData -- Clears all unsaved measurement data that has been collected up to this point. This function is especially useful for discarding unneeded data, such as data collected during the startup phase of a program.
• DisableRecordingData -- Stops recording measurement data. After you disable recording using this function, you can't resume recording. Use the PureAPI function StopRecordingData if you want to stop recording measurement data and then resume recording later.
• SaveData -- Takes a snapshot of all memory profiling data recorded since a program started, or since the last call to ClearData. Data recording continues. If you run a program that contains this function from the command line and you also use the /SaveData or /SaveTextData options, the data file that's created contains only the measurement data that was current when the SaveData PureAPI function was called. The file doesn't contain data for the entire run.
• StartRecordingData -- Starts recording measurement data. By default, data recording begins automatically when a program starts.
• StopRecordingData -- Stops recording measurement data. Use this function instead of DisableRecordingData if you want to stop recording and then resume recording later.

To use the PureAPI functions, you must import Rational\PureAPI to the source file. Listing 1 shows an example of PureAPI usage.

import Rational.PureAPI

class SnapshotClass {
   public static void main(String args\[\]){
      InputFunctionA();

      PureAPI.ClearData();
      ComputationFunctionB();

      PureAPI.SaveData();
      //The preceding function takes a snapshot of the 
      //measurement data collected for ComputationFunctionB. The 
      //data collected for the startup phase of the program was 
      //discarded before ComputationFunctionB was called.

      PureAPI.ClearData();
      ComputationFunctionC();

      PureAPI.SaveData();
      //The preceding function takes a snapshot of the
      //measurement data collected for ComputationFunctionC.

      PureAPI.DisableRecordingData();
      //The preceding function disables recording of
      //measurement data for the rest of the run.

      OutputFunctionD(int);
   }
}

Back to top

Part 3: Examples of PurifyPlus Usage

Now let's look at how we would use each of the PurifyPlus tools to perform runtime analysis of an actual Web application. We'll use examples analyzing the J2EE demo applications PetStore and Bookstore.

Creating a memory profile

First we'll use Purify to create a memory profile of the PetStore application as a customer logs in to the Web site, browses for a product, buys it, and checks out. How much memory did the Web application use for this session? Where was the memory allocated? How was the memory distributed in the application? Were there any memory leaks? Purify can answer all these questions if we attach it to the JVM while playing back the scenario.

We'll follow these steps:

1. Start the PetStore application server together with Purify.
2. Launch the application server.
3. Force garbage collection by calling the Java API function gc or from within the Purify GUI.
4. Take a snapshot of memory by clicking the camera icon in the Purify main window and start the client session.
5. Buy an iguana.
6. Take another snapshot of memory and end the session.
7. Close both the browser and the Java application server.
8. Run the Compare Runs feature in Purify. This feature will create an additional data set with the memory profile of the section in the Java application server run between the two snapshots.
9. Analyze the results.

The resulting data set will create a call graph of the memory profile looking like Figure 13.

Figure 13: Call graph of PetStore execution segment in Purify

(click here to enlarge)

The call graph is a powerful memory visualization tool. It gives us an overview of the course of execution of the tested Web application. Additionally, it highlights the chain of calls with the largest memory allocation, leading us visually to the application's memory hotspot. The thickness of the line connecting the methods represents the percentage of memory used for this chain of calls compared to the rest of the application, as shown in Figure 14.

Figure 14: Finding a memory hotspot

(click here to enlarge)

The other very useful tool in the Compare Runs report is the Function List View. The Function List View displays the number of bytes allocated in each method called between the two snapshots, along with the number of calls to the method and other valuable information, as illustrated in Figure 15.

Figure 15: Function List View in Purify

(click here to enlarge)

More information about the memory profile is available in the Snapshot report (also known as the Function Detail View) for each individual method, as shown in Figure 16.

Figure 16: Function Detail View in Purify

(click here to enlarge)

If you look carefully at the data available in this report, you'll notice a detailed list of objects in memory at the moment of creating the snapshot. Purify features a detailed object-level profiler with reference browser, but due to the size of the memory dump of the Java application server, analyzing objects and references may require substantial amounts of memory and CPU speed.

This example represents typical datasets obtained from analyzing a Web service. If you want to learn how to analyze Purify data to find potential memory leaks and "memory hogs," see the whitepaper "Memory Profiling in Java."

Back to top

Creating a performance profile

The way to use the performance-profiling tool IBM® Rational® Quantify® with J2EE applications is essentially the same as for Purify and PureCoverage: We start the server with Quantify attached and take snapshots of the performance profile before and after the section of execution we want to focus on. Then we use the Compare Runs feature to isolate performance data recorded between the snapshots.

Figure 17 shows the performance profile of the PetStore application for the same scenario as described in the previous section.

Figure 17: Call graph of PetStore execution segment in Quantify

(click here to enlarge)

As in Purify, the Function List View can provide interesting information about the execution and potential areas for improvement. Figure 18 shows a portion of this view for our PetStore scenario.

Figure 18: Function List View in Quantify

(click here to enlarge)

The most obvious approach to analyzing the Function List View is to sort the list of methods by time spent on each method between the snapshots and concentrate on the top ten functions. Another approach is to analyze the number of times a certain method has been called. Does the number of recorded calls match the expected value for the scenario that was tested? If the method is called too many times unnecessarily, this is a potential area for improvement.

Quantify can also serve as a secondary memory-profiling tool. Note how much time was spent executing garbage collection for cleaning the unused memory. Garbage collection follows its own principles and can't be exactly manipulated, but increasing the available heap for the process at the start of the application can reduce the number of garbage collection interventions.

Also as in Purify, more information about the performance profile is available in the Snapshot report (also known as the Function Detail View) for each individual method, as shown in Figure 19.

Figure 19: Function Detail View in Quantify

(click here to enlarge)

Let's look at another example, this one using the standard J2EE demo application Bookstore. Bookstore is based on a set of servlets. The suggested procedure for testing this Web application is similar to the one described for JSP applications. If the servlets are compiled with debugging information and if the source files are available on the test machine, Quantify and PureCoverage will be able to create line-level profiles of the tested Web application.

Let's say that the call graph of the difference between two snapshots (Figure 20) reveals that most of run time was spent in the method doGet in the servlet BookDetailServlet.

Figure 20: Call graph of Bookstore execution segment in Quantify

(click here to enlarge)

A closer look at the line-level profile reveals that the time gets spent in fetching data from the database. Figure 21 shows the line-level profile for the method BookDetailServlet.doGet.

Figure 21: Line-level performance profile in Quantify

(click here to enlarge)

This line-level profile, known as the Annotated Source report, displays the source files with additional profiling information for each line of source code. It provides information about the time spent executing the line of code, as well as the line of code plus its descendants, and about the percentage of both in the recorded method time. All times are measured in microseconds by default.

Creating a code coverage profile

The procedure for using PureCoverage is the same as for Quantify and Purify. We attach the tool to the JVM for the tested application and take snapshots of code coverage as we run our tests. We can use the Compare Runs and Merge Runs features either to focus on certain parts of the application (Compare Runs) or to get an overview of the sequence of tests (Merge Runs).

For this example we start the IBM WebSphere server with PureCoverage attached and execute the following scenario:

1. Take the initial snapshot of PetStore.
2. Add an iguana to the chart.
3. Take a second code-coverage snapshot.
4. Remove the iguana from the chart and go to the store's home page.
5. Take a third snapshot.
6. Merge the results of all three snapshots.

Figure 22 shows the PureCoverage main window with its detailed information about code coverage for methods and lines of code that were executed during these two tests. PureCoverage displays the results by source file (File View), by module (Module View), or in a list of methods (Function List View).

Figure 22: File View of our scenario in PureCoverage

(click here to enlarge)

If we wanted to focus on the code coverage for the scenario of removing the item from the chart and returning to the home page of the store, we could compare the second and third snapshots by using the Compare Runs feature. Sorting the resulting data file by number of new method calls would highlight all the methods that were called between the two selected snapshots, as shown in Figure 23.

Figure 23: List of method calls from Compare Runs feature in PureCoverage

(click here to enlarge)

PureCoverage, just like Quantify, is able to present code coverage data on the source level for further analysis. The results are displayed in the Annotated Source report, where the status of the lines of code is indicated with different colors.

Figure 24 is an example of line-level code coverage information obtained by PureCoverage for the Bookstore Web application. The lines of code that were hit during the test are blue, the missed lines are red, and the dead lines are black.

Figure 24: Line-level code coverage info for the Bookstore application in PureCoveragex

(click here to enlarge)

The coding style makes a difference when it comes to how precisely the code is colored. PureCoverage "knows" only about the executed lines of code; all lines of code that aren't executable will be left in black.

By default, lines of code that consist of multiple blocks aren't displayed. These lines can be hit, missed, or partially hit. Exact information on these lines can be obtained by right-clicking anywhere in the report and choosing "Show Multi-block Lines" in the pop-up window, as shown in Figure 25.

Figure 25: Choosing the "Show Multi-block Lines" option in PureCoverage

Back to top

Part 4: Information on Specific Java Application Servers

Every Java application server can be set up to run with PurifyPlus as described in Part 1. This part gives information specific to each of these major servers and engines:

• IBM WebSphere 4
• BEA WebLogic 6.1
• Apache Jakarta Tomcat 4
• Sun J2EE SDK 1.3.1
• Silverstream 3.7

Running IBM WebSphere 4 with PurifyPlus

Prefilters for IBM WebSphere 4

java.
javax.
sun.
com.sun.
org.omg.
org.w3c.
org.xml.
org.apache.
org.enhydra.
ibm.
dcom.
com.ibm.
db.
com.fourthpass.

For information on what to do with this list of prefilters, see "Step 3: Updating the Prefilter List for PurifyPlus Tools," above.

Running Purify with IBM WebSphere 4

To successfully collect memory-profiling information from an IBM WebSphere 4 server, you need to enable the following additional Purify option for the run:

/PurifyDefaultInstrumentationType=Function

Use of this option is explained under "Changing the Instrumentation Level to Reduce Purify's Memory Needs," above.

Running BEA WebLogic 6.1 with PurifyPlus

Prefilters for BEA WebLogic 6.1

java.
javax.
sun.
com.sun.
org.omg.
org.xml.
org.w3c.
COM.
com.beasys.
com.adventnet.
weblogic.
bea.
com.bea.
antlr.
bsh.
c8e.

For information on what to do with this list of prefilters, see "Step 3: Updating the Prefilter List for PurifyPlus Tools," above.

Filters for the $Proxy* Packages

In the Purify Filter Manager, specify a new filter for Java packages with the pattern $Proxy* in the name, as explained in the section "Using the Purify Filter Manager," above.

Running Apache Jakarta Tomcat with PurifyPlus

Tomcat is a lightweight JSP and servlet engine, not a full-size Java application server. But due to its small memory footprint, it allows memory profiling on the object level even on slower machines.

Prefilters for Apache Jakarta Tomcat 4

java.
javax.
com.sun.
sun.
org.omg.
org.xml.
org.w3c.
org.apache.
filters.
listeners.
compressionFilters.

For information on what to do with this list of prefilters, see "Step 3: Updating the Prefilter List for PurifyPlus Tools," above.

Starting Apache Jakarta Tomcat 4 with PurifyPlus Attached

It's recommended to start Jakarta Tomcat 4 from the Tomcat startup batch file, startup.bat. When shutting down the Tomcat server, start the shutdown batch file in the same PurifyPlus tool that's attached to the JVM to insure the correct shutdown procedure.

Running Sun J2EE SDK with PurifyPlus

Prefilters for Sun J2EE SDK 1.3.1

java.
javax.
com.sun.
sun.
org.omg.
org.xml.
org.w3c.
org.apache.
c8e.
COM.
RmiJdbc.

For information on what to do with this list of prefilters, see "Step 3: Updating the Prefilter List for PurifyPlus Tools," above.

Running Silverstream Java Application Server 3.7 with PurifyPlus

Prefilters for Silverstream 3.7

java.
javax.
com.sun.
sun.
org.omg.
org.xml.
com.phaos.
com.sssw.
COM.
c8e.
RmiJdbc.
com.ibm.
org.apache.
com.b.
com.d.
com.g.
com.k.

For information on what to do with this list of prefilters, see "Step 3: Updating the Prefilter List for PurifyPlus Tools," above.

Starting Silverstream 3.7 with PurifyPlus Attached

Silverstream itself is a JNI application, and JVM runs in its own process. Therefore, the way to start PurifyPlus with Silverstream is to set up the system environmental variable _JAVA_OPTIONS as explained in "To start every Java application with PurifyPlus attached," above. Furthermore, for profiling purposes Silverstream has to be started in the Debug mode. Here's the workaround:

1. Set JAVA_HOME to <SILVERSTREAM_HOME>/jre
2. Go to directory jre/lib/security and allow write access to the file java.policy. (Uncheck the read-only box in Windows Explorer.)
3. Update the Silverstream JRE with cstart /setup
4. Set up the system environmental variable _JAVA_OPTIONS=-XrunPureJVMPI:Tool where Tool is either purify, quantify, or coverage, depending on the type of runtime analysis you want to perform.
5. Update the prefilters as explained in the section above.
6. Start Silverstream 3.7 in the Debug mode.

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Part 1: Setting up the Java environment for profiling
• Part 2: Running the PurifyPlus Tools
• Part 3: Examples of PurifyPlus Usage
• Creating a performance profile
• Part 4: Information on Specific Java Application Servers
• About the author
• Comments

Next steps from IBM

• Try: Rational PurifyPlus
• Webcast: Extending Web application security testing across the software delivery lifecycle
• Briefing: Jazz and Rational Team Concert
• Buy: Rational PurifyPlus

My developerWorks community

Dig deeper into Rational on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers