jelly-wzj / jphantom

A tool for Java program complementation.

JPhantom

A tool for Java program complementation. It takes a single jar as its main argument and complements it by creating a new jar that adds dummy implementations for every phantom class detected in the original one. (A phantom class is a class that is referenced somewhere but its definition is missing.)

The phantom classes in the produced jar will contain every missing field and method that was referenced and used in the original jar, as well as a supertype that respects every type constraint that was found (e.g., if phantom class B was used in a place where known class A was expected, and a widening reference conversion took place, then we must conclude that class A is a supertype of B).

You can read more about the underlying problem of class hierarchy complementation in the OOPSLA '13 paper (or the presentation slides).

Release

To list JPhantom as a dependency using Maven, add the following to your pom.xml:

<dependency>
  <groupId>org.clyze</groupId>
  <artifactId>jphantom</artifactId>
  <version>1.4.2</version>
</dependency>

To add a dependency using Gradle:

dependencies {
  compile 'org.clyze:jphantom:1.4.2'
}

Usage

java -jar <jphantom>  <injar> [--debug] [--help] [--save-class-files] [--soft-fail] [-d <dir>] [-java-version <ver>][-o <outjar>] [-v (--log, --verbose) N]

 <injar>                 : the jar to be complemented
 --debug                 : Debug mode
 --help                  : Help
 --save-class-files      : Save phantom class files
 --soft-fail             : Attempt to recover partial results from conflicts
 -d <dir>                : Phantom-classes destination directory
 -java-version <ver>     : Java version to target, defaulting to 5
 -o <outjar>             : the destination path of the complemented jar
 -v (--log, --verbose) N : Level of verbosity

You can use the --save-class-files option to save the generated class files for the phantom classes that were detected in the process. This is handy when you want to inspect only the code that was autogenerated, without having to extract the relevant class files from the complemented jar.

You can also increase the level of verbosity to log every constraint that was detected by using the --verbose N option.