Re: [sca-j] [ISSUE 104] RFC2119 Language is needed for CAA Specification- Proposal

[Simon Nash <oasis@cjnash.com>]

Mike,
See inline for my responses to your responses.

   Simon

Mike Edwards wrote:
> 
> Simon,
> 
> Thanks for your thorough review,
> 
> responses inline...
> 
> There is one item that will require you to raise an issue if you want 
> the text of the document changed (lines 1821 / 1832),
> 
> 
> 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
> 
> 
> From: 	Simon Nash <oasis@cjnash.com>
> To: 	OASIS Java <sca-j@lists.oasis-open.org>
> Date: 	02/03/2009 00:02
> 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.
> *<mje>Fixed</mje>*
>  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..."
> *<mje>Fixed</mje>*
>  3. Line 463: Similar to point 2, change "The SCA Java Common
>     Annotations specification..." to "This specification..."
> *<mje>Fixed</mje>*
>  4. The EBNF syntax used in lines 527 though 530 should be
>     accompanied by a cross-reference [EBNF-Syntax].
> *<mje>Fixed</mje>*
>  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)*
> *<mje>Fixed</mje>*
>  6. The non-terminal "qualifier" in line 530 is not defined.
>     Following line 530, this line should be added:
>       qualifier ::= NCName
> *<mje>Fixed</mje>*
>  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.
> *<mje>Fixed</mje>*
>  8. In lines 542-543, replace "specific @Confidentiality intent
>     annotation" by "@Confidentiality specific intent annotation".
> *<mje>Fixed</mje>*
>  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)?
> *<mje>Fixed</mje>*
> 10. Line 560: change "of an intent annotation" to "of a specific intent
>     annotation".
> *<mje>Fixed</mje>*
> 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.
> *<mje>Language made non-normative - normative stuff is in section 9</mje>*
> 12. Lines 608 through 610 have non-keywords in bold font.
> *<mje>Fixed</mje>*
> 13. Lines 625 through 627 have non-keywords in bold font.
> *<mje>Fixed</mje>*
> 14. Line 753 has a non-keyword in bold font.
> *<mje>Fixed</mje>*
> 15. Line 770 has a keyword in non-bold font.
> *<mje>Fixed</mje>*
> 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".
> *<mje>Fixed, but used "callback interface" for the second occurrance</mje>*
> 17. After line 1203, add the sentence "When used in this way, the
>     @Callback annotation MUST NOT specify any attributes."
> *<mje>Fixed, with wording adjusted to allow statement to stand alone</mje>*
> 18. Lines 1204 through 1211 should be removed as they are a duplicate
>     subset of the following example in lines 1213 through 1229.
> *<mje>Fixed</mje>*
> 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.
> *<mje>Fixed</mje>*
> 20. In line 1419, change "annotate the Java class" to "mark the Java 
> class".
> *<mje>Fixed</mje>*
> 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.
> *<mje>Fixed</mje>*
 >
The wording for JCA90009 should be changed to match the form of
wording for JCA90005.  The resulting wording would be: If there
is a method annotated with @Init that matches the criteria for the
annotation, the SCA runtime MUST....".  The important difference
from the current wording is the inclusion of the phrase "annotated
with @Init".

> 22. Line 1610: Highlighted conformance item should not include
>     "However," at start of sentence.
> *<mje>Fixed</mje>*
> 23. Line 1613: Highlighted conformance item should not include
>     "However," at start of sentence.
> *<mje>Fixed</mje>*
> 24. Lines 1641 and 1642: agree that this should be normative.  Wording
>     similar to line 2080 would be suitable.
> *<mje>Fixed</mje>*
 >
The conformance target for JCA90047 should be the SCA runtime, as in
JCA90020 and JCA90021.  The rewording would be "....java.util.Collection,
then the SCA runtime MUST introspect the component type of the
implementation with a <property/> element....".

