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.
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
true for the duration of extraction.
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).
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.