[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: 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 > >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]