Re: [sca-j] Two ways to specific the same intent

[Simon Nash <oasis@cjnash.com>]

Anish Karmarkar wrote:
> On the last call we had a short discussion about whether we should keep 
> our current dual way of specifying annotations. Someone (I think Simon) 
> had asked for an example. Here is one:
> 
> For the 'confidentiality' annotation, currently one can use either the 
> @Requires or @Confidentiality, here is how the two look:
> 
> @Requires({CONFIDENTIALITY})
> 
> vs.
> 
> @Confidentiality
> 
> 
> Note that all sca defined intents are defined as constants and we 
> encourage creators of new intent-specific annotations to define 
> equivalent constants.
 >
The constant CONFIDENTIALITY is currently defined as part of the
@Confidentiality annotation definition.  If specific intent
annotations were removed, where would this constant be defined?
The obvious place is the Constants interface, but this has
disadvantages:

  1. Everyone using the @Requires annotation would need to import
     the necessary definitions from the Constants interface using
     code like:
     import static org.oasisopen.sca.Constants.CONFIDENTIALITY;

  2. It would be hard to decide which SCA intents should be defined
     in the Constants interface, and it would be difficult to ensure
     that the Constants interface contains all the required definitions.
     The SCA intents are all owned by other TCs, and it would be a
     significant maintenance burden for these TCs to coordinate with
     the SCA-J TC to ensure the correct set of constants appears in
     the Constants interface.  It is almost inevitable that mistakes
     and omissions would occur.  Placing the constants in specific
     intent annotation definitions solves this problem.

  3. This approach doesn't work for user-defined intents, because
     these could not have their definitions included in the Constants
     interface.  These would have to use some other mechanism for
     holding their constants, which would cause user confusion because
     different intents would use different mechanisms.  Placing the
     constants in specific intent annotation definitions solves this
     problem.

 >                       The above example is based on existing
> definitions, obviously the number of characters one has to type depend 
> on the intent definition and the strings used for defining the constant 
> (eg, MESSAGE vs. MSG). Also note that when using multiple intents the 
> number of extra characters (the "Requires" part) are amortized over all 
> the intents. Eg: @Requires({CONFIDENTIALITY, INTEGRITY})
> 
> My preference for getting rid of two ways to do the same thing is based 
> on the following:
> 
> 1) Multiple ways to do the same thing is usually not a good idea, IMHO, 
> unless there is a significant advantage. The number of extra characters 
> here doesn't seem to justify (to me) defining a bunch of new 
> annotations, and @Intent @Qualifier.
> 
I think the main advantage of the current approach is that it provides
a framework for infrastructure developers to define new intents in Java
(including the necessary constants) and for business developers to use
those definitions easily and conveniently.

> 2) In figuring out which intents are applicable, one has to merge the 
> @Requires with intent-specific annotations to get the full set. Makes it 
> slightly harder wrt understanding the code and its intent (pun intended 
> ;-) ).
> 
We definitely would need rules for the following combinations:
   Multiple @Requires annotations on a class or method
   @Requires together with specific intent annotations on a class or method
   @Requires on a class and @Requires on a method of the class
   @Requires on a class and specific intent annotations on a method of the class
   Specific intent annotations on a class and @Requires on a method of the class

Here is my attempt to define suitable rules for the above.  The following
steps would be performed in the order stated:
  1. All specific intent annotations are logically replaced by the
     equivalent @Requires annotation.
  2. All @Requires annotations on the same class or method are merged
     by combining the contents of their "values" attribute arrays (in
     some arbitrary order).
  3. For each method of the class, the intents for the method's @Requires
     annotation are applied.  If the class has any @Requires intents whose
     base intent name isn't present in the method's @Requires annotation,
     these intents are also applied to the method.

This is a slightly more explicit version of what's already stated
in section 7.3 (though I note in passing that there seems to be no
normative MUST statement covering the 7.3 rules).  If we did not
have specific intent annotations, step 1 in the above list could be
eliminated.  This doesn't seem to be a huge simplification.

> 3) This makes inheritance issue complex (I know there is a proposal to 
> get rid of it, but I'm not convinced (yet) that this is best proposal, 
> though can live with it. And even if we remove @Inherited, un-overridden 
> methods still get the annotations from the superclass). What happens if 
> @Requires is on a class and @Confidentiality is on a method (or vice 
> versa) ... and there is inheritance. We get into exactly the kind of 
> situation that JSR 250 talks about wrt @WebMethod and @WebService. I 
> find that unintuitive and hard to remember.
> 
I don't think we do get into the JSR 250 situation.  Without annotation
inheritance, class-level annotations only affect methods declared
within that class (a simple rule).  Also, annotations on one method
of a class can never change the effective annotations on the class's
other methods (another simple rule for SCA, but not true in JSR 250).
These rules seem very simple and intuitive and I don't see how they
could lead to the problematical @WebService and @WebMethod situation.

   Simon

> -Anish
> -- 
> 
> ---------------------------------------------------------------------
> To unsubscribe from this mail list, you must leave the OASIS TC that
> generates this mail.  Follow this link to all your TCs in OASIS at:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
> 
>