com.iparelan.util.annotations
Annotation Type NoBinaryAnnotations

@Target(value=PACKAGE)
@Retention(value=CLASS)
@Copyright(value="Copyright © 2008, Iparelan Solutions, LLC. All rights reserved.")
public @interface NoBinaryAnnotations

This annotation exists to solve the problem of unnecessarily invoking the compiler due to the lack of a corresponding object file for a package-info.java file. Solving this problem allows for faster build script execution.

Declares that a package has no annotations (other than this one) having a binary (object/byte code) representation. This constraint is not enforced by the compiler, but an annotation processor could likely be devised for such enforcement.

Note that annotating a package with this annotation forces package object code generation, so the name of this annotation is paradoxical. Perhaps it could have been called NullBinaryAnnotation, MeaninglessBinaryAnnotation, or BinaryMarker.

Detailed Problem Description

When a package contains a Java source file named package-info.java the compiler will compile the file just as it does for any other Java source file. However, the package-info.java is a special source file: its contents are restricted to either documentation comments (Javadoc) for the package, annotations for the package, or both -- no source code proper may be present as "packages are not defined in source files." (The Java Programming Language, 4th ed. sec. 19.5.1).

This lack of source code proper means that "compiling" package-info.java may not require the creation of object/byte code in the form of a corresponding Class file (.class). In particular, no object code needs to be generated if no package annotation exists with a retention policy "stronger" than SOURCE. Only stronger retention policies (CLASS (the default annotation retention policy) and RUNTIME) produce a binary representation of an annotation, and thus require object code generation.

Each subsequent compilation will invoke the compiler on the package-info.java "source code" file in the absence of a corresponding, up-to-date package-info.class object code file. Such unnecessary compiler invocations have the effect of increasing build script execution time.

Static Analysis

The need for the NoBinaryAnnotations annotation is reduced when source code undergoes static analysis with tools that support package annotation that has a retention policy strength greater than SOURCE.

FindBugs is one such tool. It supports the DefaultAnnotation annotation that declares that specified annotations be applied to all classes, fields, and methods of a package. This annotation is retained in class files so applying DefaultAnnotation to a package file obviates the need for NoBinaryAnnotations.

Usage Suggestion

When development has produced some "final" code for a particular version, the last build, or last few builds could change the retention policy of this annotation to RetentionPolicy.SOURCE to remove extraneous Class files in deployment bundles.

Version:

July 2008

Author:

Greg Mattes