Usage
This page describes how to use 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.
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.
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:
- the kind of reflective call:
Class.forName,Class.newInstance,Constructor.newInstanceorMethod.invoke - 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,
- the fully qualified name of the method that contains the reflective call, and
- the line number at which the reflective call took place. (This may be empty if the bytecode contains no line-number information.)
- optionally additional information, such as the accessibility status of the member in question
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>
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 =====
$