ChangeDistiller

The ChangeDistiller-algorithm extracts fine-grained source code changes between subsequent revision of Java classes. The algorithm does tree differencing and works on abstract syntax trees.

Description

Source code can be represented by abstract syntax trees (ASTs). The change distilling algorithm uses tree differencing on the ASTs of two subsequent versions of a particular class [2]. Basically, the algorithm calculates an edit script that contains basic tree edit operations and transforms the older into the newer AST. We use the basic tree edit operations insert, delete, move, and update on AST nodes.

A taxonomy of source code changes defines change types according to tree edit operations in the AST. The taxonomy is used to translate an edit script into concrete source code changes. In addition, the taxonomy defines the change significance level that expresses the possible impact a change type may have on other source code entities and whether it may be altering the functionality. Change significance levels are used to measure the relevance of each particular source code change.

The current version of the taxonomy defines more than 40 change types for source code entities [1]. These change types are divided into body and declaration part categories of attributes, classes, and methods. Each change type obtains a change significance level of none, low, medium, high, or crucial. For certain change types the change significance level is adapted to the accessibility modifier of a source code entity. For instance, a return type change of a public method has a higher change significance level than of a private method. The goal is to differentiate less relevant changes from significant changes, for instance, changes with impact on functionality.

Leveraging the information provided by ASTs permits us to get precise information about a source code change. In addition to the information that a particular source code entity has changed, tree edit operations also provide information about the location of the change. For instance, we can tell that a method invocation fred.bar() was moved into an if-statement with the condition fred != null.

This version of ChangeDistiller works with Java and provides a convenient API to extract and work with fine-grained source code changes.

Obtaining ChangeDistiller

ChangeDistiller is open source, available under the Apache 2.0 License. Please cite [2] if you want to reference the ChangeDistilling algorithm in your scientific work.

You can either check-out the source code from the Git repository hosted by Bitbucket or download a snapshot build from our continuous integration server.

Git

Checking-out and building ChangeDistiller yourself is easy if you are familiar with Apache Maven and Git:

git clone git@bitbucket.org:sealuzh/tools-changedistiller.git changedistiller
cd changedistiller
mvn install

The target/ folder will then contain four .jar files:

changedistiller-0.0.1-SNAPSHOT-javadoc.jar
changedistiller-0.0.1-SNAPSHOT-sources.jar
changedistiller-0.0.1-SNAPSHOT.jar
changedistiller-0.0.1-SNAPSHOT-jar-with-dependencies.jar

For the first three artifacts, all third-party libs can be found in lib/. The last one is self-contained.

Snapshot Builds

Please visit https://seal-team.ifi.uzh.ch/jenkins/job/changedistiller/ for the latest stable build.

Using ChangeDistiller

A small usage example can be found below. For details, please have a look at the tests and Javadocs.

#!java

File left = new File("MyClass.java_v1");
File right = new File("MyClass.java_v2");

FileDistiller distiller = ChangeDistiller.createFileDistiller(Language.JAVA);
try {
    distiller.extractClassifiedSourceCodeChanges(left, right);
} catch(Exception e) {
    /* An exception most likely indicates a bug in ChangeDistiller. Please file a
       bug report at https://bitbucket.org/sealuzh/tools-changedistiller/issues and
       attach the full stack trace along with the two files that you tried to distill. */
    System.err.println("Warning: error while change distilling. " + e.getMessage());
}

List<SourceCodeChange> changes = distiller.getSourceCodeChanges();
if(changes != null) {
    for(SourceCodeChange change : changes) {
        // see Javadocs for more information
    }
}

ChangeDistiller OSGI Bundle

This version of ChangeDistiller works independently of OSGI and Eclipse. That means it can be embedded in any other Java context, such as Web services, non-rcp Java desktop applications, etc. However, ChangeDistiller is still a valid OSGI bundle and thus can be used like any other Eclipse plug-in. As such it depends on other bundles, some provided already as part of a default Eclipse installation. The following two bundles are not part of Eclipse, but can be found in the lib/ folder, once ChangeDistiller has been built with Maven:

commons-lang3-3.1.jar
guice-assistedinject-3.0.jar

Please install changedistiller-0.0.1-SNAPSHOT.jar in this case, not the jar that includes all third-party dependencies. Otherwise you might run into class-loading issues due to duplicated classes.

References

Beat Fluri and Harald C. Gall. Classifying Change Types for Qualifying Change Couplings. In Proceedings of the 14th International Conference on Program Comprehension, pp. 35-45, IEEE Computer Society, 2006.
Beat Fluri, Michael Würsch, Martin Pinzger, and Harald C. Gall. Change Distilling: Tree Differencing for Fine-Grained Source Code Change Extraction. IEEE Transaction on Software Engineering, 33(11), pp. 725-743, 2007.
Harald C. Gall, Beat Fluri, and Martin Pinzger. Change Analysis with Evolizer and ChangeDistiller. IEEE Software, 26(1), pp. 26-33, 2009.

Wiki

tools-changedistiller / Home