Re: [sca-j] ISSUE 121: Work in progress zip file

[Simon Nash <oasis@cjnash.com>]

I have uploaded a second draft of the SCA-J APIs and annotations
zip file here:
  http://www.oasis-open.org/apps/org/workgroup/sca-j/download.php/31164/javacaa-code-draft2.zip

This contains the complete set of APIs and annotations.

Here are some points for editorial action that I noted while
going through the annotations.

  1. Out of order import statements in @AllowsPassByReference,
     @Callback, @ComponentName, @Context, @Property, @Reference.

  2. Wrong syntax for @Target in @Callback.

  3. Wrong package name in @Confidentiality.

  4. Wrong import package name in @Integrity (for Constants import).

  5. Inconsistencies between @Property and @Reference wording:
      a. First sentence of second paragraph of @Property description
         ("The @Property.....method parameter.") is redundant and
         should be removed.  Also remove "However," at start of
         following sentence.
      b. @Reference should say "specifies" at start of description
         of "required" attribute.

Comments are most welcome.

   Simon

Simon Nash wrote:
> I have uploaded a partial first draft of the SCA-J APIs and
> annotations zip file here:
>  http://www.oasis-open.org/apps/org/workgroup/sca-j/download.php/31135/javacaa-code-draft1.zip 
> 
> 
> At present only the contents of the org.oasisopen.sca package are
> included.  I would welcome any comments on how I have done this
> before I proceed with adding the annotations.  In particular:
> 
>  a) I was surprised to see that the javadoc index page puts all
>     interfaces, classes and exceptions together into a single list.
>     Other javadocs I have seen have had separate lists for these.
>     Does anyone know how to get these separated into separate lists?
> 
>  b) I'm surprised to see no description for ComponentContext on
>     the overview page.  There is a short description for this in
>     the source file.  Does anyone know how to fix this?
> 
> I resisted the temptation to "improve" the descriptions of the
> interfaces, classes and methods.  I think it is important to keep
> the spec and code fully in sync, and the best way to ensure this
> is to make any changes in the spec first.
> 
> As a general comment, some of the descriptions for interfaces,
> classes and methods are very brief and should be expanded.  I have
> not made specific mention of these.  Reading the javadoc should
> make it fairly clear where changes are needed.  I did find some
> specific points for action or discussion, which are listed below.
> 
>  1. The descriptions of ComponentContext.getService() and
>     getServiceReference() talk about throwing an
>     IllegalArgumentException, but this is not shown on the
>     signatures.  In contrast, ComponentContext.cast() has
>     IllegalArgumentException on the signature but this is
>     not mentioned in the description.  How should we handle
>     this for unchecked exceptions?
> 
>  2. There is a missing "of" in the description of
>     ComponentContext.getServiceReferences(): "... list typed
>     service references...".
> 
>  3. On ComponentContext, the method descriptions for
>     getRequestContext() and cast() are in the wrong order.
> 
>  4. ComponentContext needs an import for java.util.Collection.
> 
>  5. In the description of RequestContext.getServiceReference(),
>     "CallableReference" needs to be changed to "ServiceReference".
> 
> More later...
> 
>   Simon
> 
> 
> 
> ---------------------------------------------------------------------
> 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
> 
>