Re: wire stack words and diagram

Heather,

Overall, this[0] looks good. I have some comments regarding the 
SOAP description.

Jean-Jacques.

Heather Kreger wrote:
> Here is the words I have for the wire stack.  Same caveats as before.
> 
> (See attached file: wire.ZIP)

---------------------
"The current industry standard for XML packaging is the Simple 
Object Access Protocol (SOAP)[SOAP 00]."

     Given that SOAP 1.2 is no longer an acronym (for which
     no one has complained) -- and since I think you're really
     talking about SOAP 1.1 at this point -- I'd suggest simply
     saying: "SOAP 1.1 [SOAP 00]".

"IBM, Microsoft and others submitted SOAP to the W3C"

     s/SOAP/SOAP 1.1/

"as the basis of the XML Protocol Working Group [XMLP 00]."

     I suggest adding: "The XMLP WG is in the final stages of
     developping SOAP 1.2, the next version of SOAP.", which
     then provides a good transition to the following
     (amended) sentence:

"Once complete, XML Protocol implementations will replace the 
existing SOAP implementations as the industry standard XML 
messaging protocol."

      s/XML Protocol/SOAP 1.2/  (The name of the protocol
      is no longer XMLP [nor XP, as it used to be initially].)

"SOAP is a simple and lightweight XML-based mechanism for 
creating structured data packages that can exchanged between 
network applications. SOAP consists of four fundamental 
components: [...]"

      This is a description of SOAP 1.1. SOAP 1.2 has many
      more components than this (see below). Also, most
      components are now optional, so no longer
      fundamental.

      I'd thus suggest combining the above text with text
      derived from SOAP 1.2's abstracts for Part 1 and
      Part 2. Here's a suggestion:

      "SOAP 1.2 is a lightweight XML-based mechanism for
      creating structured data packages that can be exchanged
      between network applications. 'Part 1: Messaging
      Framework' defines an extensible messaging framework
      containing a message construct that can be exchanged
      over a variety of underlying protocols.

      'Part 2: Adjuncts' defines a set of optional
      extensions (adjuncts): a data model for
      representing application-defined data structures
      and values as a directed, edge-labeled graph;
      a set of rules for encoding instances of
      data that conform to the data model; a convention
      for how to use the data model for representing RPC
      calls and responses; a convention for describing
      features and bindings; a request-response message
      exchange pattern (MEP); a message exchange pattern
      supporting non-SOAP requests for SOAP responses; a
      feature for controlling the methods used on the
      World Wide Web; a binding to HTTP that follows the
      rules of the SOAP Protocol Binding Framework.

      SOAP 1.2 can be used in combination with a variety of
      network protocols; such as HTTP, SMTP, FTP, RMI/IIOP
      or MQSeries. A binding to Email [SOAP-EMail] has also
      been developped by the XMLP WG."

"SOAP is currently the de facto standard for XML messaging for a 
number of reasons. [...]"

      You may also wish to list XML as another reason for
      SOAP's success.

"As a key part of its envelope message structure, SOAP defines a 
mechanism to incorporate orthogonal extensions to the message in 
the form of headers and encoding rules."

      As of SOAP 1.2, extensions (now called "features")
      are either implemented as headers -- in which case
      the extension (the combination of the syntax
      and the associated processing) is called a
      "module" --, or via bindings -- in which case
      it is a "binding-supported feature" (no special
      name). SOAP 1.2 also introduces Message Exchange
      Patterns (MEPs), which are a 3rd type of "feature"
      (supported by bindings only).

      So, to catter for SOAP 1.2's revised extensibility model,
      I suggest the following two replacements (above):

        s/SOAP/SOAP 1.2/
        s/extensions/extensions (so called features)/

      and adding the following sentence:

        "SOAP 1.2 also allow features to be expressed via
        protocol bindings, when such features are implemented
        natively by underlying protocols."

