Re: [sca-assembly] NEW ISSUE: Incorrect usage of MAY Keyword

Folks,

Logged as    http://www.osoa.org/jira/browse/ASSEMBLY-122

Yours,  Mike.

Strategist - Emerging Technologies, SCA & SDO.

Co Chair OASIS SCA Assembly TC.

IBM Hursley Park, Mail Point 146, Winchester, SO21 2JN, Great Britain.

Phone & FAX: +44-1962-818014    Mobile: +44-7802-467431  

Email:  

From:
"Eric Wells" <>

To:
"OASIS SCA Assembly List"
<>

Date:
07/03/2009 13:31

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



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

Unless stated otherwise above:

IBM United Kingdom Limited - Registered in England and Wales with number
741598. 

Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6
3AU