- From: David Booth <dbooth@dev.w3.org>
- Date: Tue, 14 Sep 2004 12:35:07 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20 In directory hutz:/tmp/cvs-serv30308 Modified Files: wsdl20-primer.xml wsdl20-primer.html Log Message: Corrected section numbers; minor edits. Index: wsdl20-primer.xml =================================================================== RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v retrieving revision 1.12 retrieving revision 1.13 diff -C2 -d -r1.12 -r1.13 *** wsdl20-primer.xml 14 Sep 2004 03:39:05 -0000 1.12 --- wsdl20-primer.xml 14 Sep 2004 12:35:04 -0000 1.13 *************** *** 64,72 **** <div2 id="PrimerStructure"> <head>Structure of the Primer</head> ! <p>In the following sections, We will cover various aspects of the WSDL 2.0 language.</p> ! <p>Section 2 explains how an abstract interface is described in WSDL 2.0. It first explains how messages are defined using XML Schema and get used by WSDL 2.0; it then moves on to examine the details of the interface construct. </p> ! <p>Section 3 explains how to bind an abstract interface to concrete transport protocols. It first introduces the WSDL 2.0 binding constructs, and then explains the binding extensions defined by @WSDL2.0 part 3@, including bindings for SOAP 1.2, SOAP 1.1 and HTTP.</p> ! <p>Section 4 covers service endpoint definitions.</p> ! <p>Section 5 covers advanced topics, including features and properties, flexible authoring styles, service references, use of URIs, etc. </p> </div2><div2 id="notation"> --- 64,72 ---- <div2 id="PrimerStructure"> <head>Structure of the Primer</head> ! <p>Section 2 provides a big picture view of WSDL 2.0. It desribes the purpose and scope of the language, and explains its most important concepts.</p> ! <p>Section 3 presents an example use case, the GreatH hotel reservation service, and explains how an abstract interface for this Web service is described in WSDL 2.0. It first explains how messages are defined using XML Schema and get used by WSDL 2.0; it then moves on to examine the details of the interface construct. </p> ! <p>Section 4 continues the GreatH example, explaining how to bind an abstract interface to concrete transport protocols. It first introduces the WSDL 2.0 binding constructs, and then explains the binding extensions defined by @WSDL2.0 part 3@, including bindings for SOAP 1.2, SOAP 1.1 and HTTP.</p> ! <p>Section 5 covers service endpoint definitions, further developing the GreatH example.</p> ! <p>Section 6 covers advanced topics, including features and properties, flexible authoring styles, service references, use of URIs, etc. </p> </div2><div2 id="notation"> *************** *** 165,169 **** <div2 id="Web_Service_Descriptions"> ! <head>What Is a WSDL 2.0 Web Service Description (WSD)?</head> <p>A WSDL 2.0 <emph>Web service description</emph> (WSD) is an XML document that describes the mechanics of interacting with a particular Web service. Although a WSD is written solely from the point of view of the Web service (or the <xspecref href="http://www.w3.org/TR/2004/NOTE-ws-arch-20040211/#reqpro">provider agent</xspecref> that realizes that service), it is inherently intended to constrain <emph>both</emph> the provider agent <emph>and</emph> the <xspecref href="http://www.w3.org/TR/2004/NOTE-ws-arch-20040211/#reqpro">requester agent</xspecref> that makes use of that service. The WSD is therefore concerned only with information that <emph>both</emph> parties must agree upon -- not information that is relevant only to one party or the other, such as internal implementation details. It represents a take-it-or-leave-it "contract" that governs the interaction between requester agent and provider agent. Of course, this "contract" is only partial because in general it only describes the <eph>mechanics</emph> of the interaction -- not the intended semantics. Description of the application semantics is outside the scope of WSDL 2.0.</p><p>In some cases, the WSD is created before the provider agent is realized, and the provider agent is then created to conform to the WSD. In other cases the WSD is created at the same time or after the provider agent has been created. Although the provider agent must faithfully implement the WSD, WSDL 2.0 makes no requirement about which is created first. Both approaches are useful in different situations.</p> <p></p> --- 165,169 ---- <div2 id="Web_Service_Descriptions"> ! <head>The Purpose of the Web Service Description (WSD)</head> <p>A WSDL 2.0 <emph>Web service description</emph> (WSD) is an XML document that describes the mechanics of interacting with a particular Web service. Although a WSD is written solely from the point of view of the Web service (or the <xspecref href="http://www.w3.org/TR/2004/NOTE-ws-arch-20040211/#reqpro">provider agent</xspecref> that realizes that service), it is inherently intended to constrain <emph>both</emph> the provider agent <emph>and</emph> the <xspecref href="http://www.w3.org/TR/2004/NOTE-ws-arch-20040211/#reqpro">requester agent</xspecref> that makes use of that service. The WSD is therefore concerned only with information that <emph>both</emph> parties must agree upon -- not information that is relevant only to one party or the other, such as internal implementation details. It represents a take-it-or-leave-it "contract" that governs the interaction between requester agent and provider agent. Of course, this "contract" is only partial because in general it only describes the <eph>mechanics</emph> of the interaction -- not the intended semantics. Description of the application semantics is outside the scope of WSDL 2.0.</p><p>In some cases, the WSD is created before the provider agent is realized, and the provider agent is then created to conform to the WSD. In other cases the WSD is created at the same time or after the provider agent has been created. Although the provider agent must faithfully implement the WSD, WSDL 2.0 makes no requirement about which is created first. Both approaches are useful in different situations.</p> <p></p> *************** *** 1091,1113 **** <p>One technique is to ensure that the top-level elements declared in your message schema are different for different operations. This is probably the most general solution, since it is guaranteed to provide a way to perform dispatch, without preventing toolkits from potentially using other dispatch techniques.</p> <p>Another technique is to define a required feature that enables a particular dispatching convention. This approach makes the dispatching convention explicit, although it may not be supported by every WSDL toolkit.</p> ! </div2> ! </div1> ! <!-- **********************************NotesOnURIs***************** --> ! <!-- **********************************NotesOnURIs***************** --> ! <div1 id="uri"> ! <head>Notes on URIs</head> ! <ednote> ! <name>KevinL</name> ! <date>20040526</date> ! <edtext> ! This section is subject to being treated as a subsection of Advanced Topic ! </edtext> ! </ednote> ! <p>This section does not directly contribute to the specification, but provide background that may be useful when ! implementing the specification.</p> ! <div2> ! <head>XML namespaces and schema locations</head> ! <p>It is a common misperception to equate the <att> targetNamespace</att> of an XML schema or the value of the <att>xmlns</att> attribute in XML instances with the location --- 1091,1097 ---- <p>One technique is to ensure that the top-level elements declared in your message schema are different for different operations. This is probably the most general solution, since it is guaranteed to provide a way to perform dispatch, without preventing toolkits from potentially using other dispatch techniques.</p> <p>Another technique is to define a required feature that enables a particular dispatching convention. This approach makes the dispatching convention explicit, although it may not be supported by every WSDL toolkit.</p> ! </div2><!-- **********************************NotesOnURIs***************** --><div2><head>Notes on URIs</head><p>This section does not directly contribute to the specification, but provide background that may be useful when ! implementing the specification.</p><div3><head>XML namespaces and schema locations</head><p>It is a common misperception to equate the <att> targetNamespace</att> of an XML schema or the value of the <att>xmlns</att> attribute in XML instances with the location *************** *** 1121,1138 **** specification provides the processing context here via the <att>import</att> mechanism, which is based on the XML ! schemas grammar for the similar concept.</p> ! </div2> ! <div2> ! <head>Relative URIs</head> ! <p>Throughout this document you see fully qualified URIs used in WSDL and XSD documents. The use of a fully qualified URI is simply to illustrate the referencing concepts. The use of relative URIs is completely allowed and is warranted in many cases. For information on processing relative URIs, see ! <loc href="http://www.ietf.org/rfc/rfc2396.txt">RFC2396</loc>.</p> ! </div2> ! <div2> ! <head>Generating URIs</head> ! <p>When working with WSDL, it is sometimes desirable to make up a URI for an entity, but not make the URI globally unique for all time and have it "mean" that version of the --- 1105,1114 ---- specification provides the processing context here via the <att>import</att> mechanism, which is based on the XML ! schemas grammar for the similar concept.</p></div3><div3><head>Relative URIs</head><p>Throughout this document you see fully qualified URIs used in WSDL and XSD documents. The use of a fully qualified URI is simply to illustrate the referencing concepts. The use of relative URIs is completely allowed and is warranted in many cases. For information on processing relative URIs, see ! <loc href="http://www.ietf.org/rfc/rfc2396.txt">RFC2396</loc>.</p></div3><div3><head>Generating URIs</head><p>When working with WSDL, it is sometimes desirable to make up a URI for an entity, but not make the URI globally unique for all time and have it "mean" that version of the *************** *** 1151,1157 **** context. It is not recommended that <attval> http://tempuri.org/</attval> be used as a base for stable, ! fixed entities.</p> ! </div2> </div1> <div1 id="References"> <head>References</head> --- 1127,1135 ---- context. It is not recommended that <attval> http://tempuri.org/</attval> be used as a base for stable, ! fixed entities.</p></div3></div2> </div1> + + <!-- ********************************** References ***************** --> + <div1 id="References"> <head>References</head> Index: wsdl20-primer.html =================================================================== RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.html,v retrieving revision 1.7 retrieving revision 1.8 diff -C2 -d -r1.7 -r1.8 *** wsdl20-primer.html 14 Sep 2004 03:39:05 -0000 1.7 --- wsdl20-primer.html 14 Sep 2004 12:35:04 -0000 1.8 *************** *** 141,146 **** 5. <a href="#Service">Defining Service Endpoints</a><br /> 6. <a href="#advanced">Advanced Topics - TBD</a><br /> ! 7. <a href="#uri">Notes on URIs</a><br /> ! 8. <a href="#References">References</a><br /> </p> </div> --- 141,145 ---- 5. <a href="#Service">Defining Service Endpoints</a><br /> 6. <a href="#advanced">Advanced Topics - TBD</a><br /> ! 7. <a href="#References">References</a><br /> </p> </div> *************** *** 158,164 **** Conventions</a><br /> 2. <a href="#IntroductionWS">WSDL 2.0: The Big Picture</a><br /> !     2.1 <a ! href="#Web_Service_Descriptions">What Is a WSDL 2.0 Web Service ! Description (WSD)?</a><br />         2.1.1 <a href="#scope">WSDL 2.0 Scope: Individual Web Services</a><br /> --- 157,162 ---- Conventions</a><br /> 2. <a href="#IntroductionWS">WSDL 2.0: The Big Picture</a><br /> !     2.1 <a href="#Web_Service_Descriptions">The ! Purpose of the Web Service Description (WSD)</a><br />         2.1.1 <a href="#scope">WSDL 2.0 Scope: Individual Web Services</a><br /> *************** *** 167,177 ****     2.3 <a href="#overview">WSDL 2.0 Extensibility</a><br /> !     2.4 <a href="#id5185502">XML Syntax Summary</a><br />         2.4.1 <a ! href="#id5194598">Target Namespace and Symbol Spaces</a><br /> 3. <a href="#interface">Defining an Abstract Interface for a Web Service</a><br /> !     3.1 <a href="#id5194735">Example: The GreatH Hotel Reservation Service</a><br />     3.2 <a href="#messages">Defining Messages --- 165,175 ----     2.3 <a href="#overview">WSDL 2.0 Extensibility</a><br /> !     2.4 <a href="#id5185506">XML Syntax Summary</a><br />         2.4.1 <a ! href="#id5194602">Target Namespace and Symbol Spaces</a><br /> 3. <a href="#interface">Defining an Abstract Interface for a Web Service</a><br /> !     3.1 <a href="#id5194738">Example: The GreatH Hotel Reservation Service</a><br />     3.2 <a href="#messages">Defining Messages *************** *** 206,254 **** 5. <a href="#Service">Defining Service Endpoints</a><br /> 6. <a href="#advanced">Advanced Topics - TBD</a><br /> !     6.1 <a href="#id5197936">Import mechanism and authoring style</a><br />     6.2 <a ! href="#id5197951">Extensibility</a><br />         6.2.1 <a ! href="#id5198048">Optional Versus Required Extensions</a><br />         6.2.2 <a ! href="#id5198099">Scoping of the wsdl:required Attribute</a><br />     6.3 <a href="#FP">Features and Properties</a><br /> !     6.4 <a href="#id5198162">MTOM Support</a><br /> !     6.5 <a href="#id5198176">Security Considerations</a><br /> !     6.6 <a href="#id5198185">Versioning and services equivalency</a><br />     6.7 <a href="#RPCstyle">Operation Style and RPC</a><br /> !     6.8 <a href="#id5198234">GET Versus POST: Which to Use?</a><br /> !     6.9 <a href="#id5198249">Service References</a><br /> !     6.10 <a href="#id5198266">XML Schema Examples</a><br /> !     6.11 <a href="#id5198279">Multiple In-Line Schemas</a><br />     6.12 <a ! href="#id5198298">schemaLocation</a><br /> !     6.13 <a href="#id5198328">Multiple Logical WSDL Documents Describing the Same Service</a><br /> !     6.14 <a href="#id5198348">Mapping to RDF and semantic web</a><br /> !     6.15 <a href="#id5198357">Enabling Easy Message Dispatch</a><br /> ! 7. <a href="#uri">Notes on URIs</a><br /> !     7.1 <a href="#id5198451">XML namespaces and ! schema locations</a><br /> !     7.2 <a href="#id5198491">Relative ! URIs</a><br /> !     7.3 <a href="#id5198532">Generating URIs</a><br /> ! 8. <a href="#References">References</a><br /> !     8.1 <a href="#Normative-References">Normative References</a><br /> !     8.2 <a href="#Informative-References">Informative References</a><br /> </p> --- 204,253 ---- 5. <a href="#Service">Defining Service Endpoints</a><br /> 6. <a href="#advanced">Advanced Topics - TBD</a><br /> !     6.1 <a href="#id5198071">Import mechanism and authoring style</a><br />     6.2 <a ! href="#id5198086">Extensibility</a><br />         6.2.1 <a ! href="#id5198183">Optional Versus Required Extensions</a><br />         6.2.2 <a ! href="#id5198234">Scoping of the wsdl:required Attribute</a><br />     6.3 <a href="#FP">Features and Properties</a><br /> !     6.4 <a href="#id5198297">MTOM Support</a><br /> !     6.5 <a href="#id5198311">Security Considerations</a><br /> !     6.6 <a href="#id5198320">Versioning and services equivalency</a><br />     6.7 <a href="#RPCstyle">Operation Style and RPC</a><br /> !     6.8 <a href="#id5198370">GET Versus POST: Which to Use?</a><br /> !     6.9 <a href="#id5198384">Service References</a><br /> !     6.10 <a href="#id5198401">XML Schema Examples</a><br /> !     6.11 <a href="#id5198414">Multiple In-Line Schemas</a><br />     6.12 <a ! href="#id5198433">schemaLocation</a><br /> !     6.13 <a href="#id5198460">Multiple Logical WSDL Documents Describing the Same Service</a><br /> !     6.14 <a href="#id5198479">Mapping to RDF and semantic web</a><br /> !     6.15 <a href="#id5198488">Enabling Easy Message Dispatch</a><br /> !     6.16 <a href="#id5198534">Notes on URIs</a><br /> !         6.16.1 <a ! href="#id5198548">XML namespaces and schema locations</a><br /> !         6.16.2 <a ! href="#id5198583">Relative URIs</a><br /> !         6.16.3 <a ! href="#id5198604">Generating URIs</a><br /> ! 7. <a href="#References">References</a><br /> !     7.1 <a href="#Normative-References">Normative References</a><br /> !     7.2 <a href="#Informative-References">Informative References</a><br /> </p> *************** *** 290,310 **** Structure of the Primer</h3> ! <p>In the following sections, We will cover various aspects of the ! WSDL 2.0 language.</p> ! <p>Section 2 explains how an abstract interface is described in ! WSDL 2.0. It first explains how messages are defined using XML ! Schema and get used by WSDL 2.0; it then moves on to examine the ! details of the interface construct.</p> ! <p>Section 3 explains how to bind an abstract interface to concrete ! transport protocols. It first introduces the WSDL 2.0 binding ! constructs, and then explains the binding extensions defined by ! @WSDL2.0 part 3@, including bindings for SOAP 1.2, SOAP 1.1 and ! HTTP.</p> ! <p>Section 4 covers service endpoint definitions.</p> ! <p>Section 5 covers advanced topics, including features and properties, flexible authoring styles, service references, use of URIs, etc.</p> --- 289,313 ---- Structure of the Primer</h3> ! <p>Section 2 provides a big picture view of WSDL 2.0. It desribes ! the purpose and scope of the language, and explains its most ! important concepts.</p> ! <p>Section 3 presents an example use case, the GreatH hotel ! reservation service, and explains how an abstract interface for ! this Web service is described in WSDL 2.0. It first explains how ! messages are defined using XML Schema and get used by WSDL 2.0; it ! then moves on to examine the details of the interface ! construct.</p> ! <p>Section 4 continues the GreatH example, explaining how to bind ! an abstract interface to concrete transport protocols. It first ! introduces the WSDL 2.0 binding constructs, and then explains the ! binding extensions defined by @WSDL2.0 part 3@, including bindings ! for SOAP 1.2, SOAP 1.1 and HTTP.</p> ! <p>Section 5 covers service endpoint definitions, further ! developing the GreatH example.</p> ! <p>Section 6 covers advanced topics, including features and properties, flexible authoring styles, service references, use of URIs, etc.</p> *************** *** 446,451 **** <div class="div2"> <h3><a id="Web_Service_Descriptions" ! name="Web_Service_Descriptions"></a>2.1 What Is a WSDL 2.0 Web ! Service Description (WSD)?</h3> <p>A WSDL 2.0 <em>Web service description</em> (WSD) is an XML --- 449,454 ---- <div class="div2"> <h3><a id="Web_Service_Descriptions" ! name="Web_Service_Descriptions"></a>2.1 The Purpose of the Web ! Service Description (WSD)</h3> <p>A WSDL 2.0 <em>Web service description</em> (WSD) is an XML *************** *** 2436,2456 **** by every WSDL toolkit.</p> </div> - </div> - - <div class="div1"> - <h2><a id="uri" name="uri"></a>7. Notes on URIs</h2> ! <table border="1" summary="Editorial note: KevinL"> ! <tr> ! <td align="left" valign="top" width="50%"><b>Editorial note: ! KevinL</b></td> ! <td align="right" valign="top" width="50%">20040526</td> ! </tr> ! ! <tr> ! <td colspan="2" align="left" valign="top">This section is subject ! to being treated as a subsection of Advanced Topic</td> ! </tr> ! </table> <p>This section does not directly contribute to the specification, --- 2439,2445 ---- by every WSDL toolkit.</p> </div> ! <div class="div2"> ! <h3>6.16 Notes on URIs</h3> <p>This section does not directly contribute to the specification, *************** *** 2458,2463 **** specification.</p> ! <div class="div2"> ! <h3>7.1 XML namespaces and schema locations</h3> <p>It is a common misperception to equate the --- 2447,2452 ---- specification.</p> ! <div class="div3"> ! <h4>6.16.1 XML namespaces and schema locations</h4> <p>It is a common misperception to equate the *************** *** 2475,2480 **** </div> ! <div class="div2"> ! <h3>7.2 Relative URIs</h3> <p>Throughout this document you see fully qualified URIs used in --- 2464,2469 ---- </div> ! <div class="div3"> ! <h4>6.16.2 Relative URIs</h4> <p>Throughout this document you see fully qualified URIs used in *************** *** 2486,2491 **** </div> ! <div class="div2"> ! <h3>7.3 Generating URIs</h3> <p>When working with WSDL, it is sometimes desirable to make up a --- 2475,2480 ---- </div> ! <div class="div3"> ! <h4>6.16.3 Generating URIs</h4> <p>When working with WSDL, it is sometimes desirable to make up a *************** *** 2506,2512 **** </div> </div> <div class="div1"> ! <h2><a id="References" name="References"></a>8. References</h2> <table border="1" summary="Editorial note: KevinL"> --- 2495,2502 ---- </div> </div> + </div> <div class="div1"> ! <h2><a id="References" name="References"></a>7. References</h2> <table border="1" summary="Editorial note: KevinL"> *************** *** 2525,2529 **** <div class="div2"> <h3><a id="Normative-References" ! name="Normative-References"></a>8.1 Normative References</h3> <dl> --- 2515,2519 ---- <div class="div2"> <h3><a id="Normative-References" ! name="Normative-References"></a>7.1 Normative References</h3> <dl> *************** *** 2684,2688 **** <div class="div2"> <h3><a id="Informative-References" ! name="Informative-References"></a>8.2 Informative References</h3> <dl> --- 2674,2678 ---- <div class="div2"> <h3><a id="Informative-References" ! name="Informative-References"></a>7.2 Informative References</h3> <dl>
Received on Thursday, 16 September 2004 18:14:57 UTC