Composite Annotations

This is draft for comment of a project coin proposal to allow language level composite annotations to the JDK. This should make it easier for annotation rich frameworks to provide stereotypes that represent common combinations. This came out of a discussion on the atmosphere mailing list.

PROJECT COIN SMALL LANGUAGE CHANGE PROPOSAL FORM v1.0

AUTHOR(S): Gerard Davison

OVERVIEW

Provide a two sentence or shorter description of these five aspects of the feature:

FEATURE SUMMARY: Should be suitable as a summary in a language tutorial.

Add the ability to compose existing annotations as meta annotations to be able to easily create stereotypes for common combinations.

MAJOR ADVANTAGE: What makes the proposal a favorable change?

Libraries can provide common "stereotype" made up of sensible default combinations of annotations.

MAJOR BENEFIT: Why is the platform better if the proposal is adopted?

Potentially shallower learning curve for annotation based frameworks.

MAJOR DISADVANTAGE: There is always a cost.

It is possible that by hiding configuration behind stereotypes that the code becomes harder to diagnose. This can be ameliorated to some extent with tool support and suitable naming conventions.

ALTERNATIVES: Can the benefits and advantages be had some way without a language change?

Yes, it is possible for each and every framework to introduce there own Composite marker annotation and processor. For example spring has something quite similar in there meta annotations:

http://blog.springsource.com/2009/05/06/spring-framework-30-m3-released/

Each implementation would be different then as not as easily accessible as a language feature would be.

EXAMPLES Show us the code!

SIMPLE EXAMPLE: Show the simplest possible program utilizing the new feature.

package java.lang.annotation;

@Rentention(SOURCE)
@Target(ANNOTATION_TYPE)
public @interface Composite
{
}


package x;

@Composite
@SuppressWarnings({"unchecked"})
@Target(METHOD)
public @interface SuppressUnchecked
{
}

package y;

public class ExampleService
{
   @SupressUnchecked
   public void methodWithOddCast()
   {
       ...
   }
}

ADVANCED EXAMPLE: Show advanced usage(s) of the feature.

@Composite
@WebService
@Binding(SOAPBinding.SOAP_12_BINDING)
@Addressing
@Target(CLASS)
public @interface SOAP12AddressingWebService
{
}

@SOAP12AddressingWebService
public class ExampleService
{
   ...
}

DETAILS SPECIFICATION: Describe how the proposal affects the grammar, type system, and meaning of expressions and statements in the Java Programming Language as well as any other known impacts.

The lexical grammar is unchanged. The type system is unchanged. The annotation type section is modified (JLS ?.?) so that an annotation can be applied to composite annotation if that annotation is tagged with @Composite and the target and retention matches that of the composite annotation. This prevents all annotations having to be modified with the ANNOTATION_TYPE modifier.

COMPILATION: How would the feature be compiled to class files?

This feature modifies the process which is used to gather the annotation properties. In general the rule is that values directly applied to class will override values provided by composite annotations. So the process for building the values for a particular class should be:

1. For each annotation attached to the class that isn't marked as @Composite store the values for this class. Once defined the value will not change.
2. For each annotation attached to the class in source order that is marked as @Composite apply any values that have not been previously defined. Recursively apply the values for any attached composite annotations.

The compilation should fail if there is a loop of @Composite annotations. (QUERY should we allow multi-level or is one turtle enough.)

For a client reading the class using the reflective API it should appear as if the annotations provided by the composite annotations were applied to the class directly. (QUERY should the composite annotations be erased at runtime?)

TESTING: How can the feature be tested?

It should be a matter of generating various simple cases with differing levels of composite annotations. Corner cases should be provided with inconsistent target or retention policies.

LIBRARY SUPPORT: Are any supporting libraries needed for the feature?

REFLECTIVE APIS: Do any of the various and sundry reflection APIs need to be updated? This list of reflective APIs includes but is not limited to core reflection (java.lang.Class and java.lang.reflect.*), javax.lang.model.*, the doclet API, and JPDA.

As the annotations are unwound at compile time this won't affect any reflective API that works from a class file. It is going to pose a question of what is the correct thing to do when looking at a source file. (QUERY not sure what the best thing is to do)

OTHER CHANGES: Do any other parts of the platform need be updated too? Possibilities include but are not limited to JNI, serialization, and output of the javadoc tool.

Yes, the javadoc tool should show both the composite and the applied annotations in some way.

MIGRATION: Sketch how a code base could be converted, manually or automatically, to use the new feature.

Roll up some application to use stereotypes as applicable.

COMPATIBILITY BREAKING CHANGES: Are any previously valid programs now invalid? If so, list one.

All existing programs remain valid.

EXISTING PROGRAMS: How do source and class files of earlier platform versions interact with the feature? Can any new overloadings occur? Can any new overriding occur?

The semantics of existing class files and legal source files and are unchanged by this feature.

REFERENCES EXISTING BUGS: Please include a list of any existing Sun bug ids related to this proposal.

None

URL FOR PROTOTYPE (optional):

No prototype at this time.