Install
Requirements
To run the birthmark tool, you need the following software on your system:- A Java 1.5 Runtime Environment
- The ant build tool.
Download and Unpack
Download the most recent version from our web site. It comes as a tarball and can be unpacked with following command:
->tar xvzf api-birthmark-1.0.tgz
This will create a new directory APIBirthmarkDist
Adjust the Properties File
The settings in./APIBirthmarkDist/APIBirthmark/project.properties
have to be adjusted.
This has to be done before the compilation, because the properties file
is packaged in the resulting jar.
Following properties have to be adjusted (see comments in project.properties file for further documentation):
#directory to output the files generated during
instrumentation and birthmark results
output.dir=${scratch.dir}/APIBirthmarkOutput
#location of the uninstrumented runtime classes. (usually rt.jar on Mac classes.jar)
runtime.source=${scratch.dir}/JavaVM.framework/Versions/1.5.0/Classes/classes.jar
#destination location of the instrumented rt.jar
runtime.instrumented=${output.dir}/classes.jar
output.dir=${scratch.dir}/APIBirthmarkOutput
#location of the uninstrumented runtime classes. (usually rt.jar on Mac classes.jar)
runtime.source=${scratch.dir}/JavaVM.framework/Versions/1.5.0/Classes/classes.jar
#destination location of the instrumented rt.jar
runtime.instrumented=${output.dir}/classes.jar
Compile
The project can be compiled using the ant tool.
->cd APIBirthmarkDist/APIBirthmark
->ant -f dist.xml
->ant -f dist.xml
Test
In order to see if the tool works correctly two tests can be carried out. These tests need a bit more memory. Therefore, the ANT_OPTS environment Variable has to be set, e.g.
export ANT_OPTS=-Xmx1024m
-
The first test compiles an instruments a small test program
that uses the Java API. The Birthmarks of two runs with
slightly different behaviour are then compared.
->cd APIBirthmarkDist/APIBirthmarkThis should produce a output like this (complete output):
->ant compareTestJarBirthmarks...
compareTestJarBirthmarks:
[java] INFO [getTraceObjectResult - org.softevo.apibirthmark.tracing.result.process.ResultFromFiles] -
Reading: /scratch/APIBirthmark/APIBirthmarkOutput/testAPICalls.ser Modification Date: 2007-10-03
[java] INFO [getTraceObjectResult - org.softevo.apibirthmark.tracing.result.process.ResultFromFiles] -
Reading: /scratch/APIBirthmark/APIBirthmarkOutput/test.ser Modification Date: 2007-10-03
[java] Similarity between the two results: 0.8695652
[java] INFO [getTraceObjectResult - org.softevo.apibirthmark.tracing.result.process.ResultFromFiles] -
Reading: /scratch/APIBirthmark/APIBirthmarkOutput/testAPICalls.ser Modification Date: 2007-10-03
[java] INFO [getTraceObjectResult - org.softevo.apibirthmark.tracing.result.process.ResultFromFiles] -
Reading: /scratch/APIBirthmark/APIBirthmarkOutput/test.ser Modification Date: 2007-10-03
[java] Using contained birthmark
[java] Similarity between the two results: 1.0
BUILD SUCCESSFUL
Total time: 1 minute 42 seconds -
The second test builds an artificial API and a program using
this API. Then the program is run and the actual calls to the
API are compared with the expected calls.
->cd APIBirthmarkDist/APIBirthmarkWhich should produce a output like this (complete output):
->ant validation
[transformedRunner] 12000 calls traced
[java] INFO [getPropertyFileLocation - org.softevo.apibirthmark.util.PropertyFileLoader] -
Location of properties file(project.properties) : file:
/Users/schuler/apitest/APIBirthmarkDist/APIBirthmark/bin/project.properties
[java] Location of properties file(project.properties) : file:
/Users/schuler/apitest/APIBirthmarkDist/APIBirthmark/bin/project.properties
[java] Start Comparing
[java] Finished
[java] 12000 equal trace entries
BUILD SUCCESSFUL
Total time: 9 seconds
Compute Birthmarks
In order to determine the birthmark for a program, you have to follow these steps (all steps are carried out as ant tasks). See build.xml and project.properties for an example.- The Java Runtime classes (usually rt.jar) have to be instrumented. This is
done via the apitransformer task.
<target name="transformRuntime" depends="init">
<apitransformer source="${runtime.source}" destination="${runtime.instrumented}"
IDMapDestination="${idfile.runtime}" />
</target>Parameters Description source The source location of the runtime classes (rt.jar) destination The location where the instrumented jar is written. IDMapDestination The location for an XML file, that stores the class and method names and their IDs.
- Instrument the program(s), for which the birthmark should be computed. This
is done via the observedtransformer task.
<target name="transformYourJar" depends="transformRuntime" description="transforms a jar to enable the computation of birthmarks">
<observedtransformer source="${jar.to.transform}" destination="${your.instrumented.jar}"
IDMapSource="${idfile.runtime}" IDMapDestination="${idfile.for.instrumented.jar}" />
</target>Parameters Description source The source location of the jar. destination The location where the instrumented jar is written. IDMapSource The location of the XML file, that holds the class and method names of the API (should be the same as IDMapDestination in the apitransformertask). IDMapDestination The location for an XML file, that stores the class and method names of the program and their IDs. -
Run the instrumented program and capture the birthmark. This is done via the
transformedRunner task.
<target name="runTransformedJar" depends="transformYourJar" description="runs the program and computes the birthmark">This is a subclass of the ant Java task, hence it supports the same parameters as the java task. The additional parameters are:
<transformedRunner classname="YourMainClass" resultFile="${birthmark.file}" maxmemory="500M" compare="false">
<classpath>
<pathelement path="${your.instrumented.jar}" />
</classpath>
<bootprepend>
<fileset refid="project.jars" />
<pathelement path="${runtime.instrumented}" />
<pathelement path="${bin}" />
</bootprepend>
</transformedRunner>
</target>
Parameters Description resultFile The location where the resulting birthmark file is written . compare If this is set to true, the program is run twice and a second result file is written. Its file name is the name given in resultfile prefixed with COMPARE_. IDMapSource The location of the XML file, that holds the class and method names of the API (should be the same as IDMapDestination in the apitransformertask).
The instrumented program is given via the classpath element. -
Compare Birthmarks:
<java classname="org.softevo.apibirthmark.tracing.BirthmarkCompare">The two birthmark files (written in the transformedRunner task) to compare are given as arguments.
<arg value="${birthmark.file.1}" />
<arg value="${birthmark.file.2}" />
<classpath>
<pathelement path="${bin}" />
<fileset refid="project.jars" />
</classpath>
</java>
Additionally the system property birthmarkComparison can be specified.<sysproperty key="birthmarkComparison" value="contained" />If it is set tocontained the two result sets are not intersected. Instead for each set it is computed how much it is contained in the other set and the maximum of these two values is taken.