OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

sca-j message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

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

I have uploaded a second draft of the SCA-J APIs and annotations
zip file here:

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 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

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]