Re: Discussion summary: Proposal for clarifying relationship between SOAP modules and features

Suggestions for B):

<revised>
The term 'SOAP module' refers to the specification of the syntax 
and semantics of one or more SOAP header blocks. *A SOAP module 
realizes one or more SOAP features.* A module specification 
adheres to the following rules. It:
</revised>

and C):

<revised>
A SOAP Module is a specification that contains the combined 
syntax and semantics of SOAP header blocks specified according to 
the rules in 3.2 SOAP Modules. *A SOAP module realizes one or 
more SOAP features.*
</revised>

I can live with D).

I am fine with your other changes.

Jean-Jacques.

Henrik Frystyk Nielsen wrote:
> 
> Jean-Jacques,
> 
> Thanks for writing this up. I only have a few comments:
> 
> A) In 1) Part 1, section 3.1 "SOAP Features", I prefer the <jjm-long>
> version.
> 
> B) In 2) Part 1, section 3.2 "SOAP Modules" I would rather not talk
> about header blocks being implementations of SOAP features and would
> rather have the description be symmetrical with the first description of
> modules. That is, I think I prefer the initial proposal:
> 
> "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:"
> 
> C) In Part 1, section 3.2 "SOAP Modules", item 2, I have the same
> comment about avoiding the term "implement" but rather say:
> 
> "A SOAP Module is a specification that contains the combined syntax and
> semantics of SOAP header blocks specified according to the rules in 3.2
> SOAP Modules."
> 
> D) Here I would rather refer to the description of features rather than
> repeating the rules for referring to features using URIs etc.
> 
> "MUST declare the features provided by a module (see SOAP features)"
> 
> E) Regarding whether we should provide rules for what features are, I
> would prefer to state that *if* one has a something that needs to be
> exposed by a feature then it should be done as described. By using the
> explicit reference above, I think we make it clear that SOAP features
> are named regardless of whether they only live in a SOAP module or as a
> separate document. I would therefore think that, if accepted, that we do
> cover this case.
> 
> F) In 5) Part 1, section 3.2 "SOAP Modules", item 5, I think Noah's
> friendly amendment is fine (I think this was just spec original text)
> 
> In summary, below is an updated proposal that takes into account A-F. I
> took the liberty to simply the proposed changes to <current> vs.
> <proposed>--hopefully we can keep It together in the thread!
> 
> Thanks,
> 
> Henrik
> 
> * * * * * 
> 
> 1) Part 1, section 3.1 "SOAP Features"
> --------------------------------------
> 
> <current>
> When a feature is expressed this way, the combined syntax and semantics
> of such SOAP header blocks are known as a SOAP Module, and are specified
> according to the rules in 3.2 SOAP Modules.
> </current>
> 
> <proposed>
> The combined syntax and semantics of SOAP header blocks are known as a
> SOAP module, and are specified according to the rules in 3.2 SOAP
> Modules.
> </proposed>
> 
> 1) Part 1, section 3.1 "SOAP Features"
> --------------------------------------
> 
> <current>
> 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>
> 
> <proposed>
> *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.
> </proposed>
> 
> 2) Part 1, section 3.3 "MEPs"
> -----------------------------
> 
> [Add the sentence about MEPs being a particular type of feature, which
> was removed from proposal 1) above.]
> 
> <current>
> 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>
> A Message Exchange 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>
> 
> 2) Part 1, section 3.2 "SOAP Modules"
> -------------------------------------
> 
> <current>
> The term 'SOAP Module' refers to the set of syntax and semantics
> associated with implementing a particular feature (see 3.1 SOAP
> Features) as SOAP header blocks. A Module is described in a Module
> Specification, which adheres to the following rules. It:
> </current>
> 
> <proposed>
> 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:
> </proposed>
> 
> 3) Part 1, Glossary
> -------------------
> 
> <current>
> None
> </current>
> 
> <proposed>
> A SOAP Module is a specification that contains the combined syntax and
> semantics of SOAP header blocks specified according to the rules in 3.2
> SOAP Modules.
> </proposed>
> 
> 4) Part 1, section 3.2 "SOAP Modules", item 2
> ---------------------------------------------
> 
> <current>
> 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>
> 
> <proposed>
> MUST declare the features provided by a module (see SOAP features).
> </proposed>
> 
> 5) Part 1, section 3.2 "SOAP Modules", item 5
> ---------------------------------------------
> 
> <current>
> 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 (whether or not those features are themselves modules).
> For example, we can imagine a module which encrypts the SOAP body and
> inserts a SOAP header block containing a checksum and an indication of
> the encryption mechanism used. The specification for such a module would
> indicate that the decryption algorithm on the receiving side is to be
> run prior to any other modules which rely on the contents of the SOAP
> body.
> </current>
> 
> <proposed>
> 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*. For example, we can imagine a module
> which encrypts *and removes the SOAP body, inserting instead* a SOAP
> header block containing the encrypted information and an indication of
> the encryption mechanism used. The specification for such a module would
> indicate that a decryption algorithm on the receiving side is to be used
> to reconstruct the body prior to invoking other modules that rely on the
> contents of the SOAP body.
> </proposed>
> 
> 6) Part 1, TOC
> --------------
> 
> <current>
> 3. SOAP Extensibility Model
>     3.1 SOAP Features
>         3.1.1 Requirements on Features
>     3.2 SOAP Modules
>     3.3 SOAP Message Exchange Patterns (MEPs)
> </current>
> 
> <proposed>
> 3. SOAP Extensibility Model
>      3.1 SOAP Features
>          3.1.1 Requirements on Features
>      3.2 SOAP Message Exchange Patterns (MEPs)
>      3.3 SOAP Modules
> </proposed>
>

Received on Tuesday, 26 November 2002 05:47:48 UTC