[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [sca-j] [ISSUE 104] RFC2119 Language is needed for CAA Specification- Proposal
Mike, Sorry for the delay in sending these. I have had an extremely hectic weekend! As well as comments on the RFC2119 changes, I have also included a few other editorial comments on things I noticed as I reviewed the document. All line numbers relate to the PDF version of the document. 1. Line 188: Highlighted conformance item should not include "However," at start of sentence. 2. Line 458: It's odd to see a reference to "The SCA Java Common Annotations specification" from text within this specification. Change "The SCA Java Common Annotations specification has..." to "This specification defines..." 3. Line 463: Similar to point 2, change "The SCA Java Common Annotations specification..." to "This specification..." 4. The EBNF syntax used in lines 527 though 530 should be accompanied by a cross-reference [EBNF-Syntax]. 5. The definition of the EBNF syntax used in lines 527 though 530 requires literals to be enclosed in either single or double quotes. (Without this, it would not be clear whether characters such as "(" are to be interpreted as literals.) Using this approach, line 52 should read '@Requires("' qualifiedIntent '"' (',"' qualifiedIntent '"')* ')' and line 530 should read qualifiedIntent ::= QName ('.' qualifier)* 6. The non-terminal "qualifier" in line 530 is not defined. Following line 530, this line should be added: qualifier ::= NCName 7. The convention for this form of EBNF is that symbols are written with an initial capital letter if they are the start symbol of a regular language, otherwise with an initial lowercase letter. See http://archives.devshed.com/forums/standards-105/some-editorial-comments-on-a-1-ebnf-productions-797670.html for an explanation of "regular language". This would require "qualifier" and "qualifiedIntent" in lines 527 through 530 to be written using initial capitals. 8. In lines 542-543, replace "specific @Confidentiality intent annotation" by "@Confidentiality specific intent annotation". 9. The EBNF syntax used in lines 552 though 556 requires literals to be enclosed in either single or double quotes. Also, the <> and [] symbols used in line 552 don't conform to this variant of EBNF. Correcting these problems, line 552 should read '@' Intent ('(' qualifiers ')')? Line 555 should read qualifiers ::= '"' qualifier '"' (',"' qualifier '"')* Line 556 should read qualifier ::= NCName ('.' qualifier)? 10. Line 560: change "of an intent annotation" to "of a specific intent annotation". 11. Lines 573 and 574 have non-normative "should" and line 576 has non-normative "required". This paragraph needs to be replaced by normative language with rules for qualifiers. 12. Lines 608 through 610 have non-keywords in bold font. 13. Lines 625 through 627 have non-keywords in bold font. 14. Line 753 has a non-keyword in bold font. 15. Line 770 has a keyword in non-bold font. 16. In lines 1197 and 1198, change "a callback interface, which takes the Java class object of the callback class as a parameter" to "a callback interface by specifying the Java class object of the callback class as an attribute". 17. After line 1203, add the sentence "When used in this way, the @Callback annotation MUST NOT specify any attributes." 18. Lines 1204 through 1211 should be removed as they are a duplicate subset of the following example in lines 1213 through 1229. 19. In lines 1394 to 1396, conformance statement JCA90006 is redundant and should be removed. Conformance statement JCA90001 states that the SCA runtime MUST NOT run the component in this case, which means there will be no instance on which @Destroy could be called. 20. In line 1419, change "annotate the Java class" to "mark the Java class". 21. In lines 1444 to 1447, conformance statement JCA90010 is redundant and should be removed. Conformance statement JCA90001 states that the SCA runtime MUST NOT run the component in this case, which means there will be no instance on which @Init could be called. 22. Line 1610: Highlighted conformance item should not include "However," at start of sentence. 23. Line 1613: Highlighted conformance item should not include "However," at start of sentence. 24. Lines 1641 and 1642: agree that this should be normative. Wording similar to line 2080 would be suitable. 25. Line 1701: Highlighted conformance item should not include "However," at start of sentence. 26. Line 1761: conformance target should be the SCA runtime. Wording similar to line 2080 would be suitable. 26. Line 1761: change "not an array or a collection" to "not an array or any type that extends or implements java.util.Collection" for consistency with line 1764. 27. Line 1765: conformance target should be the SCA runtime. Wording similar to line 2080 would be suitable. 28. Line 1771: non-normative "should". 29. Line 1802: What does "MUST be represented as null" mean and what is the conformance target? Does this mean that the SCA runtime MUST inject null? This affects the resolution of JAVA-131. 30. Line 1803: Lower case "must". 31. Line 1803: What does "MUST be represented as an empty array or empty collection" mean and what is the conformance target? Does this mean that the SCA runtime MUST inject an empty array or empty collection? This affects the resolution of JAVA-131. 32. Lines 1812 and 1813: Last sentence of this paragraph ("Setter injection....to a change.") is non-normative and should not be part of conformance statement JCA90025. 33. Very confusing terminology in lines 1820, 1831 and 1841. In line 1820, "target of the reference has changed" does not mean the same as "reference target changes" in line 1815, despite the almost identical wording. The line 1815 words refer to the reference changing to point at a different target. The line 1820 words refer to the target service changing (this is made clear in the table). Similarly, the line 1831 and 1841 words refer to the target service changing. It would be better to use the phrase "target service" instead of "target" in lines 1820, 1831 and 1841. 34. In lines 1821 and 1832, "MAY continue to work" seems too weak. I think a better constraint would be "MUST either continue to work or throw an exception". 35. In line 1837, The non-highlighted text "This applies whether or not reinjection has taken place" is normative and should be part of the previous conformance statement JCA90034. 36. In line 1841, the execption thrown MAY be InvalidServiceException if the service is undeployed, or ServiceUnavailableException if the service is unavailable, for consistency with lines 1818, 1820, 1828 and 1830. 37. In line 1848, change "array or collection MAY change" to "array or collection change". 38. Line 1849: change "the setter methor MUST be called" to "the SCA runtime MUST call the setter method". 39. In the reinjection table, change the title of the first column from "Reference" to "Injected Reference or ServiceReference". 40. In the reinjection table, add "**" to the title of the second column from "Reference" to "Injected Reference or ServiceReference". 41. In the reinjection table, add a row for "Target service has become unavailable" under the row for "Target service undeployed". 42. Line 2052: change "the interface MUST treated" to "the SCA runtime MUST treat the interface". 43. Line 2054: change "the @org.oasisopen.sca.annotation.OneWay annotation MUST be treated" to "the SCA runtime MUST treat the @org.oasisopen.sca.annotation.OneWay annotation". 44. Line 2055: change "the generated @WebService annotation MUST be taken" to "the SCA runtime MUST take the generated @WebService annotation". Simon Mike Edwards wrote: > > Folks, > > Here is a proposal for Issue 104 which handles the RFC2119 language in > the CAA spec, done as an update to CD02 Rev2 > and a candidate for CD02 Rev3: > > http://www.oasis-open.org/apps/org/workgroup/sca-j/download.php/31351/sca-javacaa-1.1-spec-cd02-rev3_proposal.pdf > > http://www.oasis-open.org/apps/org/workgroup/sca-j/download.php/31350/sca-javacaa-1.1-spec-cd02-rev3_proposal.doc > > > Review and comments welcome!! > > Yours, Mike. > > Strategist - Emerging Technologies, SCA & SDO. > Co Chair OASIS SCA Assembly TC. > IBM Hursley Park, Mail Point 146, Winchester, SO21 2JN, Great Britain. > Phone & FAX: +44-1962-818014 Mobile: +44-7802-467431 > Email: mike_edwards@uk.ibm.com > > > ------------------------------------------------------------------------ > > / > / > > /Unless stated otherwise above: > IBM United Kingdom Limited - Registered in England and Wales with number > 741598. > Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU/ > > > > > >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]