[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: [ASSEMBLY 122] Incorrect Usage of MAY Keyword - Revised Proposal, Part 1
All, I took an AI to make ASSEMBLY-122 more manageable and here is a revised proposal. I tried to separate the items, but they all involve the usage of MAY to indicate semantics, which is in contradiction to the RFC2119 definition. (See the original E-mail at http://www.oasis-open.org/apps/org/workgroup/sca-assembly/email/archives/200 903/msg00094.html) Anish identified three uses of the MAY keyword: (See: http://www.oasis-open.org/apps/org/workgroup/sca-assembly/email/archives/200 903/msg00105.html) 1) MAY used to indicate schema element cardinality 2) MAY used to indicate artifact semantics 3) MAY used to indicate optional support in SCA Runtimes Only usage (3) is consistent with the RFC2119 definition. I found no instances of usage (1), at least in the PRD document. All the items below are usage (2). We should not be using MAY in these circumstances as they are NOT optionally supported items. (Note that the test cases for all of the MAY items below are mandatory, which again indicates the items are not optional). There is a summary of changes below and a marked-up word document is attached. Best Regards, Eric. Eric Wells. Consulting Engineer. Hitachi Computer Products (America) Inc. San Francisco, CA. USA. +1 (415) 656-4346 eric.wells@hitachisoftware.com PROPOSAL: ========= We should ONLY use MAY (SHOULD, etc) in the strict sense defined by RFC2119. That is for items that a vendor can arbitrarily chose to support or implement. In other circumstances, such as defining semantics, the normative statements should be reworded to use ONLY the mandatory keywords (MUST, REQUIRED, etc). Obviously if a statement is non-normative it should not use any RFC2119 keywords. Following this principle the following changes should be made: Based on PRD: http://docs.oasis-open.org/opencsa/sca-assembly/sca-assembly-1.1-spec-cd03.d oc (Line numbers refer to the attached marked up document) 1) Section 4.3 Reference, Lines 805 - 813 ----------------------------------------- Now addressed by http://www.osoa.org/jira/browse/ASSEMBLY-134. Paragraph has been made non-normative in the attached document. 2) Section 4.3.1, Lines 882 - 886 [ASM50016] -------------------------------------------- In the second from last bullet the phrase "MAY require" confuses two RFC2119 keywords. I believe the intent is to say some bindings DO IN FACT require more than a simple URI and it isn't optional for that particular binding type. Reword as follows (make first sentence non-normative): It is possible that a particular binding type uses more than a simple URI for the address of a target service. In cases where a reference element has a binding sub element that uses more than a simple URI, the @uri attribute of the binding element MUST NOT be used to identify the target service - in this case binding specific attributes and/or child elements MUST be used. [ASM50016] 3) Section 4.3.1.1, Lines 893 - 901 [ASM50018] thru [ASM50021] -------------------------------------------------------------- The rules constraining the number of target services use MAY incorrectly to indicate @multiplicity semantics. Reword as follows: . A reference with multiplicity 0..1 MUST have no more than one target service defined. [ASM50039] . A reference with multiplicity 1..1 MUST have exactly one target service defined. [ASM50040] . A reference with multiplicity 1..n MUST have at least one target service defined. [ASM50041] . A reference with multiplicity 0..n can have any number of target services defined. The reference MUST be wired to all of the defined target services and able to invoke operations on each target service. [ASM50042] The new normative statement [ASM50042] needs further checking against the rules for deployment of unwired composites. ([ASM60021] on lines 1778 - 1780) I think this is OK as there would not be targets for these unwired composites? 4) Section 6, lines 2326 - 2330 [ASM70005] ------------------------------------------------------------ Normative statement [ASM70005] uses MAY incorrectly to indicate possible implementation artifacts. Make the first part non-normative and reword as: It is possible that an implementation contains additional services, additional references with @multiplicity=0..1 or @multiplicity=0..n and additional properties with @mustSupply=false beyond those declared in the constraining type. However, an implementation MUST NOT contain additional references with @multiplicity=1..1 or @multiplicity=1..n or additional properties with @mustSupply=true [ASM70005] 5) Section 8, lines 2740 - 2741 [ASM90004] ------------------------------------------ I believe the intent of [ASM90004] is to say the following: To wire to a specific binding of a target service the syntax "componentName/serviceName/bindingName" MUST be used. [ASM90004] 6) Section 11.6, lines 3697 - 3708 [ASM12013] --------------------------------------------- The MAY keyword is redundant in the list of mandatory (MUST) choices. Reword as: For components at the Domain level, with References for which @autowire="true" applies, the behavior of the SCA runtime for a given Domain MUST take ONE of the 3 following forms: 1) The SCA runtime disallows deployment of any components with autowire References. In this case, the SCA runtime MUST raise an exception at the point where the component is deployed. 2) The SCA runtime evaluates the target(s) for the reference at the time that the component is deployed and not update those targets when later deployment actions occur. 3) The SCA runtime re-evaluates the target(s) for the reference dynamically as later deployment actions occur resulting in updated reference targets which match the new Domain configuration. How the reconfiguration of the reference takes place is described by the relevant client and implementation specifications. [ASM12013] 7) Correct Usage ---------------- I think the following instances of the optional RFC2119 keywords are correct: Lines 1778 - 1780 [ASM60021] Lines 3377 - 3378 [ASM12002] Lines 3379 - 3381 [ASM12003] Lines 3524 - 3526 [ASM12029] Lines 3537 - 3539 [ASM12030] Lines 3624 - 3625 [ASM12007] Lines 3634 - 3636 [ASM12008] Lines 3752 - 3754 [ASM12014] Lines 3757 - 3760 [ASM12016] Lines 3761 - 3767 [ASM12017] Lines 3768 - 3769 [ASM12018] Lines 3800 - 3801 [ASM14001] Lines 3801 - 3803 [ASM14002] Lines 3824 - 3825 [ASM14004] Lines 3863 - 3866 SCA Interoperable Packaging Document
sca-assembly-1.1-cd03+ASSEMBLY122.doc
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]