Semmle 1.22
Skip to end of metadata
Go to start of metadata

On this page:

Related topics:

-

This topic describes how to use the ODASA_JAVA_CLASS_ORIGIN_TRACKING environment variable to instruct the Semmle Java extractor to use an alternative method of uniquely identifying Java classes. Enabling origin tracking allows the Java extractor to distinguish between different classes with the same fully qualified name.

Overview

By default, the Semmle Java extractor identifies classes by their fully qualified name. If the code base that you are analyzing has two distinct classes with the same qualified name, the extractor sees them as a single class containing the union of the members of the two classes.

From Semmle release 1.9.3 onward you can enable an alternative method of Java class identification: "origin tracking." This enables the Java extractor to distinguish between Java classes that have the same qualified name.

-

-

How origin tracking works

When origin tracking is enabled, the Java extractor identifies classes not only by their fully qualified name, but also by a hash of:

  • The path of the source file in which the class is defined
  • The contents of that source file

To implement origin tracking across compilations, the Java extractor associates origin information with every class file produced by the compiler. The hash of source file location and file contents is stored as an attribute of the class file. This change should not affect any class file processing tools. In particular, it is ignored by the JVM.

Enabling origin tracking

To turn on origin tracking for Java, set the environment variable ODASA_JAVA_CLASS_ORIGIN_TRACKING to true for the duration of extraction.

To set an environment variable for the duration of extraction
  1. Edit the variables file in the project directory (for example, odasa/projects/yourProject).
    Create this file if it does not already exist.
  2. Add the following line:

    ODASA_JAVA_CLASS_ORIGIN_TRACKING = true
  3. Edit the project file in the project directory.
  4. Identify the build command(s) that cause the code to be compiled.
    Typically, these commands will contain index="true" within the opening tag of the build element.
  5. Add an  export attribute with the value "ODASA_JAVA_CLASS_ORIGIN_TRACKING" within the opening tag of each the build elements identified in step 4. For example:

    <build index="true" export="ODASA_JAVA_CLASS_ORIGIN_TRACKING">mvn clean install</build>

Aspects of enabling Java class origin tracking

You should be aware of the following aspects of origin tracking. 

Modifications to class files

The default method of class identification does not modify the output files. The files produced by the build process are the same as those generated by a non-Semmle build. When you enable origin tracking, Java class files contain a new attribute, as described above. The modification will not change the behavior of the class file, however it is likely to change the file size and any hashes or fingerprints of the file (such as the SHA sum). 

Note

Class files that exist in the project within jar files are not modified – only class files produced by the compiler during extraction.

Changes to analysis results

In principle, the results of almost any Java analysis query could be affected by enabling origin tracking. In practice, you are most likely to observe changes in the results of code duplication queries, which may now find new true positives if separate classes had previously been treated as a single class.