RE: Proposed Primer ToC

1. In the past people has stated that many of the examples in the
current SOAP 1.2 specification could be moved to the proposed Primer.
According to this description (you mention only examples
1,2,48,49,50,51,52) I assume you are proposing leaving most of the
examples in the other documents.  Is this true?
 
2. I think a section on SOAP 1.1 backwards compatability would be
useful.
 
3. I think a section on error conditions would be useful.  Everything in
your ToC seems to describe things that work perfectly.
 
 
/paulc
 
Paul Cotton, Microsoft Canada
17 Eleanor Drive, Nepean, Ontario K2E 6A3
Tel: (613) 225-5445 Fax: (425) 936-7329
< mailto:pcotton@microsoft.com> 

-----Original Message-----
From: Nilo Mitra (EMX) [mailto:Nilo.Mitra@am1.ericsson.se]
Sent: Wednesday, August 15, 2001 3:12 PM
To: 'XMLP Internal'
Subject: Proposed Primer ToC



Dear All: 
Based on a telecon between the editors of the current spec and myself,
please find below a proposed ToC for the SOAP:Primer.

My ideas for what the contents might be follow the headings in the ToC. 
Also, please note that the section headings are tentative place-holders,
chosen more to reflect 
the content. The scenario numbers S### are from the requirements
document [2]. 

Please let me know what you think. Thanks, 
Nilo 
nilo.mitra@ericsson.com 

[1]
http://lists.w3.org/Archives/Member/w3c-xml-protocol-wg/2001Aug/0023.htm
l 
[2] http://www.w3c.org/TR/2001/WD-xmlp-reqs-20010319/#N2690 

======== 

SOAP 1.2: Primer 
Table of Contents 

1. INTRODUCTION 

        1.1 Overview 
Briefly explain the separate entities: SOAP "core", its binding to
alternative transports,.... 
in effect a guide to the two parts of the specification 

        1.2 SOAP Processing Model 
Briefly explain what is done by/responsibility of SOAP processors, what
is outside 

        1.3 Extensibility mechanisms 
Briefly explain how applications can define new extension mechanisms.
Pointers to specific examples 
in Sections 2, 3. 


2. BASIC USAGE SCENARIOS 

        2.1 One-way SOAP messages 
  
<<covers S1; I don't think S2 needs an explicit example, just some text
perhaps>> 

This could be Example 0 from the current spec. 

We could follow up to show its use with acknowledgements <<scenario
S5>>, for HTTP POST 
and a response 202/204 and SMTP with DSN. 
(Would also serve to clarify the distinction between a SOAP one-way and
the underlying 
protocol's messaging pattern.) 

        2.2 Two-way SOAP messages 

                2.2.1 Document-style message exchange 

<<covers S3, maybe also S6>> 
Need to make up an example here. 

<<Could make up some examples here to cover S6 and S10 - encrypted
payload/header>> 

                2.2.2 SOAP for RPC 

<<covers S4>> 
Could use example 1/2 and/or example 48/50/52 from the current spec.
These show HTTP 
mapping. 

3. ADVANCED USAGE SCENARIOS 

This chapter would cover scenarios involving intermediaries, adding
headers, mU, etc. 
Two options are possible: sections based on features (e.g., adding new
headers..) versus 
sections named after scenarios (e.g., "Conversational message exchange")
showing the use of 
such features keeping the structure like section 2. For now, I chose the
former. 

The intent would be to show clearly what is in the scope of the spec and
what needs to be 
done outside of it via hooks provided in the spec (e.g., extension
mechansims) 

        3.1 Using headers 

Could provide one example here where a header block for correlation ID
is used along with 
an SMTP binding. <<covers scenario S8, S17, possibly S20 if example is
suitably chosen>> 

Could provide (a la example 49/51) example showing fault code for
failure to understand mandatory header. 

        3.2 Using SOAP intermediaries 

Need to provide *new* examples here (choose from tracking, logging,
cacheing,....) that exercise the 
actor and mU attributes. 
<<would cover S11, parts of S10, S807, S810, maybe others>> 
<<Paul Denning has sent me email saying that he'd like to "help with
S810". perhaps we could use some 
examples from SOAP-RP??>> 

        3.3 Using other transport bindings 

Need to provide examples. Or it could just be a description or issues
that the application designer 
must be aware of or what expectations to have when using any particular
underlying transport. 

        3.4 using other serialization schemes 



I have not been able to find a way to cover the more unusual usage
scenarios, c.f., S21. 
I'm not sure we need to validate each one of them. 
Comments welcome, 
Nilo