Add annotations for instance callbacks

• Key: JDO-638
• Type: Improvement
• Status: Open
• Priority: Minor
• Assignee: Unassigned
• Reporter: Matthew T. Adams
• Component/s: api2

Description

The current JDO annotations in javax.jdo.annotations do not include annotations equivalent to instance callbacks. We should add method annotations for each method in javax.jdo.InstanceCallback.

Comments

[Matthew T. Adams]

Attached patch contains annotations. TCK tests TBD.

[Craig Russell]

I have no philosophical objections to adding these annotations.

> TCK tests TBD.

;-) I suppose that will be in your next patch.

Also need the @Target and @Retention annotations on the annotations.

[Matthew T. Adams]

I'll add @Target & @Retention on next patch. TCK tests will have to be in patch after that. ;)

[Matthew T. Adams]

Added Target & Retention annotations. TCK tests still TBD.

[Matthew T. Adams]

How should we handle the case where a class both implements an instance callback interface and uses an instance callback annotation? Seems to me that f the annotated method is the same method as the instance callback interface method, it is not an error (warning would be nice), otherwise it's an error. I also would consider a stricter policy that says it's one or the other, interfaces or annotations, not both. What do you think?

[Michael Bouschen]

We discussed this during the JDO TCK conference call and came to the conclusion that JDO should support multiple methods being annotated with the same instance callback annotation. This also includes mixing annotations and implementing the instance callback interface, as long as the signature of the callback methods are correct. The order of execution of callbacks/annotated methods is not defined.

[Craig Russell]

Just to clarify, we discussed this issue during the conference call but didn't decide anything. Decisions are made on email and jira issue discussions.

[Matthew T. Adams]

The following proposes the ordering of annotated methods. I've added an order property to each of the annotations with javadoc as follows:

/**
* The order of execution of this method relative to other annotated
* callback methods. A lower order value means that the annotated method has
* a higher precedence among annotated methods, and a higher order, a lower
* precedence. Order values need not be contiguous among annotated methods.
* Methods that are implementations of the corresponding callback interface
* method are always called first. The order value {@link Integer#MAX_VALUE}
* , the default, signifies that the order is undefined among annotated
* methods. If other annotated methods define an order, those methods will
* be called before annotated methods with an undefined order. If other
* annotated methods define equal order values, then methods annotated with
* lower order values will be called before them, the methods with equal
* order values will be called in an undefined order, and then any methods
* with higher order values will be called after the methods with equal
* order values have been called. If a method that represents an
* implementation of the corresponding interface method carries this
* annotation, the annotation and its order are ignored, and the interface
* method is called first. If a subclass annotates a method with the same
* order as an annotated method in its superclass hierarchy, then the
* subclass's method is called first, otherwise the order values among all
* annotated methods in the class and its superclass hierarchy determine
* call order.
*/
int order() default Integer.MAX_VALUE;

Thoughts?