OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

sca-j message

[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


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>
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>
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>
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>
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>
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>
38. Line 1849: change "the setter methor MUST be called" to "the SCA
    runtime MUST call the setter method".
<mje>Fixed</mje>
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>
<mje>Note that I also made the whole table non-normative, as I suggested in my comment</mje>
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






[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]