JAVA-98: Summary of current status and proposed direction for resolution

[Simon Nash <oasis@cjnash.com>]

So far we have agreed the following as directional resolutions:

  1. We won't follow the JSR 250 guideline about method-level
     annotations cancelling the effect of class-level annotations
     of the same type.

  2. We won't use @Inherited on any intent annotations.

I believe the following are generally accepted by the TC.

  3. We will follow the other JSR 250 guidelines and we will point
     to them by reference rather than copying them into the SCA spec.

  4. We will not use @Inherited on any of the non-intent annotations.

Questions that still need to be answered:

  A) If we retain specific intent annotations, how do they relate to
     the @Requires annotation?  They cannot be considered exactly
     equivalent because users may have defined other semantics for them.

  B) What are the precise rules for merging between method-level
     annotations and class-level annotations?

  C) How do intent annotations on a service interface interact with
     intent annotations on the implementation?

  D) How are intent annotations on the implementation represented in
     the component type now that <operation> elements have been removed?

My proposed answers to the above questions:

A) Specific intent annotations can appear together with @Requires
    on the same Java program element.  If they do, the annotations
    contributed by specific intent annotations are merged with those
    contributed by @Requires, with the specific intent annotations
    taking priority.  This means that for any given program element,
    if any intents contributed by specific intent annotations have
    the same base intent names as any intents contributed by @Requires,
    all the intents with these base names contributed by @Requires
    are ignored for that program element.

    More precisely, the effective intents for a Java program element
    (class, interface, service method, setter method, field, or
    constructor parameter) are computed as follows:
    1. Look on the program element for intents contributed by specific
       intent annotations.  If different specific intent annotations
       contribute intents with the same base intent name, this is
       an error.
    2. Look on the program element for intents contributed by @Requires
       with base intent names that differ from those of any intents
       found in step 1.

B) The effective intents for a service method are computed as follows:
    1. Look on the method for intents using the rules in A) above.
    2. Look on the declaring class for intents using the rules in
       A) above, disregarding any intents with the same base intent
       names as intents that were found in step 1.

C) For service methods, the effective intents are found by using
    the following algorithm:
    1. For each method of the service interface, apply the algorithm
       described in B) above to the service implementation class.
    2. For each method of the service interface, apply the algorithm
       described in B) above to the service interface, disregarding
       any intents with the same base intent names as intents that
       were found in step 1.

   For references and properties, the effective intents are found by
   using the following algorithm:
    1. Apply the algorithm described in A) above to the program element
       defining the reference or property.  Any intents found for a
       reference are applied to all methods of the reference.
    2. Apply the algorithm described in A) above to the implementation
       class containing the program element defining the reference or
       property, disregarding any intents with the same base intent
       names as intents that were found in step 1.  Any intents found
       for a reference are applied to all methods of the reference.
    3. For a reference, apply the algorithm described in B) above to
       each method of the service interface, disregarding any intents
       with the same base intent names as intents that were found in
       steps 1 or 2.

D) The SCA runtime creates a new interface or class that extends the
    Java interface or class that was used to define the SCA service
    or reference.  This interface or class contains method-level
    @Requires annotations specifying the intents that were derived from
    following the steps in C) above.  This new interface or class
    is used for the introspected component type.

   Simon