[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: 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
SCA-Asy V1.1 CD02 Rev3 RFC2119.doc
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]