[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [sca-assembly] NEW ISSUE: Incorrect usage of MAY Keyword
On today's Assembly call I volunteered to produce a reworded paragraph for the first of Eric's items. See inline below. Simon Eric Wells wrote: > All, > I think that in several places in the specification the usage of the > keyword MAY is not consistent with the definition in RFC2119. To quote > http://www.ietf.org/rfc/rfc2119.txt: > > 5. MAY This word, or the adjective "OPTIONAL", means that an item is > truly optional. One vendor may choose to include the item because a > particular marketplace requires it or because the vendor feels that > it enhances the product while another vendor may omit the same item. > > In several places MAY is used to indicate the semantics of an artifact and > NOT that a behavior is optional. I believe other usage of MAY (and SHOULD) > are consistent with the RFC2119 definition. > > Note I DO NOT want to delay the CD03 vote, so it may be more appropriate to > handle these issues on the public comment list. However I will defer to > others as to how best to handle these items. > > 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 the CD03 Word document at: > > > http://www.oasis-open.org/committees/download.php/31566/sca-assembly-1.1-spe > c-cd03.doc > > I think that the following normative statements need corrections: > > Unmarked normative statement Lines 836 - 840 > ============================================ > "If the component reference has @nonOverridable==false and @multiplicity > 1..1 and the reference has a target, then any composite reference which > promotes the component reference has @multiplicity 0..1.by default and MAY > have an explicit @multiplicity of either 0..1 or 1..1." > > Although this is not marked as a normative statement, I think the use of the > MAY keyword is probably correct and either value for @multiplicity is > arbitrarily allowed. > > PROPOSAL: > Add a normative reference for the statement. N.B. If a vendor should NOT be > allowed to arbitrarily choose the value for @multiplicity the statement > should be reworded. (Note there is an extra period in "0..1.by" that should > be corrected editorially regardless of this issue). > Here is my proposed rewording of this paragraph. I have added inline notes as <scn>...</scn> to explain the changes, with a few additional comments. nonOverridable : boolean (0..1) - a boolean value, "false" by default, which indicates whether this component reference can have its targets overridden by a composite reference which promotes the component reference. If @nonOverridable==false, the target(s) of the promoting composite reference replace all the targets explicitly declared on the component reference for any value of @multiplicity on the component reference. If the component reference has @nonOverridable==false and @multiplicity 1..1 and the reference has a target, then any composite reference which promotes the component reference has @multiplicity 0..1 by default and can have an explicit @multiplicity of either 0..1 or 1..1. <scn> Changed "MAY" to "can" because the normative text covering this will be added to ASM60011 (see below). </scn> <scn>I find it surprising that there is no similar special case for a component reference with multiplicity 1..n and one or more targets. Is this deliberate? <scn> If @nonOverridable==true, and the component reference has @multiplicity 0..1 or 1..1 and the reference has a target, promotion implies that the <scn>Changed "also declares a target" to "has a target" for consistency with the previous wording four lines earlier. The difference could be significant if the target is provided by autowiring. </scn> promoting composite reference has @wiredbyImpl==true and the composite reference cannot supply a target, but can influence the policy attached to the component reference. If @nonOverridable==true, and the component reference @multiplicity is 0..n or 1..n, promotion targeting is additive. In addition to this change, a change needs to be made to the description of @multiplicity for composite references because the current wording does not cover this case. Here's my proposed update: multiplicity : (0..1) - Defines the number of wires that can connect the reference to target services. When present, the multiplicity can have one of the following values: o 0..1 – zero or one wire can have the reference as a source o 1..1 – one wire can have the reference as a source o 0..n - zero or more wires can have the reference as a source o 1..n – one or more wires can have the reference as a source The default value for the @multiplicity attribute is 1..1, except where the promoted component reference has @nonOverridable==false and @multiplicity 0..1 or 1..1 and the reference has a target, in which case the default value for @multiplicity is 0..1. <scn>I find it surprising that the default is 1..1 rather than the multiplicity setting of the promoted component reference. Assuming this was a deliberate choice and not a cut-and-paste error, this additional special case of a 0..1 default needs to be added. </scn> The value specified for the @multiplicity attribute of a composite reference MUST be compatible with the multiplicity specified on each of the promoted component references, i.e., the multiplicity has to be equal or further restrict. So multiplicity 0..1 can be used where the promoted component reference has multiplicity 0..n, multiplicity 1..1 can be used where the promoted component reference has multiplicity 0..1, 0..n, or 1..n, and multiplicity 1..n <scn>I have added 0..1 to the above list, assuming that its omission was accidental rather than deliberate. </scn> can be used where the promoted component reference has multiplicity 0..n. However, a composite reference of multiplicity 0..n or 1..n cannot be used to promote a component reference of multiplicity 0..1 or 1..1 respectively. In addition, if the promoted component reference has @nonOverridable==false and @multiplicity 1..1 and the reference has a target, then the composite reference can have multiplicity 0..1. [ASM60011] <scn>Added additional possibility that is an exception to the normal rule that promoted references can only restrict multiplicity. </scn> Simon > > > ASM50016 Lines 910 - 914 > ======================== > "It is possible that a particular binding type MAY require that the address > of a target service uses more than a simple URI. In cases where a reference > element has a binding sub element of such a type, the @uri attribute of the > binding element MUST NOT be used to identify the target service - instead, > binding specific attributes and/or child elements MUST be used. [ASM50016]" > > I believe the intent is to say some bindings DO IN FACT require more than a > simple URI - it isn't (in general) optional for that particular binding > type. > > Also, the phrase "MAY require" semi-confuses two RFC2119 keywords. This may > be a little pedantic as I think it is clear what is being stated. However, > it would clarify matters to reword the statement. > > PROPOSAL: > I suggest making the first sentence of ASM50016 non-normative with (e.g.) > the following wording: > > "It is possible that a particular binding type will use 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]" > > We should probably also say what constitutes a "simple URI". (I think this > is covered in section 8, Bindings, but there is no context for this > statement). > > It may also be more appropriate to place this requirement in section 8 - > Bindings. > > > > ASM50018 Line 921 > ================= > "A reference with multiplicity 0..1 or 0..n MAY have no target service > defined. [ASM50018]" > > Again, this statement is not really specifying optional behavior - it is > making a statement about the semantics of the @multiplicity attribute. I.E. > If there are no target services defined the "actual configured multiplicity" > is zero (which is consistent with 0..1 and 0..n). > > PROPOSAL: > I suggest making [ASM50018] non-normative to "remind" readers that for 0..1, > 0..n it is possible that no target services are configured. > > > > ASM50021 Lines 926 - 927 > ======================== > "A reference with multiplicity 0..n or 1..n MAY have one or more target > services defined. [ASM50021]" > > The same considerations as for ASM50018, above, apply. > > PROPOSAL: > I suggest making [ASM50021] non-normative. > > > > ASM70005 Lines 2369 - 2373 > ========================== > "An implementation MAY contain 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, but MUST > NOT contain additional references with @multiplicity=1..1 or > @multiplicity=1..n or additional properties with @mustSupply=true > [ASM70005]" > > I think this is the same situation as ASM50021. If so the first sentence > needs to be non-normative. > > PROPOSAL: > Reword ASM70005 as follows: > > "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]" > > > > ASM90004 Lines 2786 - 2787 > ========================== > "To do so, a wire target MAY be specified with a syntax of > "componentName/serviceName/bindingName". [ASM90004]" > > This usage could be correct, but NOT if we are saying that this syntax MUST > be used to wire to a specific binding. Again, is this an optional feature > that vendors can choose to implement or not? > > PROPOSAL: > If this syntax is obligatory to wire to a specific service we should change > the wording to: > > "To wire to a specific binding of a component service the syntax > "componentName/serviceName/bindingName" MUST be used. > > > > Unmarked normative statement Lines 3434 - 3436 > ============================================== > "n the sca-contribution.xml file, additional elements MAY exist that list > the namespaces of constructs that are needed by the contribution and which > are be found elsewhere, for example in other contributions." > > This appears to be a bad edit. > > PROPOSAL: > Remove lines 3434 - 3436 or correct text and mark the statement as > normative. > > > > ASM12013 Lines 3750 - 3761 > ========================== > "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 MAY disallow 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 MAY evaluate 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 MAY re-evaluate 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 new configuration of the reference takes > place is > described by the relevant client and implementation specifications. > > I do not think we should mix the mandatory MUST in the first sentence with > the optional MAY in the numbered clauses. (This would allow a vendor to > choose say, option 1, and then, because it is optional, choosing not to > disallow deployment. > > PROPOSAL: > I suggest the following wording: > > "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 does not update those targets when later > deployment actions > occur. > 3) The SCA runtime evaluates the target(s) for the reference dynamically > for each > deployment action, resulting in updated reference targets which match > the new > Domain configuration. How the new configuration of the reference takes > place is > described by the relevant client and implementation specifications." > > > > > > > > > > > > > > > > > > > --------------------------------------------------------------------- > 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]