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

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 Friday, 22 November 2002 12:43:05 UTC