- From: Jonathan Marsh via cvs-syncmail <cvsmail@w3.org>
- Date: Tue, 23 Jan 2007 16:28:38 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20
In directory hutz:/tmp/cvs-serv26687/wsdl20
Modified Files:
wsdl20-primer.xml wsdl20-primer.html
Log Message:
Incorporated CR134 resolution - easy message dispatching with HTTP binding.
Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.151
retrieving revision 1.152
diff -C 2 -d -r1.151 -r1.152
*** wsdl20-primer.xml 22 Dec 2006 19:04:56 -0000 1.151
--- wsdl20-primer.xml 23 Jan 2007 16:28:34 -0000 1.152
***************
*** 2432,2436 ****
the message received.</p>
! <p>For example, the WS-Addressing [WS-Addressing] specification provides such a
disambiguation mechanism. It consists of an extension element which may be marked
as required, and defines a required [action] property whose value is
--- 2432,2436 ----
the message received.</p>
! <p>For example, the WS-Addressing <bibref ref="WS-A"/> specification provides such a
disambiguation mechanism. It consists of an extension element which may be marked
as required, and defines a required [action] property whose value is
***************
*** 2441,2444 ****
--- 2441,2454 ----
uniquely.</p>
+ <p>When using the HTTP Binding, or when using the SOAP Binding with the
+ SOAP Response MEP, there is no SOAP envelope in a request message, and thus
+ mechanisms other than unique qualified names of global element declarations,
+ or headers such as wsa:Action, must be considered. In these cases, the
+ {address} and {http location} properties may be constructed so as to provide
+ a location that can be correlated uniquely with an operation. For instance,
+ one could prefix the {http location} property with the operation name, or
+ one could ensure that the portion of the {http location} preceding the first
+ unescaped "{" character be unique per operation.</p>
+
<!-- old text for this section, replaced by contribution from Umit
<p>Suppose a WSDL 2.0 document has two input-output operations and uses the same input message schema for both. When the service receives the input message, how will the service know which operation is supposed to be invoked? Although the data contained in a runtime message may be sufficient to distinguish between the operations, this can be a problem for WSDL 2.0 toolkits that are looking only at the message schema, rather than the actual messages. (For example, the toolkit may be operating at design time, without access to the runtime messages.) This is the problem of <emph>dispatch</emph>. How can a WSDL 2.0 document be written to ensure easy message dispatch? Strategies include:</p>
Index: wsdl20-primer.html
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.html,v
retrieving revision 1.176
retrieving revision 1.177
diff -C 2 -d -r1.176 -r1.177
*** wsdl20-primer.html 16 Jan 2007 03:19:53 -0000 1.176
--- wsdl20-primer.html 23 Jan 2007 16:28:34 -0000 1.177
***************
*** 1,3 ****
! <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Web Services Description Language (WSDL) Version 2.0 Part 0: Primer</title><style type="text/css">
code { font-family: monospace; }
--- 1,3 ----
! <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Web Services Description Language (WSDL) Version 2.0 Part 0: Primer</title><style type="text/css">
code { font-family: monospace; }
***************
*** 93,97 ****
<h2><a name="contents">Table of Contents</a></h2><p class="toc">1. <a href="#Introduction">Introduction</a><br> 1.1 <a href="#Prerequisites">Prerequisites</a><br> 1.2 <a href="#PrimerStructure">Structure of this Primer</a><br> 1.3 <a href="#UseIRI">Use of URIs and IRIs</a><br> 1.4 <a href="#notation">Notational Conventions</a><br>2. <a href="#basics">WSDL 2.0 Basics</a><br> 2.1 <a href="#basic-example">Getting Started: The GreatH Hotel Example</a><br> 2.1.1 <a href="#basics-greath-scenario">Example Scenario: The GreatH Hotel Reservation Service</a><br> 2.1.2 <a href="#basics-getting-started">Defining a WSDL 2.0 Target Namespace</a><br> 2.1.2.1 <a href="#example-empty-shell-explanation">Explanation of Example</a><br> &nbp; 2.1.3 <a href="#basics-types">Defining Message Types</a><br> 2.1.3.1 <a href="#example-initial-types-explanation">Explanation of Example</a><br> 2.1.4 <a href="#basics-interface">Defining an Interface</a><br> 2.1.4.1 <a href="#example-initial-interface-explanation">Explanation of Example</a><br> 2.1.5 <a href="#basics-binding">Defining a Binding</a><br> 2.1.5.1 <a href="#example-initial-binding-explanation">Explanation of Example</a><br> 2.1.6 <a href="#basics-service">Defining a Service</a><br> 2.1.6.1 <a href="#example-initial-service-explanation">Explanatin of Example</a><br> 2.1.7 <a href="#basics-documentation">Documenting the Service</a><br> 2.1.7.1 <a href="#example-initial-documentation-explanation">Explanation of Example</a><br> 2.2 <a href="#wsdl-xml-representation">WSDL 2.0 Infoset, Schema and Component Model</a><br> 2.2.1 <a href="#wsdl-infoset-diagram">WSDL 2.0 Infoset</a><br> 2.2.2 <a href="#wsdl-schema">WSDL 2.0 Schema</a><br> 2.2.2.1 <a href="#element-order">WSDL 2.0 Element Ordering</a><br> 2.2.3 <a href="#component-model">WSDL 2.0 Component Model</a><br> 2.2.3.1 <a href="#import-component">WSDL 2.0 Import and Include</a><br>&nbp; 2.3 <a href="#more-types">More on Message Types</a><br> 2.3.1 <a href="#more-types-schema-inline">Inlining XML Schema</a><br> 2.3.2 <a href="#more-types-schema-import">Importing XML Schema</a><br> 2.3.3 <a href="#more-types-import-include-summary">Summary of Import and Include Mechanisms</a><br> 2.4 <a href="#more-interfaces">More on Interfaces</a><br> 2.4.1 <a href="#more-interfaces-interfaces">Interface Syntax </a><br> 2.4.2 <a href="#more-interfaces-inheritance">Interface Inheritance</a><br> 2.4.3 <a href="#more-interfaces-faults">Interface Faults</a><br> 2.4.4 <a href="#more-interfaces-operations">Interface Operations</a><br> &bsp; 2.4.4.1 <a href="#more-interfaces-op-attr">Operation Attributes</a><br> 2.4.4.2 <a href="#N109C9">Operation Message References</a><br> 2.4.4.2.1 <a href="#N109E6">The messageLabel Attribute</a><br> 2.4.4.2.2 <a href="#N109FE">The element Attribute</a><br> 2.4.4.2.3 <a href="#N10A4F">Multiple infault or outfault Elements</a><br> 2.4.4.3 <a href="#more-interfaces-meps">Understanding Message Exchange Patterns (MEPs)</a><br> 2.5 <a href="#more-bindings">More on Bindings</a><br> nbsp; 2.5.1 <a href="#more-bindings-wsdl">Syntax Summary for Bindings</a><br> 2.5.2 <a href="#more-bindings-reusable">Reusable Bindings</a><br> 2.5.3 <a href="#more-bindings-faults">Binding Faults</a><br> 2.5.4 <a href="#bindingOperations">Binding Operations</a><br> 2.5.5 <a href="#more-bindings-soap">The SOAP Binding Extension</a><br> 2.5.5.1 <a href="#more-bindings-soap-example-explanation">Explanation of Example</a><br> 2.5.6 <a href="#more-bindings-http">The HTTP Binding Extension</a><br> 2.5.6.1 <a href="#N10C17">Explanation of
Example</a><br> 2.5.7 <a href="#adv-get-vs-post">HTTP GET Versus POST: Which to Use?</a><br>3. <a href="#advanced-topic_ii">Advanced Topics I: Importing Mechanisms</a><br> 3.1 <a href="#adv-import-and-authoring">Importing WSDL</a><br> 3.2 <a href="#adv-multiple-inline-schemas">Importing Schemas</a><br> 3.2.1 <a href="#N10D67">Schemas in Imported Documents</a><br> 3.2.2 <a href="#N10DF2">Multiple Inline Schemas in One Document</a><br> 3.2.3 <a href="#adv-schema-location">The schemaLocation Attribute</a><br> 3.2.3.1 <a href="#N10E52">Using the id Attribute to Identify Inline
! Schemas</a><br>4. <a href="#advanced-topic_iii">Advanced Topics II: Extensibility and Predefined Extensions</a><br> 4.1 <a href="#adv-extensibility">Extensibility</a><br> 4.1.1 <a href="#adv-optional-versus-required">Optional Versus Required Extensions</a><br> 4.2 <a href="#adv-MEP">Defining New MEPs</a><br> 4.2.1 <a href="#challenge-confirm">Confirmed Challenge</a><br> 4.3 <a href="#adv-RPCstyle">RPC Style</a><br>5. <a href="#advanced-topic_iv">Advanced Topics III: Miscellaneous</a><br> 5.1 <a href="#adv-message-dispatch">Enabling Easy Message Dispatch</a><br> 5.2 <a href="#adv-versioning">Web Service Versioning</a><br> 5.2.1 <a href="#adv-versioning-compatible-evolution">Compatible Evolution</a><br> .2.2 <a href="#adv-versioning-big-bang">Big Bang</a><br> 5.2.3 <a href="#ad-versioing-migration">Evolving a Service</a><br> 5.2.4 <a href="#adv-versioning-combined">Combined Approaches</a><br> 5.2.5 <a href="#adv-versioning-examples">Examples of Versioning and Extending a Service</a><br> 5.2.5.1 <a href="#N110EB">Additional Optional Elements Added in Content</a><br> 5.2.5.2 <a href="#N11102">Additional Optional Elements Added to a Header</a><br> 5.2.5.3 <a href="#N11119">Additional Mandatory Elements in Content</a><br> 5.2.5.4 <a href="#N11130">Additional Optional Operation Added to Interfae</a><br> 5.2.5.5 <a href="#N1113C">Additional Mandatory Operation Added to Interface</a><br> 5.2.5.6 <a href="#N11156">Indicating Incompatibility by Changing the Endpoint URI</a><br> 5.2.5.7 <a href="#N1115F">Indicating Incompatibility by Changing the SOAP Action</a><br> 5.2.5.8 <a href="#N11176">Indicating Incompatibility by Changing the Element Content</a><br> 5.3 <a href="#adv-service-references">
Describing Web Service Messages That Refer to Other Web
Services
--- 93,97 ----
<h2><a name="contents">Table of Contents</a></h2><p class="toc">1. <a href="#Introduction">Introduction</a><br> 1.1 <a href="#Prerequisites">Prerequisites</a><br> 1.2 <a href="#PrimerStructure">Structure of this Primer</a><br> 1.3 <a href="#UseIRI">Use of URIs and IRIs</a><br> 1.4 <a href="#notation">Notational Conventions</a><br>2. <a href="#basics">WSDL 2.0 Basics</a><br> 2.1 <a href="#basic-example">Getting Started: The GreatH Hotel Example</a><br> 2.1.1 <a href="#basics-greath-scenario">Example Scenario: The GreatH Hotel Reservation Service</a><br> 2.1.2 <a href="#basics-getting-started">Defining a WSDL 2.0 Target Namespace</a><br> 2.1.2.1 <a href="#example-empty-shell-explanation">Explanation of Example</a><br> &nbp; 2.1.3 <a href="#basics-types">Defining Message Types</a><br> 2.1.3.1 <a href="#example-initial-types-explanation">Explanation of Example</a><br> 2.1.4 <a href="#basics-interface">Defining an Interface</a><br> 2.1.4.1 <a href="#example-initial-interface-explanation">Explanation of Example</a><br> 2.1.5 <a href="#basics-binding">Defining a Binding</a><br> 2.1.5.1 <a href="#example-initial-binding-explanation">Explanation of Example</a><br> 2.1.6 <a href="#basics-service">Defining a Service</a><br> 2.1.6.1 <a href="#example-initial-service-explanation">Explanatin of Example</a><br> 2.1.7 <a href="#basics-documentation">Documenting the Service</a><br> 2.1.7.1 <a href="#example-initial-documentation-explanation">Explanation of Example</a><br> 2.2 <a href="#wsdl-xml-representation">WSDL 2.0 Infoset, Schema and Component Model</a><br> 2.2.1 <a href="#wsdl-infoset-diagram">WSDL 2.0 Infoset</a><br> 2.2.2 <a href="#wsdl-schema">WSDL 2.0 Schema</a><br> 2.2.2.1 <a href="#element-order">WSDL 2.0 Element Ordering</a><br> 2.2.3 <a href="#component-model">WSDL 2.0 Component Model</a><br> 2.2.3.1 <a href="#import-component">WSDL 2.0 Import and Include</a><br>&nbp; 2.3 <a href="#more-types">More on Message Types</a><br> 2.3.1 <a href="#more-types-schema-inline">Inlining XML Schema</a><br> 2.3.2 <a href="#more-types-schema-import">Importing XML Schema</a><br> 2.3.3 <a href="#more-types-import-include-summary">Summary of Import and Include Mechanisms</a><br> 2.4 <a href="#more-interfaces">More on Interfaces</a><br> 2.4.1 <a href="#more-interfaces-interfaces">Interface Syntax </a><br> 2.4.2 <a href="#more-interfaces-inheritance">Interface Inheritance</a><br> 2.4.3 <a href="#more-interfaces-faults">Interface Faults</a><br> 2.4.4 <a href="#more-interfaces-operations">Interface Operations</a><br> &bsp; 2.4.4.1 <a href="#more-interfaces-op-attr">Operation Attributes</a><br> 2.4.4.2 <a href="#N109C9">Operation Message References</a><br> 2.4.4.2.1 <a href="#N109E6">The messageLabel Attribute</a><br> 2.4.4.2.2 <a href="#N109FE">The element Attribute</a><br> 2.4.4.2.3 <a href="#N10A4F">Multiple infault or outfault Elements</a><br> 2.4.4.3 <a href="#more-interfaces-meps">Understanding Message Exchange Patterns (MEPs)</a><br> 2.5 <a href="#more-bindings">More on Bindings</a><br> nbsp; 2.5.1 <a href="#more-bindings-wsdl">Syntax Summary for Bindings</a><br> 2.5.2 <a href="#more-bindings-reusable">Reusable Bindings</a><br> 2.5.3 <a href="#more-bindings-faults">Binding Faults</a><br> 2.5.4 <a href="#bindingOperations">Binding Operations</a><br> 2.5.5 <a href="#more-bindings-soap">The SOAP Binding Extension</a><br> 2.5.5.1 <a href="#more-bindings-soap-example-explanation">Explanation of Example</a><br> 2.5.6 <a href="#more-bindings-http">The HTTP Binding Extension</a><br> 2.5.6.1 <a href="#N10C17">Explanation of
Example</a><br> 2.5.7 <a href="#adv-get-vs-post">HTTP GET Versus POST: Which to Use?</a><br>3. <a href="#advanced-topic_ii">Advanced Topics I: Importing Mechanisms</a><br> 3.1 <a href="#adv-import-and-authoring">Importing WSDL</a><br> 3.2 <a href="#adv-multiple-inline-schemas">Importing Schemas</a><br> 3.2.1 <a href="#N10D67">Schemas in Imported Documents</a><br> 3.2.2 <a href="#N10DF2">Multiple Inline Schemas in One Document</a><br> 3.2.3 <a href="#adv-schema-location">The schemaLocation Attribute</a><br> 3.2.3.1 <a href="#N10E52">Using the id Attribute to Identify Inline
! Schemas</a><br>4. <a href="#advanced-topic_iii">Advanced Topics II: Extensibility and Predefined Extensions</a><br> 4.1 <a href="#adv-extensibility">Extensibility</a><br> 4.1.1 <a href="#adv-optional-versus-required">Optional Versus Required Extensions</a><br> 4.2 <a href="#adv-MEP">Defining New MEPs</a><br> 4.2.1 <a href="#challenge-confirm">Confirmed Challenge</a><br> 4.3 <a href="#adv-RPCstyle">RPC Style</a><br>5. <a href="#advanced-topic_iv">Advanced Topics III: Miscellaneous</a><br> 5.1 <a href="#adv-message-dispatch">Enabling Easy Message Dispatch</a><br> 5.2 <a href="#adv-versioning">Web Service Versioning</a><br> 5.2.1 <a href="#adv-versioning-compatible-evolution">Compatible Evolution</a><br> .2.2 <a href="#adv-versioning-big-bang">Big Bang</a><br> 5.2.3 <a href="#ad-versioing-migration">Evolving a Service</a><br> 5.2.4 <a href="#adv-versioning-combined">Combined Approaches</a><br> 5.2.5 <a href="#adv-versioning-examples">Examples of Versioning and Extending a Service</a><br> 5.2.5.1 <a href="#N110F1">Additional Optional Elements Added in Content</a><br> 5.2.5.2 <a href="#N11108">Additional Optional Elements Added to a Header</a><br> 5.2.5.3 <a href="#N1111F">Additional Mandatory Elements in Content</a><br> 5.2.5.4 <a href="#N11136">Additional Optional Operation Added to Interfae</a><br> 5.2.5.5 <a href="#N11142">Additional Mandatory Operation Added to Interface</a><br> 5.2.5.6 <a href="#N1115C">Indicating Incompatibility by Changing the Endpoint URI</a><br> 5.2.5.7 <a href="#N11165">Indicating Incompatibility by Changing the SOAP Action</a><br> 5.2.5.8 <a href="#N1117C">Indicating Incompatibility by Changing the Element Content</a><br> 5.3 <a href="#adv-service-references">
Describing Web Service Messages That Refer to Other Web
Services
***************
*** 2519,2523 ****
the message received.</p>
! <p>For example, the WS-Addressing [WS-Addressing] specification provides such a
disambiguation mechanism. It consists of an extension element which may be marked
as required, and defines a required [action] property whose value is
--- 2519,2523 ----
the message received.</p>
! <p>For example, the WS-Addressing [<cite><a href="#WS-A">WS-Addressing</a></cite>] specification provides such a
disambiguation mechanism. It consists of an extension element which may be marked
as required, and defines a required [action] property whose value is
***************
*** 2528,2531 ****
--- 2528,2541 ----
uniquely.</p>
+ <p>When using the HTTP Binding, or when using the SOAP Binding with the
+ SOAP Response MEP, there is no SOAP envelope in a request message, and thus
+ mechanisms other than unique qualified names of global element declarations,
+ or headers such as wsa:Action, must be considered. In these cases, the
+ {address} and {http location} properties may be constructed so as to provide
+ a location that can be correlated uniquely with an operation. For instance,
+ one could prefix the {http location} property with the operation name, or
+ one could ensure that the portion of the {http location} preceding the first
+ unescaped "{" character be unique per operation.</p>
+
***************
*** 2646,2650 ****
<div class="div4">
! <h5><a name="N110EB"></a>5.2.5.1 Additional Optional Elements Added in Content</h5>
<p> The following example demonstrates how content may be extended with
additional content. The reservation service is changed to a newer version that can accept an optional
--- 2656,2660 ----
<div class="div4">
! <h5><a name="N110F1"></a>5.2.5.1 Additional Optional Elements Added in Content</h5>
<p> The following example demonstrates how content may be extended with
additional content. The reservation service is changed to a newer version that can accept an optional
***************
*** 2675,2679 ****
<div class="div4">
! <h5><a name="N11102"></a>5.2.5.2 Additional Optional Elements Added to a Header</h5>
<p> Another option is to add the extension as a header block. This is
accomplished by defining an element for the extension and adding a
--- 2685,2689 ----
<div class="div4">
! <h5><a name="N11108"></a>5.2.5.2 Additional Optional Elements Added to a Header</h5>
<p> Another option is to add the extension as a header block. This is
accomplished by defining an element for the extension and adding a
***************
*** 2710,2714 ****
<div class="div4">
! <h5><a name="N11119"></a>5.2.5.3 Additional Mandatory Elements in Content</h5>
<p> This following example demonstrates an extension with additional
content. The reservation service requires a number of guests parameter.
--- 2720,2724 ----
<div class="div4">
! <h5><a name="N1111F"></a>5.2.5.3 Additional Mandatory Elements in Content</h5>
<p> This following example demonstrates an extension with additional
content. The reservation service requires a number of guests parameter.
***************
*** 2738,2742 ****
<div class="div4">
! <h5><a name="N11130"></a>5.2.5.4 Additional Optional Operation Added to Interface</h5>
<p> Section <a href="#more-interfaces-inheritance"><b>2.4.2 Interface Inheritance</b></a> shows another type
of versioning or extension, where the reservationInterface extends the
--- 2748,2752 ----
<div class="div4">
! <h5><a name="N11136"></a>5.2.5.4 Additional Optional Operation Added to Interface</h5>
<p> Section <a href="#more-interfaces-inheritance"><b>2.4.2 Interface Inheritance</b></a> shows another type
of versioning or extension, where the reservationInterface extends the
***************
*** 2747,2751 ****
<div class="div4">
! <h5><a name="N1113C"></a>5.2.5.5 Additional Mandatory Operation Added to Interface</h5>
<p> Often mandatory operations are added to an interface. The Hotel service
decides to add an operation to the reservation service which is a
--- 2757,2761 ----
<div class="div4">
! <h5><a name="N11142"></a>5.2.5.5 Additional Mandatory Operation Added to Interface</h5>
<p> Often mandatory operations are added to an interface. The Hotel service
decides to add an operation to the reservation service which is a
***************
*** 2790,2794 ****
<div class="div4">
! <h5><a name="N11156"></a>5.2.5.6 Indicating Incompatibility by Changing the Endpoint URI</h5>
<p> To indicate incompatibility, the URI of the Hotel Endpoint can be
changed and messages send to the old Endpoint return a Fault.</p>
--- 2800,2804 ----
<div class="div4">
! <h5><a name="N1115C"></a>5.2.5.6 Indicating Incompatibility by Changing the Endpoint URI</h5>
<p> To indicate incompatibility, the URI of the Hotel Endpoint can be
changed and messages send to the old Endpoint return a Fault.</p>
***************
*** 2796,2800 ****
<div class="div4">
! <h5><a name="N1115F"></a>5.2.5.7 Indicating Incompatibility by Changing the SOAP Action</h5>
<p> The SOAP Action can be set for the makeReservation request, and making
it different than the earlier version should indicate incompatibility.</p>
--- 2806,2810 ----
<div class="div4">
! <h5><a name="N11165"></a>5.2.5.7 Indicating Incompatibility by Changing the SOAP Action</h5>
<p> The SOAP Action can be set for the makeReservation request, and making
it different than the earlier version should indicate incompatibility.</p>
***************
*** 2817,2821 ****
<div class="div4">
! <h5><a name="N11176"></a>5.2.5.8 Indicating Incompatibility by Changing the Element Content</h5>
<p> The namespace or name of the makeReservation element can be changed, and
then the interface and bindings changed. To indicate incompatibility,
--- 2827,2831 ----
<div class="div4">
! <h5><a name="N1117C"></a>5.2.5.8 Indicating Incompatibility by Changing the Element Content</h5>
<p> The namespace or name of the makeReservation element can be changed, and
then the interface and bindings changed. To indicate incompatibility,
Received on Tuesday, 23 January 2007 16:28:45 UTC