[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [sca-assembly] [ASSEMBLY 122] Incorrect Usage of MAY Keyword- Revised Proposal, Part 1
Eric, Thanks for these proposals. See comments inline. Simon Eric Wells wrote: > 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. > Actually, ASSEMBLY-134 addresses a separate but related point. When ASSEMBLY-134 is resolved, I was intending to produce a proposal for the other changes that are needed to this paragraph and section 5.2. I was expecting to include these other changes as part of this issue, but we could expand ASSEMBLY-134 to cover them or I could raise a separate issue for this. > > 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] > This change looks good to me. > > 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. > These changes look good to me. > 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? > I don't understand why this new statement is needed. It doesn't have a clear conformance target and the first part appears to be a tautology (specifying target services is one form of wiring). The second part seems strange as well, as it is not the reference that invokes services. If such a statement is needed, it should not appear in section 4.3.1.1, which is about multiplicity. A more general form of this would be to say that the SCA runtime MUST permit a reference to be used to invoke operations on all target services of the references. If we need to say this (and I am not sure that we do), section 5.4 seems a more suitable place. > > 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] > I'm not sure that there is a problem with the original wording. It is defining something optional that a component implementation is allowed to either do or not do. I also think the revised wording is OK. > > 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] > This statement is in the wrong place. It should appear in section 5.4 as a valid alternative to the <component-name>/<service-name> syntax. If the componentName/serviceName/bindingName syntax is defined in section 5.4, it would be helpful to also mention it here using a non-normative statement. > > 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. > Change "and not" to "and does not" in above sentence. > 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] > Looks OK, with the small wording change suggested above. Simon > > 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 > > > > ------------------------------------------------------------------------ > > --------------------------------------------------------------------- > 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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]