Re: Proposal for clarifying relationship between SOAP modules and features

[I apologize in advance for the length of this message. It 
started small and ended much longer that I had anticipated.]

-----------

Having just been made aware of issue 219[1], it's resolution[2] 
and pushback[3], here's a variation of my earlier proposal:

<alternativeAmendment
     section="3.2, 1st paragraph"
     section="Glossary">
A SOAP Module *describes* the syntax and semantics of one or more 
SOAP header blocks *used to implement* one or more SOAP features.
<theFollowingNotInGlossary/>
A module specification adheres to the following rules. It:
</alternativeAmendment>

-----------

Also, [3] requested clean-ups to bullet 2, section 3.2. The 
current text says:

<current section="3.2, 2nd bullet">
MUST, if the Module implements a Feature which has already been 
defined elsewhere, clearly refer to that Feature's URI. Note that 
a Module may EITHER explicitly refer to a separate Feature in 
this way OR may implicitly define a Feature simply by describing 
the semantics of the Module.
</current>

I suggest changing it to:

<proposed section="3.2, 2nd bullet">
MUST, if the module implements a feature which has already been 
defined elsewhere, clearly *reference that feature using the 
feature's URI*. Note that a module may EITHER explicitly 
*reference an existing* feature in this way OR may implicitly 
define a *new* feature simply by describing the *module's semantics*.
</proposed>

----------

Finally, and whilst I am at it, I've always found the 1st 
paragraph of 3.1 to be a sort of a hodge-podge and to create more 
confusion than is necessary. For example, "an extension typically 
associated with the exchange of messages" implies, wrongly, MEP. 
The current text says:

<current section="3.1">
For the purpose of this specification, the term "feature" is used 
to identify an extension of the SOAP messaging framework 
typically associated with the exchange of messages between 
communicating SOAP nodes. Although SOAP poses no constraints on 
the potential scope of such features, example features include 
"reliability", "security", "correlation", and "routing". In 
addition, the communication might require a variety of message 
exchange patterns (MEPs) such as one-way messages, 
request/response interactions, and peer-to-peer conversations. 
MEPs are considered to be a type of feature, and unless otherwise 
stated, references in this specification to the term "feature" 
apply also to MEPs. The request-response MEP specified in [SOAP 
Part2] illustrates the specification of a MEP feature.
</current>

A simple approach to removing the confusion is to cut down the 
text to a single sentence:

<short section="3.1, 1st paragraph">
A SOAP feature is an extension of the SOAP messaging framework. 
Example of features are "reliability", "security", "correlation", 
"routing" and also one-way messages, request/response 
interactions and peer to peer conversations.
</short>

Alternatively, we could go with a longer proposal:

<long section="3.1">
*A SOAP feature is* an extension of the SOAP messaging framework. 
*A SOAP feature is either associated with* the *transfer and 
processing of individual* SOAP messages *or with the exchange of 
related messages according to a given* message exchange pattern 
(MEP). *Examples of the former type of* features *are* 
"reliability", "security", "correlation" and "routing". *Example 
of the second type of features (MEPs) are* one-way messages, 
request/response interactions, and peer-to-peer conversations.
</long>

The transition with the next paragraph is then much smoother: 
"The SOAP extensibility model provides two mechanisms through 
which features can be expressed [...]".

In the above, I have removed the sentence about MEPs being a 
particular type of feature. I propose to add it back to the 
beginning of 3.3 MEPs:

<current section="3.3 MEPs">
A Message Exchnage Pattern (MEP) is a template that establishes a 
pattern for the exchange of messages between SOAP nodes. The 
specification of a message exchange pattern MUST:
<current>

<proposed section="3.3 MEPs">
A Message Exchnage Pattern (MEP) is a template that establishes a 
pattern for the exchange of messages between SOAP nodes. *MEPs 
are a type of feature, and unless otherwise stated, references in 
this specification to the term "feature" apply also to MEPs. The 
request-response MEP specified in [SOAP Part2] illustrates the 
specification of a MEP feature.*

The specification of a message exchange pattern MUST:
</proposed>

Comments?

Jean-Jacques.

[1] http://www.w3.org/2000/xp/Group/xmlp-lc-issues.html#x219
[2] 
http://lists.w3.org/Archives/Public/xmlp-comments/2002Aug/0017.html
[3] 
http://lists.w3.org/Archives/Public/xmlp-comments/2002Aug/0045.html

Jean-Jacques Moreau wrote:
> 
> Henrik Frystyk Nielsen wrote:
> 
>> And to shorten the second paragraph as follows:
>>
>> "The term 'SOAP module' refers to the specification of the syntax and
>> semantics of one or more SOAP header blocks. A module specification
>> adheres to the following rules. It:..."
> 
> 
> I'd like to suggest the following friendly amendment:
> 
> <friendlyAmendment>
> *A* SOAP Module refers to the *combined* specification of the syntax and 
> semantics of one or more SOAP header blocks. *A SOAP module implements 
> one or more SOAP features.* A module specification adheres to the 
> following rules. It:...
> </friendlyAmendment>
> 
> I'd also suggest that we lift the above definition (or a revised version 
> thereof) and add it to the glossary. There is currently no definition 
> for SOAP Module!
> 
>> And in list item 5 replace "(whether or not those features are
>> themselves modules)" with
>> "and SOAP modules" so that the item reads:
>>
>> "5. MUST clearly specify any known interactions with or changes to the
>> interpretation of the SOAP body. Furthermore, it MUST clearly specify
>> any known interactions with or changes to the interpretation of other
>> SOAP features and SOAP modules. [...]"
> 
> 
> I think this adds confusion rather than clarity, since a module is an 
> implementation of a feature. I don't think we need the extra "add SOAP 
> modules". I'd suggest ending the sentence with just "of other SOAP 
> features."
> 
> +1 to your other changes.
> 
> Jean-Jacques.
>

Received on Thursday, 7 November 2002 09:39:18 UTC