"It is expected that as Web services are adopted and evolved, a 
broad collection of such extensions will emerge and be standardized."

      It may be worth pointing to the following
      existing feature definitions:
      the Web-Method feature [1], the Email correlation
      feature [2] and the (abstract) Attachment
      feature [3].

"the ability to build and/or parse a SOAP message"

      According to SOAP's terminology, this should be
      instead:

         "build and/or process"

"The XML document in the body of the message can be a SOAP RPC 
request or a document-centric message as indicated in the service 
description."

      RPCs are discouraged for safe retrieval (see [4,
      Example 12a]. Also, I think there is a growing
      feeling in the community (including within
      the XMLP and WSD WGs) that document-centric
      should be preferred over RPC.

      Should this then be indicating by the following changes?

         s/SOAP RPC/SOAP RPC (discouraged)/
         s/document-centric/document-centric (preferred)/

"The service requestor presents this message together with the 
network address of the service provider to the SOAP infrastructure"

       SOAP 1.2 would typically do this through
       a Message Exchange Context (MEC), which would
       contain more information that just the message
       address, for example the MEP and features used,
       the selected binding, etc.

       I suggest adding:

          ", via a Message Exchange Context (MEC). The
          MEC would typically contain the binding, MEP
          and feature used."

"The SOAP client runtime interacts with an underlying network 
protocol (e.g. HTTP) to send the SOAP message out over the network."

       As of SOAP 1.2, the interaction is mediated by
       a "SOAP protocol binding". I suggest:

         s/HTTP)/HTTP) via a SOAP protocol binding/

"The web service is responsible for processing the request message"

       I think there is a missing step of verifying all
       mandatory extensions/headers are understood, if
       any (as required by SOAP's processing model).

       Suggested replacement:

         "The web service is responsible for verifying
          all mandatory extensions/headers are understood,
          and, if so, for processing the request message"

"The response SOAP message is presented to the SOAP runtime with 
the service requestor as the destination"

       Again, that would typically involve passing
       a Message Exchange Context.

       I suggest adding:

         "The MEC would typically include the list of
          features used by the requesting node."

"In the case of synchronous request/response over HTTP, the 
underlying request/response nature of the networking protocol is 
used to implement the request/response nature of the messaging."

       As of SOAP 1.2, the application does not deal directly
       with the underlying protocol, but through the
       corresponding protocol binding.

       I suggest adding:

         "For SOAP 1.2, this is handled directly by the
          SOAP HTTP protocol binding."

"The response message is then presented to the application."

       Suggested addition:
         "and processed according to the rules of the SOAP
          processing model."

"This example uses the request/response transmission primitive 
that is quite common in most distributed computing environments. 
The request/response exchange may be synchronous or asynchronous. 
Other transmission primitives such as one-way messaging (no 
response), notification (push style response), publish/subscribe 
are possible using SOAP."

       s/primitive/message exchange pattern (MEP)/

       I suggest adding at the end:
         "The SOAP 1.2 binding to HTTP supports two Message
          Exchange Patterns natively: the Request-Response
          MEP and the SOAP-Response MEP. The Request-Response
          MEP should be used for all request/response style
          interactions that modify the state of the service
          provider. The SOAP-Response MEP should be used for
          all request-response style interactions that do
          not modify the state of the service provider. The
          actual MEP used depends on the value of the
          Web-Method feature."

"Interactions"

       Shouldn't there be an entry for Request-Response and
       SOAP-Response?

I hope this helps.

Jean-Jacques.

[0] http://lists.w3.org/Archives/Public/www-ws-arch/2002Sep/0296.html
[1] 
http://www.w3.org/2000/xp/Group/2/06/LC/soap12-part2.html#WebMethodFeature
[2] http://www.w3.org/TR/2002/NOTE-soap12-email-20020626#correlation
[3] 
http://www.w3.org/2000/xp/Group/2/07/SOAP-AF/aftf-soap-af.html#name
[4] http://www.w3.org/TR/2002/WD-soap12-part0-20020626/#L3677

Received on Tuesday, 1 October 2002 09:37:55 UTC