Dynamic Purity Analysis

Requirements

Before you continue, make sure that your system meets the following requirements:

A Java Runtime Environment 1.5.04 or later.
A GNU version of tar to extract the archive.
The convenience scripts are provided only for unix shells. If you are working on a windows machine, you may have to take a look at the scripts (they are really easy to understand) and create them for yourself.

Our tool has been successfully tested on the following systems:

Debian GNU/Linux 2.6.8-2-686
Suse Linux 2.6.13-15.8-smp
Mac OS X Darwin Kernel Version 8.6.0

We are confident that the tool runs on any java enabled system, but have only tested the ones listed above.

How-to use dynamic purity analysis

In order to execute dynamic purity analysis for your program, you must execute the following steps.

Download and Unpack

Go to the download page and download the most recent version. It comes as a tarball, so you need to unpack it using tar, for example by using the following command:

tar zxvf jdynpur-1.0-bin.tar.gz

This creates a subfolder jdynpur with folders lib and bin.

Modify the trace and analyze scripts

Both scripts require you to set JAVA_HOME to point to your Java Runtime Environment. You also need to edit both scripts and set the location of the installation directory of the tool (Variable INSTALL). Both scripts are located in folder bin. Use your preferred editor and change the values. An example configuration might look as follows:

# JDynPur installation directory
INSTALL=/tmp/dallmeier/dynpur

You may also want to add the bin folder to your path for ease of use.

Execute your program

If you modified the trace script correctly, you can use it just like the java command. Instead of

java mypackage.MyClass

you can simply write

tracerun.sh mypackage.MyClass

Before you execute the program, make sure that you have enough space left on your harddisk (about 100 megs, depending on how long your program runs). Equipped with dynamic purity analysis, your program slows down by about 60-80%. Analysis usually is quiet and does not output anything on your screen.

The tool needs to write tracing information to a file. The default value for the file name is trace.out in the working directory of the virtual machine. This can be changed by setting the system property jdynpur.resultfilename to wherever you want the file to go to. For example, if you want the trace to be stored in /tmp/mytrace.out, you need to add the parameter -Djdynpur.resultfilename=/tmp/mytrace.out to your invocation of the virtual machine.

Analyze the results

To evaluate the results saved in the files you need to run another script named analyzerun.sh. Make sure that all variables are set correctly. The script currently expects three parameters:

The name of the trace file (e.g. /tmp/mytrace.out.
The name of the file results are written to (e.g. results.xml).
A boolean flag (true|false) indicating if parameter mutability analysis should be turned on (true or off).

An example invocation might look as follows (assuming that you have the bin folder in your path)

analyzerun.sh trace.out results.xml true

The trace is analyzed and the program outputs a list of pure and impure methods to standard out and saves an XML representation of the results to the file you specified.

The content of the result file might look as follows:

<purityresults>
  <executedmethods>
    <method access="1" classname="com/jgoodies/forms/layout/FormLayout" methodname="getRowCount" signature="()I">
      <runtimeclass classname="com/jgoodies/forms/layout/FormLayout"/>
    </method>
  </executedmethods>
  <methodsmodifyingself>
    <method access="1" classname="com/sleepycat/je/tree/Tree" methodname="setDatabase" signature="(Lcom/sleepycat/je/dbi/DatabaseImpl;)V">
      <runtimeclass classname="com/sleepycat/je/tree/Tree"/>
    </method>
  </methodsmodifyingself>
  <impuremethods>
    <method access="1" classname="com/sun/org/apache/xerces/internal/impl/XMLDocumentScannerImpl" methodname="setProperty" signature="(Ljava/lang/String;Ljava/lang/Object;)V">
      <runtimeclass classname="com/sun/org/apache/xerces/internal/impl/XMLNSDocumentScannerImpl"/>
    </method>
  </impuremethods>
  <puremethods>
    <method access="1" classname="com/jgoodies/forms/layout/FormLayout" methodname="getRowCount" signature="()I">
      <runtimeclass classname="com/jgoodies/forms/layout/FormLayout"/>
    </method>
  </puremethods>
</purityresults>

The file first lists all methods that were executed, then all methods that actually modified the this object during execution, the list of methods that had any side-effects, and finally all methods that did not show side-effects. For methods classified as pure, the runtimeclass elements list all runtime types for which the method was executed an no side-effects were recorded. There are some difficult cases were the runtime type of a receiver object may determine if a method has side-effects or not. For static methods, the classname attribute simply contains the declaring class of the method.

Parameter Mutability Information

If you turned on parameter mutability analysis, the result file contains another element after the puremethods element:

<method access="1" classname="org/columba/core/gui/menu/MenuXMLDecoder" methodname="<init>" signature="(Lorg/columba/api/gui/frame/IFrameMediator;)V">
<runtimeclass classname="org/columba/core/gui/menu/MenuXMLDecoder">
<parameter index="0" unmodified="true"/>
</runtimeclass>
</method>

As you can see, the tool lists all methods that were executed. If a method has at least one complex parameter, it contains an element runtimeclass (see previous section). This elements contains a child parameter for each complex parameter. If the parameter was modified, the unmodified attribute is false, otherwise its true. The index attribute gives the index of the parameter in the signature (starting with 0). Be aware that dynamic methods all have an implicit this parameter.

Project Info