[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,
Just one minor comment on the latest updates. I see you have
removed the whole (*) footnote from the table in section 9.17
rather than just removing the RFC2119 keywords. I was only
suggesting removing the keywords; sorry that I wasn't clear enough
about this. I think the footnote is useful for information.
Also, this removal has left a dangling reference (*) from the
top left-hand box in the table.
I also noticed one small typo. In line 1434, @Initi should be @Init.
Both of these points are editorial.
Simon
Mike Edwards wrote:
>
> Folks,
>
> New revision addressing the points in Simon's note:
>
> http://www.oasis-open.org/apps/org/workgroup/sca-j/download.php/31684/sca-javacaa-1.1-spec-cd02-rev3_proposal3.pdf
>
> http://www.oasis-open.org/apps/org/workgroup/sca-j/download.php/31686/sca-javacaa-1.1-spec-cd02-rev3_proposal3.doc
>
>
> I intend to propose this as the resolution of Issue 104.
>
>
> 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: 13/03/2009 10:05
> Subject: Re: [sca-j] [ISSUE 104] RFC2119 Language is needed for CAA
> Specification - Proposal
>
>
> ------------------------------------------------------------------------
>
>
>
> 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/
>
>
>
>
>
>
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]