opencsa-liaison message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: RE: [opencsa-liaison] Use of "may", "must", etc.
- From: Mike Edwards <mike_edwards@uk.ibm.com>
- To: opencsa-liaison@lists.oasis-open.org
- Date: Wed, 5 Dec 2007 09:18:21 +0000
Folks,
OK, I'll bite on the challenge set by
Bryan for these two cases, in the full and certain knowledge that showing
a solution for
just these two will not address the
wider sea of cases spread across all the SCA specifications.
1)
I'd take this as being normative in
the first instance. It is stating something testable - that a C++
service interface has an optional
annotation, that, when present, indicates
that the contract defined by the interface is conversational. The
target for the normative
statement is the interface document
itself:
"Service interfaces MAY be annotated
to specify whether their contract is conversational, as described in the
Assembly Specification [ASSEMBLY],
using the @Conversational annotation."
...if you don't want the statement to be normative, then
I would cast it as follows:
"A @Conversational annotation is optionally applied
to a C++ Service interface to indicate that the service contract is conversational,
as
described in the SCA Assembly specification [ASSEMBLY]."
2)
I'm assuming that there is nothing normative
here.
"The data exchange semantics for
calls to local services is by-reference. This means that code
needs to be written with the knowledge that changes
made to parameters (other than simple
types) by either the client or the provider of the service can be
seen by the other."
I think it is perfectly possible to
write meaningful text without using RFC 2119 terms. Whether we want
to spend the time doing this wordsmithing across
the specs is the issue.
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: mike_edwards@uk.ibm.com
Bryan Aupperle <aupperle@us.ibm.com>
04/12/2007 20:41
|
To
| opencsa-liaison@lists.oasis-open.org
|
cc
|
|
Subject
| RE: [opencsa-liaison] Use of "may",
"must", etc. |
|
A couple of examples we have come across so far:
Service interfaces may be annotated to specify whether their contract is
conversational, as described in the Assembly Specification [ASSEMBLY] using
the @Conversational annotation.
Note for C++, annotations are currently anticipated to be processed by
tools so annotated source, in and of itself, does not force any behavior
on anything other than a annotation processor. The conversational
intent in the SCDL is what is meaningful. Thus use of "MAY"
is not appropriate here. Replacing "may" with "can"
is not grammatically correct.
The data exchange semantics for calls to local services is by-reference.
This means that code must be written with the knowledge that changes
made to parameters (other than simple types) by either the client or the
provider of the service can be seen by the other.
This is not really a compliance point (I would not expect a test for it)
but clearly guidance to someone reading the specification intending to
implement components. Removal or "must" is awkward and
other options are wordier.
Bryan Aupperle, Ph.D.
STSM, WebSphere Enterprise Platform Software Solution Architect
Master Inventor
Research Triangle Park, NC
+1 919-254-7508 (T/L 444-7508)
Internet Address: aupperle@us.ibm.com
"Patil, Sanjay"
<sanjay.patil@sap.com>
12/04/2007 10:34 AM
|
To
| <ashok.malhotra@oracle.com>,
Bryan Aupperle/Raleigh/IBM@IBMUS
|
cc
| <opencsa-liaison@lists.oasis-open.org>
|
Subject
| RE: [opencsa-liaison] Use of "may",
"must", etc. |
|
If we did that (that is treat the terms in lower-case differently from
their upper-case version), then our specs can not claim full compliance
with RFC 2119, since RFC 2119 does not differentiate the key words based
on their case. The problem with invoking RFC 2119 only for upper-case
keywords would be that - we might be upsetting a lot of readers out
there who have by now started expecting a full compliance with RFC 2119.
Bryan, could you give us one or two examples of the awkwardness you
faced while substituting the RFC terms? Perhaps we can just identify the
common situations of such awkwardness and try to come up with some
alternative terms that can be uniformly used by all the SCA specs.
-- Sanjay
> -----Original Message-----
> From: ashok malhotra [mailto:ashok.malhotra@oracle.com]
> Sent: Tuesday, Dec 04, 2007 6:32 AM
> To: Bryan Aupperle
> Cc: opencsa-liaison@lists.oasis-open.org
> Subject: Re: [opencsa-liaison] Use of "may", "must",
etc.
>
> Hi Bryan:
> I agree that this is a problem. My alternate proposal is that
the
> upper-case words indicate the RFC 2119 keywords and the
> lower-case words
> indicate normal English usage. But not everyone likes this solution.
>
> Bryan Aupperle wrote:
>
> >
> > I believe all of the TCs have adopted use of RFC 2119 keywords
in
> > uppercase only and to not use the keywords in lower-case
> form at all,
> > using synonyms when necessary. We have started scrubbing
> the C++ spec
> > to eliminate use of "may", "must", etc. and
found that some rather
> > awkward language can result Has anyone else started this
exercise
> > and how are your results?
> >
> > Bryan Aupperle, Ph.D.
> > STSM, WebSphere Enterprise Platform Software Solution Architect
> > Master Inventor
> >
> > Research Triangle Park, NC
> > +1 919-254-7508 (T/L 444-7508)
> > Internet Address: aupperle@us.ibm.com
>
>
>
> --
> All the best, Ashok
>
> ---------------------------------------------------------------------
> To unsubscribe from this mail list, you must leave the OASIS TC that
> generates this mail. You may a link to this group and all
> your TCs in OASIS
> at:
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgr
> oups.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
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]