[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
Yes! We say that the XML docs MUST conform to the Schema. The remaining MAYs and MUSTs MUST be about constraints/requirements that cannot be checked by the Schema. All the best, Ashok Anish Karmarkar wrote: > Martin Chapman wrote: >> Actually for the 1) I think we should strip out all those MUST and >> MAY that just repeat what is in the schema. The fact that >> something in schema says 0..1 doesn't require us to say anything >> normatively in the text aside from complying with the schema IMHO. >> > > +1 > -Anish > -- > >>> -----Original Message----- >>> From: Anish Karmarkar [mailto:Anish.Karmarkar@oracle.com] >>> Sent: 10 March 2009 23:20 >>> To: Simon Nash >>> Cc: 'OASIS SCA Assembly List' >>> Subject: Re: [sca-assembly] NEW ISSUE: Incorrect usage of MAY Keyword >>> >>> Simon Nash wrote: >>>> Martin Chapman wrote: >>>>> Eric, >>>>> >>>>> I don't see our usage as inconsistent, and is used this way in a >>>>> number if OASIS (and non-OASIS specs). >>>>> IETF predominantly defines protocols and as a vendor of a protocol >>>>> optionality of support and optionality of semantics pretty much >>>>> equate to the same thing IMHO. I think your other issue about what we >>>>> say in the conformance regarding optional items is much more >>>>> relevant. >>>>> >>>> I think there is a problem here. I went through all the conformance >>>> statements that use MAY, and a number of them don't fall into the >>>> category of things for which it would be permissible for vendors >>>> to omit support. >>>> >>>> Examples of this include ASM50018, ASM50021 and ASM90004. >>>> >>> I agree that MAY here does not mean that it is optional for the *SCA >>> Runtime*. >>> >>> I think there are three cases here: >>> 1) MAYs that indicate an optionality wrt document instances. Eg. an >>> element that has cardinality of 0..1. >>> 2) MAYs that talk about semantics (as Eric noted). I don't think we >>> should be using a MAY for this. >>> 3) MAYs that indicate an optionality wrt support by conformant SCA >>> Runtimes. >>> >>> For (1) and (3) as long as we use the right target we should be OK. >>> ASM50018, ASM50021, and ASM90004 talk about the reference/wire targets. >>> These are specific document elements/attribute. Therefore, I think they >>> are correctly worded. It is optional for a document instance to use a >>> specific wire target syntax or specify a target for references with >>> cardinality 0..1, 0..n etc. >>> >>> If we want to clearly distinguish case (1) and (3) above, we should >>> either provide some additional markup that clearly identifies the >>> target >>> or in appendix C add a new column called 'target' (Martin had put >>> forward this idea some time back), or both. For example, WS-I profiles >>> requirements contain targets in all CAPS. They also define the targets >>> right at the beginning of the profiles. >>> >>> -Anish >>> -- >>>> Simon >>>> >>>>> Martin. >>>>> >>>>>> -----Original Message----- >>>>>> From: Eric Wells [mailto:eric.wells@hitachisoftware.com] >>>>>> Sent: 07 March 2009 13:31 >>>>>> To: OASIS SCA Assembly List >>>>>> Subject: [sca-assembly] NEW ISSUE: Incorrect usage of MAY Keyword >>>>>> >>>>>> 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). >>>>>> >>>>>> >>>>>> >>>>>> 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 >>>>>> >>>>> >>>>> >>>>> --------------------------------------------------------------------- >>>>> 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 >>>>> >>>>> >>>>> >>>> >>>> >>>> --------------------------------------------------------------------- >>>> 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 >>> --------------------------------------------------------------------- >>> 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 >> >> > > --------------------------------------------------------------------- > 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]