> 25. Line 1701: Highlighted conformance item should not include
>     "However," at start of sentence.
> *<mje>Fixed</mje>*
> 26. Line 1761: conformance target should be the SCA runtime.  Wording
>     similar to line 2080 would be suitable.
> *<mje>Fixed</mje>*
> 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.
> *<mje>Fixed</mje>*
> 27. Line 1765: conformance target should be the SCA runtime.  Wording
>     similar to line 2080 would be suitable.
> *<mje>Fixed</mje>*
> 28. Line 1771: non-normative "should".
> *<mje>Fixed</mje>*
> 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.
> *<mje>This does affect JAVA-131 - all I did was to faithfully render 
> what was perviously in the text*
> *of the spec.  I've updated the words to more clearly state their 
> meaning.  Feel free to throw rocks.</mje>*
> 30. Line 1803: Lower case "must".
> *<mje>Fixed</mje>*
> 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.
> *<mje>As for 1802 above</mje>*
> 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.
> *<mje>Fixed</mje>*
> 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.
> *<mje>See if you like the tweaks I've made - to go much further will 
> require an issue</mje>*
 >
The tweaks are good, but they have introduced a new inconsistency.
This inconsistency is the change in JCA90032 from "if the target of
a ServiceReference has become unavailable" to "if the target service
of a ServiceReference has become unavailable".  This is different
from JCA90028 and JCA90035, which talk about "if the target of a
reference....or ServiceReference....has become unavailable".
For consistency, I think it would be best to revert JCA90032 to its
previous wording, while leaving the new words for JCA90029, JCA90033
and JCA90036.

> 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".
> *<mje>This definitely requires an issue since it changes the meaning of 
> the text that was*
> *there.</mje>*
 >
I will submit a new issue for this.

> 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.
> *<mje>Fixed</mje>*
 >
No change has been made here.  Is there some reason why you think
these words should not be normative?

> 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.
> *<mje>Fixed</mje>*
> 37. In line 1848, change "array or collection MAY change" to "array or
>     collection change".
> *<mje>Fixed</mje>*
 >
No change has been made here.  This combination of MAY and MUST in
the same conformance statement doesn't seem right to me.

> 38. Line 1849: change "the setter methor MUST be called" to "the SCA
>     runtime MUST call the setter method".
> *<mje>Fixed</mje>*
 >
No change has been made here.  I think the change is needed.

> 39. In the reinjection table, change the title of the first column from
>     "Reference" to "Injected Reference or ServiceReference".
> *<mje>Fixed</mje>*
> 40. In the reinjection table, add "**" to the title of the second column 
> from
>     "Reference" to "Injected Reference or ServiceReference".
> *<mje>Fixed</mje>*
> 41. In the reinjection table, add a row for "Target service has become
>     unavailable" under the row for "Target service undeployed".
> *<mje>Fixed</mje>*
 >
This also requires a change to the wording of the "Target service
undeployed" row.  In the last box of this row, the words "or unavailable"
should be removed, because this case is now covered by the following row.

> *<mje>Note that I also made the whole table non-normative, as I 
> suggested in my comment</mje>*
 >
There are still some RFC2119 keywords in the footnotes to the table.
These can be removed because they are covered by conformance statements
in the text.

   Simon

> 42. Line 2052: change "the interface MUST treated" to "the SCA runtime
>     MUST treat the interface".
> *<mje>Fixed</mje>*
> 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".
> *<mje>Fixed</mje>*
> 44. Line 2055: change "the generated @WebService annotation MUST be taken"
>     to "the SCA runtime MUST take the generated @WebService annotation".
> *<mje>Fixed</mje>*
> 
>   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/
>  >
>  >
>  >
>  >
>  >
>  >
> 
> 
> 
> ---------------------------------------------------------------------
> 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
> 
> 
> 
> 
> 
> 
> ------------------------------------------------------------------------
> 
> /
> /
> 
> /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/
> 
> 
> 
> 
> 
>