Java News from Friday, October 27, 2006

Sun has submitted JSR-308, Annotations on Java Types, to the Java Community Process. According to the JSR,

We propose an extension to Java's annotation system that permits annotations to appear on any use of a type, not just on class/method/field/variable declarations, as is the case in Java SE 6. Such a generalization removes arbitrary limitations of Java's annotation system, and it enables new uses of annotations.

This JSR specifies the syntax of extended Java annotations, but it makes no commitment as to their semantics. As with Java's existing annotations, the semantics is dependent on annotation processors (compiler plug-ins), and not every annotation is necessarily sensible in every location where it is syntactically permitted to appear. This proposal is compatible with existing annotations, such as those specified in JSR 250, "Common Annotations for the Java Platform", and JSR 305, "Annotations for Software Defect Detection".

This proposal does not change the compile-time, load-time, or run-time semantics of Java. It does not change the abilities of Java annotation processors. The proposal merely makes annotations more general --- and thus more useful for their current purposes, and also usable for new purposes that are compatible with the original vision for annotations.

The new Java syntax allows annotations in the following locations. (The specific annotation names, such as @NonNull, are examples only; this document does not propose any annotations, merely specifying where they can appear in Java code.)

method receivers:
public int size() @Readonly { ... }
generic type arguments:
Map<@NonNull String, @NonEmpty List<@Readonly Document>> files;
Document[@Readonly] docs1;
Document[][@Readonly] docs2 = new Document[2][@Readonly 12];

(docs1 is an unmodifiable one-dimensional array of mutable Documents. docs2 is a mutable array whose elements are unmodifiable one-dimensional arrays of mutable Documents.)
myString = (@NonNull String)myObject;
type tests:
boolean isNonNull = myString instanceof @NonNull String;
object creation:
new @NonEmpty @Readonly List(myNonEmptyStringSet)
type parameter bounds:
class Folder { ... }
class inheritance:
class UnmodifiableList implements @Readonly List<@Readonly T> { ... }
throws clauses:
void monitorTemperature() throws @Critical TemperatureException { ... }

Java annotations (including the extended annotations) must be stored in the class file for two reasons. First, they may be part of the interface of a class and, if so, must be available to the compiler (really, to the type-checking plug-in) when compiling clients of the class. Second, since class files may originate from any source, the information may be useful in other contexts, such as compile-time verification.

This JSR proposes conventions for storing the new annotations, as well as for storing local variable annotations, which are permitted in Java syntax but currently discarded by the compiler. Class files already store annotations in the form of ``attributes''. JVMs ignore unknown attributes. For backward compatibility, we use new attributes for storing the type annotations. In other words, our proposal merely reserves the names of a few attributes and specifies their layout. Our proposal does not alter the way that existing annotations on classes, methods, method parameters, and fields are stored in the class file. Class files generated from programs that use no new annotations will be identical to those generated by a standard Java SE 6 (that is, pre-extended-annotations) compiler.

This JSR introduces two new attributes: RuntimeVisibleTypeAnnotations and RuntimeInvisibleTypeAnnotations. These attributes are structurally identical to the existing RuntimeVisibleAnnotations and RuntimeInvisibleAnnotations attributes described above with one exception: rather than an array of annotation elements, RuntimeVisibleTypeAnnotations and RuntimeInvisibleTypeAnnotations contain an array of extendedannotation elements. An extendedannotation element is like an annotation element, but it adds a target_type field and a reference_info field.

The specification will also attempt to provide a simple approach for writing annotations with array-valued elements.

Comments are due by October 30.

Mark Hale has posted version 0.94 of JSci, a class library containing many useful mathematical and scientific functions such as complex arithmetic. This release moves the matrix and vector classes into separate sub-packages, adds bisection and Newton-Raphson methods to NumericalMath, adds a a histogram graph, and adds an instruments package.