From: Mike Edwards
[mailto:mike_edwards@uk.ibm.com]
Sent: 06 February 2009 14:04
To: OASIS SCA Assembly List
Subject: Re: [sca-assembly] NEW ISSUE: RFC2119 Corrections to CD02 Rev3
Folks,
I'd like to
give Eric a huge vote of thanks for doing this thorough review. I had
noticed a couple of the
problems when
doing some other edits and put them on my todo list, but Eric did the really
comprehensive
review that was
needed and he dragged out all the problems.
I've built a
proposed set of fixes that I sent separately and I hope we can deal with them
next week....
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:
|
"Eric
Wells" <ejwells@sonic.net>
|
|
To:
|
"OASIS
SCA Assembly List" <sca-assembly@lists.oasis-open.org>
|
|
Date:
|
05/02/2009
20:53
|
|
Subject:
|
[sca-assembly]
NEW ISSUE: RFC2119 Corrections to CD02 Rev3
|
All,
I reviewed the SCA Assembly 1.1 CD02 Rev3 document for work on
the test
assertions and found a number of problems with the use of RFC2119 keywords.
There are quite a few errors, and while most seem to be
"editorial" there
are some that may require normative changes. I am not sure how we want to
handle these as there seem to be too many to review each individually
during
a call, therefore I've posted these as a new issue.
It may be more appropriate to issue an action to make the changes, but we
should at least decide if and how any normative changes should be made (and
reviewed).
Personally, I think it would be acceptable to make most of the optional
keywords normative (should -> SHOULD, may -> MAY, etc). We do not
necessarily have to test optional statements and if we mean that a feature
is optional then why not say so?
Obviously, compulsory items (must, required) will have to be reworded if
they are not normative.
I have attached a marked up version of the document with each item marked
with a comment - "RFC2119" - and a suggested correction -
"Fix:". For
convenience I've also included the text of these below.
Best Regards,
Eric.
Eric Wells.
Consulting Engineer.
Hitachi Computer Products (America) Inc.
San Francisco, CA. USA.
+1 (415) 656-4346
eric.wells@hitachisoftware.com
Based on SCA Assembly specification 1.1 CD02 rev3 (MS Word document)
Suggested corrections are labeled:
Fix: Reword -
rephrase to avoid using the keyword
Fix: Make normative
- Capitalize the keyword to make a normative
statement
(Not necessarily
a test assertion)
Fix: Capitalize -
existing normative statement needs correct
capitalization
Other corrections should be self explanatory.
Non-capitalized RFC2119 Keywords
--------------------------------
Section 1 Last paragraph (but prior to "1.1 Terminology")
line 12: "A
mapping from XML to infoset is trivial and should be
used"
Fix:
Reword or ignore
Section 2 last paragraph
line 137:
"some programming languages may have"
Fix: Reword
Section 3.1.1 last bullet
line 290: "A
service element has an optional callback"
Fix
Reword
Section 3.1.2 "reference" element - autowire:boolean(0..1) bullet
&
following
line 338: "the
reference should be autowired"
Fix: Reword
line 347:
""
Fix Make normative or reword
line 355:
"operations required by the reference."
Fix: Reword or make normative
line 360: "a
binding element may specify an endpoint "
Fix: Reword
line 361:
"reference must not mix"
Fix: Make normative
line 365:
"each endpoint must use"
Fix: Make normative
line 368: "A
reference element has an optional"
Fix: Reword
Section 3.1.3 "bullets" (near 3.1.4)
line 413:
"many : boolean (0..1) - (optional)"
Fix: Remove
line 416:
"whether the property value must be supplied"
Fix: Reword
line 417:
"when mustSupply="true" the component must"
Fix: Make normative
line 419:
"value should only be supplied"
Fix: Reword or make normative
Section 4 "component - autowire: boolean(0..1)" bullet
line 632:
"component references should be"
Fix: Reword
Section 4.1
line 653:
"components of this kind may be useful during"
Fix: Reword
line 654:
"characteristics required of the implementation"
Fix: Reword
Section 4.2 last bullet/paragraph
line 752: "A
service element has an optional callback"
Fix: Reword
Section 4.3 "component reference - autowire: boolean(0..1)"
bullet
line 796:
"whether the reference should be autowired"
Fix: Reword
line 848: "the
operations required by the reference."
Fix: Reword
line 872: "A
reference element has an optional"
Fix: Reword
Section 4.3.1 2nd from last bullet (near 4.3.1.1)
line 910:
"attributes and/or child elements must"
Fix: Correct ASM50016 text & update link
line 937: "may
form part of"
Fix: Reword
line 938: "as
a result these may be deployed"
Fix: Reword
Section 4.4
line 1038:
"The property type specified must be compatible"
Fix: Make normative
line 1077:
"many : boolean (0..1) - (optional) "
Fix: Remove
Section 5
line 1217:
"composite name must be unique"
Fix: Correct ASM60001 text & update link
line 1226:
"whether contained component references should be"
Fix: Reword
Section 5.1
line 1296:
"The service name is optional if the target"
Fix: Make normative or reword
line 1302: "a
list of required policy intents."
Fix: Reword
line 1303:
"Specified required intents add to or"
Fix: Reword
line 1304: "further
qualify the required intents"
Fix: Reword
line 1310:
"interface is specified it must be"
Fix: correct ASM60005 text & update link
line 1322: "A
service element has an optional callback "
Fix: Reword
Section 5.2
line 1403:
"the reference name is optional if"
Fix: Make normative
line 1414:
"reference interfaces must be compatible"
Fix: correct ASM60008 text
& update link
line 1419:
"the union of the required"
Fix: Reword
line 1424: "a
list of required policy intents."
Fix Reword
line 1425: "Specified
required intents add to or"
Fix: Reword
line 1426:
"further qualify the required intents"
Fix: Reword
line 1485: "A
reference element has an optional"
Fix: Reword
Section 5.3
line 1550:
"Each property has a type, which may be either"
Fix: Reword
line 1592 :
"may contain an optional default-property-value"
Fix: Reword or make normative
Section 5.3.1
line 1653:
"the element value which is required to be"
Fix: Reword
Section 5.4
line 1757:
"name is optional if the target"
Fix: Reword or make normative
line 1764:
"reference name is optional"
Fix: Reword or make normative
line 1768:
"service name is optional"
Fix: Reword or make normative
line 1779: "by
separate configuration, if required,"
Fix: Remove or reword
line 1788:
"the interface required by the source."
Fix: Reword
line 1809: "an
implementation may only have"
Fix: Reword
line 1810:
"and may not be an instance of the (Java) class"
Fix: Reword
Section 5.5
line 2015:
"Composites may form component implementations"
Fix: Reword
line 2024: "a
component implementation must also honor"
Fix: make normative or reword
line 2054: "a
list of required policy intents."
Fix: Reword
line 2055: "Specified
required intents add to or"
Fix: Reword
line 2056:
"further qualify the required intents"
Fix: Reword
Section 5.6
line 2109:
"composites may be developed"
Fix: Reword
line 2111: "A
composite may include another composite"
Fix: Reword
line 2129:
"the included composite, must follow"
Fix: make normative
line 2130:
"the composite element must define"
Fix: Make normative
line 2133:
"must have the same value"
Fix: Make normative
line 2134:
"but its document root element must"
Fix: Make normative
line 2135:
"The composite element may contain"
Fix: Make normative
line 2138:
"included composite file may be referenced"
Fix: Reword
line 2158:
"name (required) "
Fix: Replace with cardinality notation
Section 5.7
line 2265:
"For example, a Composite may include"
Fix : Reword
Section 5.8
line 2271: "A
component in a composite may be used"
Fix: Reword
line 2273:
"URI may be used to separately identify"
Fix: Reword
line 2274:
"may be used to attach"
Fix: Reword
Section 6
line 2308:
"including the required form"
Fix: Reword
line 2361:
"additional optional references"
Fix: Correct ASM70005 text & update link
line 2362:
"additional optional properties"
Fix: Correct ASM70005 text & update link
line 2363:
"additional non-optional references"
Fix: non-optional allowed?
line 2364:
"additional non-optional properties"
Fix: non-optional allowed?
Section 6.1 paragraph following schema
line 2405:
"means that it must provide:"
Fix: Reword
Section 7.1
line 2443: "A
remoteable service is one which may be called"
Fix: Reword
Section 7.2
line 2493:
"optional callback interface."
Fix: Make normative or reword
line 2495:
"Java interfaces with an optional"
Fix: Reword
Section 7.3.1
line 2546:
"WSDL request-response pattern may be "
Fix: Reword
line 2549:
"the business process logic may be a long-running"
Fix: Reword
line 2551: "or
the process may perform"
Fix: Reword
Section 7.3.4
line 2580:
"required to support services"
Fix: Reword
Section 7.4
line 2609:
"marked with required intents MUST"
Fix: Correct ASM80008 text & update link
Section 7.5
line 2644: "an
optional callback interface"
Fix: Reword or make normative
Section 8 "name(0..1)" bullet
line 2736:
"others must have a name value"
Fix: Correct ASM90002 text & update link
line 2754:
"and it may include additional"
Fix: Reword
Section 8.1
line: 2771:
"information may be contained in SOAP headers"
Fix: Reword
Section 8.2
line 2779: "or
it may be general"
Fix: Reword
line 2783: "an
optional <sca:wireFormat/> subelement"
Fix: Reword or make normative
Section 8.3
line 2803: "to
contain the required mapping information."
Fix: Reword
Section 8.4
line 2820:
"have an optional @URI attribute"
Fix: Reword or make normative
Section 8.4.1
line 2830:
"may optionally make"
Fix: Reword or make normative
Section 8.4.2
line 2841:
"which may include the policy sets"
Fix: Reword
line 2856: "a
binding type may completely change"
Fix: Reword
line 2857: "is
required by an HTTP"
Fix: Reword
Section 8.5 first full paragraph
line 2867:
"the required qualities of service must be implemented"
Fix: Reword or make normative
line 2869:
"Web service binding should be used."
Fix: Reword or capitalize
line 2872: "the
SCA binding should be one of them."
Fix: Reword
line 2874:
"the intents required by the reference"
Fix: Reword
Section 9
line 2944:
"targetNamespace (required)"
Fix: Replace with cardinality notation
line 2946:
"The definitions element contains optional child
elements"
Fix: Reword or make normative
Section 10
line 2959:
"but other types can be defined as required,"
Fix: Reword
Section 10.2
line 3109:
"which the implementation type may provide."
Fix: Reword
Section 10.3
line 3189:
"which the binding type may provide."
Fix: Reword
Section 11.1, 2nd paragraph
line 3362:
"services outside the domain must use binding specific
mechanisms"
Fix: Reword
line 3365:
"deployed using SCA should not be able"
Fix: Reword
line 3369:
"SCA Domain may be the whole"
Fix: Reword
line 3370: "or
it may be a department"
Fix: Reword
Section 11.2
line 3387: "but
which may be needed by an SCA"
Fix: Reword
line 3391:
"Non-XML artifacts are also required within an SCA
domain."
Fix: Reword
line 3393:
"non-XML artifacts may also be required."
Fix: Reword
line 3398:
"SCA runtime may convert the ZIP"
Fix: Reword
line 3409:
"which may be used by other contributions"
Fix: Reword
line 3412:
"These optional elements may"
Fix: Reword
line 3413:
"but may be generated"
Fix: Reword
line 3414: "or
they may not exist "
Fix: Reword
line 3429:
"internal JAR file should be represented"
Fix: Reword
line 3430:
"all of the contents should be represented"
Fix: Reword
line 3431: "a
contribution should not need to "
Fix: Reword
Section 11.2.1 4th paragraph (not including bullets)
line 3455:
"using a WSDL which must be"
Fix: Reword
Section 11.2.2 1st paragraph of "Export Element - namespace (1..1) bullet
&
following
line 3563:
"should be the namespace URI"
Fix: Make normative
line 3568:
"QNames must use a different export"
Fix: Reword or make normative
line 3586:
"QNames must use a different import"
Fix: Reword or make normative
line 3616:
"dependent contributions should be specified only"
Fix: Reword
Section 11.2.3
line 3623: "an
optional "META-INF/sca-contribution-"
Fix: Reword
Section 11.3
line 3647:
"are optional, as composites"
Fix: Reword
Section 11.4
line 3664:
"The functionality is optional meaning"
Fix: Make normative
& add to ASM12008
Section 11.4.1 1st paragraph
line 3670:
"contributions that should be used to resolve"
Fix: Reword
Section 11.4.2 1st paragraph
line 3693:
"must run within the context"
Fix: Reword
Section 11.6
line 3740:
"although a runtime may supply equivalent"
Fix: Reword
Section 11.6.1 last paragraph
line 3743: "The
supplied composite URI must refer"
Fix: Make normative
Section 11.6.3
line 3760:
"any referenced artifacts must be resolved"
Fix: Reword
Section 11.6.4 1st paragraph
line 3763:
"Composite), it must be possible to get the definitions"
Fix: Reword
line 3769:
"should exist in some form"
Fix: Reword
Section 11.7
line 3777:
"(ie this may change the component"
Fix: Reword
line 3787:
"which may include changing the wires"
Fix: Change ASM120015 text & update link
Appendix B.1 1st paragraph
line 4675:
""
Fix: Reword or make normative
Appendix B.2
line 4685:
"vendors may choose to support"
Fix: Reword
line 4685: "A
single SCA implementation may"
Fix: Reword or make normative
Appendix B.3
line 4701:
"are the operations required by the service"
Fix: Reword
line 4701: "An
implementation may contain"
Fix: Reword
line 4703: "A
service may be provided as"
Fix: Reword
Appendix B.3.2
line 4719:
"Local services may rely on"
Fix: Reword
line 4719: "or
may assume a very fine-grained"
Fix: Reword
line 4720:
"They may also use technology-specific"
Fix: Reword
Appendix B.4
line 4730: "an
implementation may call"
Fix: Reword
Appendix B.6 last paragraph
line 4757:
"Interfaces may be bi-directional."
Fix: Make normative or reword
line 4757;
"service operations which must be provided"
Fix: Reword
Appendix B.7
line 4767: "It
may be used as a component implementation."
Fix: Reword
line 4768:
"Components may not be directly referenced"
Fix: Reword
Appendix B.9
line 4784:
"Properties may be defined directly"
Fix: Reword
Appendix C
ASM50016:
"and/or child elements must be used."
Fix: Capitalize
ASM60001: "A
composite name must be unique"
Fix: Capitalize
ASM60005:
"interface is specified it must be"
Fix: Capitalize
ASM60008:
"component reference interfaces must be"
Fix: Capitalize
ASM70005:
"additional optional references"
Fix: Capitalize
ASM70005:
"additional optional properties"
Fix: Capitalize
ASM80008:
"interface marked with required intents"
Fix: Capitalize
ASM90002: "all
others must have a name value"
Fix: Capitalize
ASM12015:
"which may include changing the wires"
Fix: Capitalize
[attachment "SCA-Asy V1.1 CD02 Rev3 RFC2119.doc" deleted by Mike
Edwards/UK/IBM]
---------------------------------------------------------------------
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