Usage

This page describes how to use TamiFlex.

Overview of TamiFlex

TamiFlex consists of two Java agents, a Play-Out Agent and a Play-In Agent.

The Play-Out Agent fulfils two tasks (1.) logging reflective calls into a trace file and (2.) gathering all class files that a program run loads (including classes that are generated at runtime). The Play-Out Agent will write both the classes and the log file into a specified directory. You can then feed this directory to your favorite static analysis tool. Soot has direct support to process such class directories and to read TamiFlex trace files.

You can use the the Play-In Agent to re-insert offline-transformed (e.g. optimized) classes into the original application.

Using the Play-Out Agent

To use the Play-Out Agent with your program, simply add poa.jar as an agent JAR file to your JVM's command line.

For example, to see an explanation of the agent's arguments, simply state:

java -javaagent:poa.jar

The following command will cause the agent to write classes and the reflection log file refl.log into the directory ./out:

java -javaagent:poa.jar <other arguments>

The directory out is the default output directory for the Play-Out Agent. To change this directory, modify the ConfigurationFile poa.properties.

Format of the reflection log file

The Play-Out Agent produces a refl.log file, which is just a regular CSV file. Depending on the configuration of the agent, it contains at least the following entries:

1. the kind of reflective call: Class.forName, Class.newInstance, Constructor.newInstance or Method.invoke
2. depending on the kind of the reflective call (1.) the qualified name of the class that is instantiated or the signature of the method or constructor that is called,
3. the fully qualified name of the method that contains the reflective call, and
4. the line number at which the reflective call took place. (This may be empty if the bytecode contains no line-number information.)
5. optionally additional information, such as the accessibility status of the member in question

Using the Play-In Agent

Similar to the Play-Out Agent, to use the Play-In Agent with your program, simply add pia.jar as an agent JAR file to your JVM's command line.

For example, to see an explanation of the agent's arguments, simply state:

java -javaagent:pia.jar

The following command will cause the agent to read classes from the directory ./out:

java -javaagent:pia.jar <other arguments>

Example run (on DaCapo)

In the following we give an example on how to use both agents on the Avrora benchmark of the DaCapo benchmark suite:

$ java -javaagent:poa.jar -jar dacapo-9.12-bach.jar avrora
===== DaCapo 9.12 avrora starting =====
===== DaCapo 9.12 avrora PASSED in 9969 msec =====
Found 52 new entries.
$ ls out/
Harness.class	avrora		cck		com		java		javax		org		refl.log	sun
$ head out/refl.log 
Class.forName;avrora.Main;org.dacapo.harness.Avrora.<init>;26;
Class.forName;java.security.interfaces.RSAPrivateKey;java.security.Provider$Service.getKeyClass;1402;
Class.forName;java.security.interfaces.RSAPublicKey;java.security.Provider$Service.getKeyClass;1402;
Class.forName;java.util.CurrencyData;java.util.Currency$1.run;128;
Class.forName;org.dacapo.harness.Avrora;org.dacapo.harness.TestHarness.findClass;281;
Class.forName;sun.net.www.protocol.jar.Handler;java.net.URL.getURLStreamHandler;1140;
Class.forName;sun.security.provider.SHA;java.security.Provider$Service.getImplClass;1260;
Class.forName;sun.security.rsa.RSAKeyFactory;java.security.Provider$Service.getImplClass;1260;
Class.forName;sun.security.rsa.RSASignature$SHA1withRSA;java.security.Provider$Service.getImplClass;1260;
Class.newInstance;avrora.Defaults$AutoProgramReader;cck.util.ClassMap.getObjectOfClass;171;
$

At this point you would now normally analyze all classes in out or use the refl.log file in out. Optionally, you could also transform the classes in out, for instance based on the obtained analysis information. Then you would use the Play-in Agent:

$ java -javaagent:pia.jar -jar dacapo-9.12-bach.jar avrora
===== DaCapo 9.12 avrora starting =====
===== DaCapo 9.12 avrora PASSED in 8661 msec =====
$