RE: [sca-assembly] [ASSEMBLY 122] Incorrect Usage of MAY Keyword - Revised Proposal, Part 1

All,

      I haven't received any 
further comments regarding ASSEMBLY-1222 so a revised document, as per Tuesdays 
telecon, is attached. 

 

Some 
comments regarding the items discussed are 
inline below.

 

Best 
Regards,

                       
Eric.

Eric Wells.
Consulting Engineer.
Hitachi Computer Products 
(America) Inc.
San Francisco, CA. USA.
+1 (415) 656-4346


From: David Booz [mailto:] 

Sent: Tuesday, May 05, 2009 6:37 AM
To: 

Subject: Re: [sca-assembly] 
[ASSEMBLY 122] Incorrect Usage of MAY Keyword - Revised Proposal, Part 
1

Eric, Thanks for pulling this together. I have some comments, using your 
numbering scheme as a reference.

3) Section 4.3.1.1, Lines 893 - 901 
[ASM50018] thru [ASM50021]
- Why did you create new labels instead of 
re-wording the existing labelled statements?
- ASM50042 - I don't understand 
why we need this new statement, can you explain further why you think we need 
it? 

I wanted 
to capture the idea that target services should be "invokeable". 
Deleted [ASM50042] as 
agreed during the discussion.

4) Section 6, lines 2326 
- 2330 [ASM70005]
- The new normative statement doesn't stand alone very 
well. I think it needs to retain the constrainingType context of the original 
statement. How about "An implementation that is constrained by a 
constrainingType MUST NOT..." 

Changed 
as per Daves' suggestion above. 

7) Correct 
Usage
- Why are 3761-3774 flagged with edits/change marks? 

I don't 
know! These change marks are in the CD03 document as downloaded from OASIS. I 
have not made any changes in this section. (There are several changes attributed to Anish - they could 
be Word artifacts?)

Lines 3537 - 3539 
[ASM12030]
- I'm wondering why this isn't a MUST. Any other opinions? I 
realize changing it to MUST would be done as a new issue. 

I'm not 
sure, but either usage seems consistant with the RFC2119 keyword 
definitions. 

Dave Booz
STSM, BPM and SCA 
Architecture
Co-Chair OASIS SCA-Policy TC and SCA-J TC
"Distributed 
objects first, then world hunger"
Poughkeepsie, NY (845)-435-6093 or 
8-295-6093
e-mail:

"Eric 
Wells" ---05/03/2009 09:49:22 PM---All, I took an AI to make ASSEMBLY-122 more 
manageable and here is a revised

  
  

    
From:
    
"Eric Wells" 
      <>

  

    
To:
    
"OASIS SCA Assembly List" 
      <>

  

    
Date:
    
05/03/2009 09:49 PM

  

    
Subject:
    
[sca-assembly] [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


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

(See attached file: 
sca-assembly-1.1-cd03+ASSEMBLY122.doc)---------------------------------------------------------------------
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 

sca-assembly-1.1-cd03+ASSEMBLY122rev02.doc