JDT Core/Null Analysis/External Annotations

Note
This page describes unreleased work in progress. See bug 331651 as the umbrella bug for this work area

Attaching External Annotations to libraries

Annotation-based null analysis is incomplete as long as libraries consumed by a project have no null annotations in their API. To fill this gap, it should be possible to attach "external annotations" to a library after the fact, i.e., without touching and re-packaging the library itself.

Configuration in the IDE

JDT should understand a new classpath attribute called "annotationpath", which - similar to attaching sources and javadoc - attaches a collection of external annotations to a particular classpath entry pointing to a library. Several packagings of such a collection of external annotations have been considered:

directory tree

this packaging is similar to how Java sources are stored in a directory tree, where each directory represents a package and each contained file represents one primary type (class, interface, enum)

Status: implemented

zip

this packaging simply stores a directory tree in one compressed archive file, inside of which the same structure as above is preserved

Status: implemented

big file

if annotations are sparse, instead of many tiny files it might be convenient to combine annotations for many types into one file. This could be one file per library or one file per package

Status: not implemented

combined

this packaging is a combination of "zip" and "directory tree". It is proposed in order to consume existing distributions of external annotations in zip format, while still being able to incrementally add more annotations as required by the consuming project. This packaging is inspired by Eiffel's melting ice technology. For external annotations to melt would mean that annotations for a particular type would be extracted from the zip archive and stored as an editable file in the corresponding directory tree. Changes are then made to this file, which will override the content of the zip archive.

Status: not implemented

Details are tracked in these bugs

JDT/Core

bug 440477 [null] Infrastructure for feeding external annotations into compilation

JDT/UI

bug 440815 External annotations need UI to be attached to library jars on the classpath

Headless consumption

It should also be possible to consume external annotations when compiling outside the IDE or under the control of a build system like ant, maven or gradle. For this reason the batch compiler must be configured in situations where no Eclipse project is available as the context for compilation.

one dedicated path

Using the command line option "-annotationpath location" the batch compiler can be configured to read external annotations from one specified locations, which requires to merge annotations for all relevant libraries into one package (see the packagings discussed above)

Status: implemented

from classpath

Alternatively, the batch compiler could be configured to scan the classpath used for compilation in order to search external annotations for any type it is reading from a library. This option may be less efficient than other approaches, but it provides the easiest means for integrating external annotations into existing concepts of dependency management - external annotation packages would be just additional artifacts to put on the classpath for compilation. This option would be enabled by an argument-less switch on the command line, say "-externalAnnotationsFromClasspath"

Status: not implemented

Details are tracked in this bug:

JDT/Core

bug 440687 [compiler][batch][null] improve command line option for external annotations