API Birthmark

Install

Requirements

• A Java 1.5 Runtime Environment
• The ant build tool.

Download and Unpack

Adjust the Properties File

Compile

Test

1. 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/APIBirthmark
   ->ant compareTestJarBirthmarks
   This should produce a output like this (complete output):
   ...
   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
2. 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/APIBirthmark
   ->ant validation
   Which should produce a output like this (complete output):
   
   [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

1. 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.

   
   
2. 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.

3. 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">
     <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>
   This is a subclass of the ant Java task, hence it supports the same parameters as the java task. The additional parameters are:
   

   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).

   Additionally the bootprepend element must be specified. It has to contain the instrumented runtime classes, the classes of the APIBirthmark program and its required jars.
   The instrumented program is given via the classpath element.
4. Compare Birthmarks:
   <java classname="org.softevo.apibirthmark.tracing.BirthmarkCompare">
       <arg value="${birthmark.file.1}" />
       <arg value="${birthmark.file.2}" />
       <classpath>
         <pathelement path="${bin}" />
         <fileset refid="project.jars" />
       </classpath>
     </java>
   The two birthmark files (written in the transformedRunner task) to compare are given as arguments.
   Additionally the system property birthmarkComparison can be specified.
   <sysproperty key="birthmarkComparison" value="contained" />
   If it is set to contained 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.

Further Information