ISSUE 121: Work in progress zip file

[Simon Nash <oasis@cjnash.com>]

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