- From: Arthur Ryman via cvs-syncmail <cvsmail@w3.org>
- Date: Mon, 28 Mar 2005 12:23:24 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20
In directory hutz:/tmp/cvs-serv9697
Modified Files:
wsdl20-primer.html wsdl20-primer.xml
Log Message:
Added SOAP MTOM reference and corrected validation errors in Primer.
Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.40
retrieving revision 1.41
diff -C2 -d -r1.40 -r1.41
*** wsdl20-primer.xml 27 Mar 2005 16:35:34 -0000 1.40
--- wsdl20-primer.xml 28 Mar 2005 12:23:21 -0000 1.41
***************
*** 1273,1278 ****
<ulist>
! <item> /description/binding[@name="reservationSOAP11Binding"]</item>
! <item> /description/service/endpoint[@name="reservationEndpoint2"]</item>
</ulist>
--- 1273,1278 ----
<ulist>
! <item><p>/description/binding[@name="reservationSOAP11Binding"]</p></item>
! <item><p>/description/service/endpoint[@name="reservationEndpoint2"]</p></item>
</ulist>
***************
*** 1434,1440 ****
<p>
! This example defines an interface, <em>creditCardFaults</em>, that contains four faults, <em>cancelledCreditCard</em>,
! <em>expiredCreditCard</em>, <em>invalidCreditCardNumber</em>, and <em>invalidExpirationDate</em>.
! These components belong to the namespace <em>http://finance.example.com/CreditCards/wsdl</em>.
The faults are reused in the following hotel reservation service:
</p>
--- 1434,1440 ----
<p>
! This example defines an interface, <code>creditCardFaults</code>, that contains four faults, <code>cancelledCreditCard</code>,
! <code>expiredCreditCard</code>, <code>invalidCreditCardNumber</code>, and <code>invalidExpirationDate</code>.
! These components belong to the namespace <code>http://finance.example.com/CreditCards/wsdl</code>.
The faults are reused in the following hotel reservation service:
</p>
***************
*** 1483,1494 ****
<p>
! The hotel reservation service declares that it is using components from another namespace via the <em>import</em> element.
! The import element has a required <em>namespace</em> attribute that specifies the other namespace, and an optional <em>location</em> attribute
! that gives the processor a hint where to find the description of the other namespace.
! The <em>reservation</em> interface extends the <em>creditCardFault</em> interface from the other namespace in order to make the faults available
! in the reservation interface.
! Finally, the <em>makeReservation</em> operation refers to the standard faults in its <em>outfault</em> elements.
</p>
!
<p>
Another typical situation for using imports is to define a standard interface that is to be implemented
--- 1483,1508 ----
<p>
! The hotel reservation service declares that it is using
! components from another namespace via the
! <code>import</code>>
! element. The import element has a required
! <code>namespace</code>
! attribute that specifies the other namespace, and an
! optional
! <code>location</code>
! attribute that gives the processor a hint where to find
! the description of the other namespace. The
! <code>reservation</code>
! interface extends the
! <code>creditCardFault</code>
! interface from the other namespace in order to make the
! faults available in the reservation interface. Finally,
! the
! <code>makeReservation</code>
! operation refers to the standard faults in its
! <code>outfault</code>
! elements.
</p>
!
<p>
Another typical situation for using imports is to define a standard interface that is to be implemented
***************
*** 1520,1524 ****
</ednote>
<!-- =============== -->
! <p>This section shows how the <bibref ref="xxx"/> SOAP Message Transmission Optimization Mechanism may be engaged in the WSDL 2.0 SOAP binding.</p>
<p>Let’s modify the CheckAvailability operation of the GreatH Hotel Reservation Service [ref] to return not only the room rate, but images of the room and the floorplan. We’ll modify the checkAvailabilityResponse data structure to include binary data representing these two images, indicated by xs:base64Binary data type:</p>
--- 1534,1538 ----
</ednote>
<!-- =============== -->
! <p>This section shows how the <bibref ref="SOAP-MTOM"/> SOAP Message Transmission Optimization Mechanism may be engaged in the WSDL 2.0 SOAP binding.</p>
<p>Let’s modify the CheckAvailability operation of the GreatH Hotel Reservation Service [ref] to return not only the room rate, but images of the room and the floorplan. We’ll modify the checkAvailabilityResponse data structure to include binary data representing these two images, indicated by xs:base64Binary data type:</p>
***************
*** 1690,1694 ****
natural to apply this capability to Web services.
This section describes
! <em>service references</em>
which are the Web service analogs of document
hyperlinks.
--- 1704,1708 ----
natural to apply this capability to Web services.
This section describes
! <emph>service references</emph>
which are the Web service analogs of document
hyperlinks.
***************
*** 1878,1882 ****
element is used in the messages of the retrieve and update
operations. In addition, the schema defines two
! <em>restrictions</em>
of WSDL complex types. The
<code>ReservationDetailsEndpointType</code>
--- 1892,1896 ----
element is used in the messages of the retrieve and update
operations. In addition, the schema defines two
! <emph>restrictions</emph>
of WSDL complex types. The
<code>ReservationDetailsEndpointType</code>
***************
*** 2494,2497 ****
--- 2508,2527 ----
4.2.3, S. Bradner, October 1996.</bibl>
-->
+
+ <bibl key="SOAP MTOM" id="SOAP-MTOM"
+ href="http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/">
+ <titleref>
+ SOAP Message Transmission Optimization
+ Mechanism
+ </titleref>, M. Gudgin, N. Mendelsohn, M. Nottingham, H.
+ Ruellan, Editors. World Wide Web Consortium, 25
+ January, 2005. This version of SOAP Message
+ Transmission Optimization Mechanism is available
+ at
+ <loc
+ href="http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/"/>
+ http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/.
+ </bibl>
+
<bibl key="XML Linking" href="http://www.w3.org/TR/2001/REC-xlink-20010627/" id="XLINK">
<titleref>XML Linking Language (XLink) Version 1.0</titleref>, S.
Index: wsdl20-primer.html
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.html,v
retrieving revision 1.22
retrieving revision 1.23
diff -C2 -d -r1.22 -r1.23
*** wsdl20-primer.html 23 Mar 2005 03:40:09 -0000 1.22
--- wsdl20-primer.html 28 Mar 2005 12:23:21 -0000 1.23
***************
*** 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; }
***************
*** 57,62 ****
</dl><p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> © @@@@ <a href="http://www.w3.org/"><acronym title="World Wide Web Consortium">W3C</acronym></a><sup>®</sup> (<a href="http://www.csail.mit.edu/"><acronym title="Massachusetts Institute of Technology">MIT</acronym></a>, <a href="http://www.ercim.org/"><acronym title="European Research Consortium for Informatics and Mathematics">ERCIM</acronym></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.</p></div><hr><div>
<h2><a name="abstract">Abstract</a></h2>
! <p>This document is a companion to the WSDL 2.0 specification (<em>Web Services Description Language (WSDL) Version 2.0 Part 1: Core Language</em> [<cite><a href="#WSDL-PART1">WSDL 2.0 Core Language</a></cite>], <em>Web Services Description Language (WSDL) Version 2.0 Part 2: Predefined Extensions</em> [<cite><a href="#WSDL-PART2">WSDL 2.0 Predefined Extensions</a></cite>], <em>Web Services Description Language (WSDL) Version 2.0 Part 3: Bindings</em> [<cite><a href="#WSDL-PART3">WSDL 2.0 Bindings</a></cite>]). It is intended for readers who wish to have an easier, less technical introduction to the main features of the language. </p><p>This primer is only intended to be a starting point toward use of WSDL 2.0, and hence does not describe every feature of the language. Users are expected to consult the WSDL 2.0 specification if they wish to make use of more sophisticated features or techniques.</p>
! <p>Finally, this primer is <em>non-normative</em>. Any specific questions of what WSDL 2.0 requires or forbids should be referred to the WSDL 2.0 specification. </p>
</div><div>
<h2><a name="status">Status of this Document</a></h2><p><strong>This document is an editors' copy that has
--- 57,92 ----
</dl><p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a> © @@@@ <a href="http://www.w3.org/"><acronym title="World Wide Web Consortium">W3C</acronym></a><sup>®</sup> (<a href="http://www.csail.mit.edu/"><acronym title="Massachusetts Institute of Technology">MIT</acronym></a>, <a href="http://www.ercim.org/"><acronym title="European Research Consortium for Informatics and Mathematics">ERCIM</acronym></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>, <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a> and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document use</a> rules apply.</p></div><hr><div>
<h2><a name="abstract">Abstract</a></h2>
! <p>
! This document is a companion to the WSDL 2.0
! specification (
! <em>
! Web Services Description Language (WSDL) Version 2.0
! Part 1: Core Language
! </em>
! [<cite><a href="#WSDL-PART1">WSDL 2.0 Core Language</a></cite>]
! ,
! <em>
! Web Services Description Language (WSDL) Version 2.0
! Part 2: Adjuncts
! </em>
! [<cite><a href="#WSDL-PART2">WSDL 2.0 Adjuncts</a></cite>]
! ). It is intended for readers who wish to have an
! easier, less technical introduction to the main features
! of the language.
! </p>
! <p>
! This primer is only intended to be a starting point
! toward use of WSDL 2.0, and hence does not describe
! every feature of the language. Users are expected to
! consult the WSDL 2.0 specification if they wish to make
! use of more sophisticated features or techniques.
! </p>
! <p>
! Finally, this primer is
! <em>non-normative</em>
! . Any specific questions of what WSDL 2.0 requires or
! forbids should be referred to the WSDL 2.0
! specification.
! </p>
</div><div>
<h2><a name="status">Status of this Document</a></h2><p><strong>This document is an editors' copy that has
***************
*** 64,68 ****
<hr><div class="toc">
<h2><a name="shortcontents">Short Table of Contents</a></h2><p class="toc">1. <a href="#Introduction">Introduction</a><br>2. <a href="#basics">WSDL 2.0 Basics</a><br>3. <a href="#wsdl-xml-representation">WSDL 2.0 XML Representation</a><br>4. <a href="#advanced-topic-i">Advanced Topic I: More on Messages, Interfaces, Bindings, and Services Definitions</a><br>5. <a href="#advanced-topic_ii">Advanced Topics II - TBD</a><br>6. <a href="#References">References</a><br></p></div><hr><div class="toc">
! <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="#notation">Notational Conventions</a><br>2. <a href="#basics">WSDL 2.0 Basics</a><br> 2.1 <a href="#basics-greath-scenario">Example Scenario: The GreatH Hotel Reservation Service</a><br> 2.2 <a href="#basics-getting-started">Getting Started: Defining a WSDL Target Namespace</a><br> 2.2.1 <a href="#example-empty-shell-explanation">Explanation of Example</a><br> 2.3 <a href="#basics-types">Defining Message Types</a><br> 2.3.1 <a href="#example-initial-types-explanation">Explanation of Example</a><br> 2.4 <a href="#basics-nterface">Defining an Interface</a><br> 2.4.1 <a href="#example-initial-interface-explanation">Explanation of Example</a><br> 2.5 <a href="#basics-binding">Defining a Binding</a><br> 2.5.1 <a href="#example-initial-binding-explanation">Explanation of Example</a><br> 2.6 <a href="#basics-service">Defining a Service</a><br> 2.6.1 <a href="#example-initial-service-explanation">Explanation of Example</a><br> 2.7 <a href="#basics-documentation">Documenting the Service</a><br> 2.7.1 <a href="#example-initial-documentation-explanation">Explanation of Example</a><br>3. <a href="#wsdl-xml-representation">WSDL 2.0 XML Representation</a><br> 3.1 <a href="#wsdl-infoset-diagram">WSDL2.0 Infoset Model Overview</a><br> 3.2 < href="#wsdl-xml-syntax">WSDL2.0 XML Syntax Summary</a><br> 3.3 <a href="#wsdl-element-order">Order of WSDL Elements and Placement of Extensions</a><br>4. <a href="#advanced-topic-i">Advanced Topic I: More on Messages, Interfaces, Bindings, and Services Definitions</a><br> 4.1 <a href="#more-types">Defining Messages</a><br> 4.1.1 <a href="#more-types-schema">Defining Messages Using XML Schema</a><br> 4.1.1.1 <a href="#more-types-schema-embed">Embedding XML Schema</a><br> 4.1.1.2 <a href="#more-types-schema-import">Importing XML Schema</a><br> 4.1.2 <a href="#more-types-other-schema">Defining Messages Using other type languages</a><br> 4.2 <a href="#more-interfaces">More on Interfaces</a><br>   4.2.1 <a href="#more-interfaces-interfaces">Interface Syntax </a><br> 4.2.1.1 <a href="#more-interfaces-inheritance">Interface Inheritance</a><br> 4.2.1.2 <a href="#more-interfaces-faults">Reusable Faults</a><br> 4.2.1.3 <a href="#more-interfaces-operations">Interface Operations</a><br> 4.2.2 <a href="#more-interfaces-meps">Understanding Message Exchange Patterns</a><br> 4.3 <a href="#more-bindings">More on Bindings</a><br> 4.3.1 <a href="#more-bindings-wsdl">Binding Constructs in WSDL Namespace</a><br> 4.3.1.1 <a href="#more-bindings-faults">Binding Faults</a><br> &nsp; 4.3.1.2 <a href="#bindingOperations">Binding Operations</a><br> 4.3.2 <a href="#more-bindings-soap">Extensions for SOAP Binding</a><br> 4.3.3 <a href="#more-bindings-http">Extensions for HTTP Binding</a><br> 4.4 <a href="#more-service">More on Service Endpoints </a><br>5. <a href="#advanced-topic_ii">Advanced Topics II - TBD</a><br> 5.1 <a href="#adv-extensibility">Extensibility</a><br> 5.1.1 <a href="#adv-optional-versus-required">Optional Versus Required Extensions</a><br> 5.1.2 <a href="#adv-scope-of-wsdl-required">Scoping of the wsdl:required Attribute</a><br> 5.2 <a href="#adv-FP">Features and Properties</a><br> 5.3 <a href="#adv-import-and-authoring">Import mechanism and authring style</a><br> 5.4 <a href="#adv-multiple-docs-describing-same-service">Multiple Logical WSDL Documents Describing the Same Service</a><br> 5.5 <a href="#adv-versioning">Versioning and Service Equivalency</a><br> 5.6 <a href="#adv-MTOM">MTOM Support</a><br> 5.7 <a href="#adv-security">Security Considerations</a><br> 5.8 <a href="#adv-RPCstyle">Operation Style and RPC</a><br> 5.9 <a href="#adv-message-dispatch">Enabling Easy Message Dispatch</a><br> 5.10 <a href="#adv-get-vs-post">GET Versus POST: Which to Use?</a><br> 5.11 <a href="#adv-service-references">Service References</a><br> 5.12 <a href="#adv-xml-schema-examples">XML Schema Examples</a><br> 5.13 <a href="#adv-multiple-inline-schemas">Multiple In-Line Schemas</a><br> 5.14 <a href="#adv-schema-locaion">The schemaLocation Attribute</a><br> 5.15 <a href="#adv-rdf-mapping">Mapping to RDF and Semantic Web</a><br> 5.16 <a href="#adv-notes-on-uris">Notes on URIs</a><br> 5.16.1 <a href="#adv-namespaces-and-schema-locations">XML Namespaces and Schema Locations</a><br> 5.16.2 <a href="#adv-relative-uris">Relative URIs</a><br> 5.16.3 <a href="#adv-generating-uris">Generating Temporary URIs</a><br>6. <a href="#References">References</a><br> 6.1 <a href="#Normative-References">Normative References</a><br> 6.2 <a href="#Informative-References">Informative References</a><br></p></div><hr><div class="body">
--- 94,98 ----
<hr><div class="toc">
<h2><a name="shortcontents">Short Table of Contents</a></h2><p class="toc">1. <a href="#Introduction">Introduction</a><br>2. <a href="#basics">WSDL 2.0 Basics</a><br>3. <a href="#wsdl-xml-representation">WSDL 2.0 XML Representation</a><br>4. <a href="#advanced-topic-i">Advanced Topic I: More on Messages, Interfaces, Bindings, and Services Definitions</a><br>5. <a href="#advanced-topic_ii">Advanced Topics II - TBD</a><br>6. <a href="#References">References</a><br></p></div><hr><div class="toc">
! <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="#notation">Notational Conventions</a><br>2. <a href="#basics">WSDL 2.0 Basics</a><br> 2.1 <a href="#basics-greath-scenario">Example Scenario: The GreatH Hotel Reservation Service</a><br> 2.2 <a href="#basics-getting-started">Getting Started: Defining a WSDL Target Namespace</a><br> 2.2.1 <a href="#example-empty-shell-explanation">Explanation of Example</a><br> 2.3 <a href="#basics-types">Defining Message Types</a><br> 2.3.1 <a href="#example-initial-types-explanation">Explanation of Example</a><br> 2.4 <a href="#basics-nterface">Defining an Interface</a><br> 2.4.1 <a href="#example-initial-interface-explanation">Explanation of Example</a><br> 2.5 <a href="#basics-binding">Defining a Binding</a><br> 2.5.1 <a href="#example-initial-binding-explanation">Explanation of Example</a><br> 2.6 <a href="#basics-service">Defining a Service</a><br> 2.6.1 <a href="#example-initial-service-explanation">Explanation of Example</a><br> 2.7 <a href="#basics-documentation">Documenting the Service</a><br> 2.7.1 <a href="#example-initial-documentation-explanation">Explanation of Example</a><br>3. <a href="#wsdl-xml-representation">WSDL 2.0 XML Representation</a><br> 3.1 <a href="#wsdl-infoset-diagram">WSDL2.0 Infoset Model Overview</a><br> 3.2 < href="#wsdl-xml-syntax">WSDL2.0 XML Syntax Summary</a><br> 3.3 <a href="#wsdl-element-order">Order of WSDL Elements and Placement of Extensions</a><br>4. <a href="#advanced-topic-i">Advanced Topic I: More on Messages, Interfaces, Bindings, and Services Definitions</a><br> 4.1 <a href="#more-types">Defining Messages</a><br> 4.1.1 <a href="#more-types-schema">Defining Messages Using XML Schema</a><br> 4.1.1.1 <a href="#more-types-schema-embed">Embedding XML Schema</a><br> 4.1.1.2 <a href="#more-types-schema-import">Importing XML Schema</a><br> 4.1.2 <a href="#more-types-other-schema">Defining Messages Using other type languages</a><br> 4.2 <a href="#more-interfaces">More on Interfaces</a><br>   4.2.1 <a href="#more-interfaces-interfaces">Interface Syntax </a><br> 4.2.1.1 <a href="#more-interfaces-inheritance">Interface Inheritance</a><br> 4.2.1.2 <a href="#more-interfaces-faults">Reusable Faults</a><br> 4.2.1.3 <a href="#more-interfaces-operations">Interface Operations</a><br> 4.2.2 <a href="#more-interfaces-meps">Understanding Message Exchange Patterns</a><br> 4.3 <a href="#more-bindings">More on Bindings</a><br> 4.3.1 <a href="#more-bindings-wsdl">Binding Constructs in WSDL Namespace</a><br> 4.3.1.1 <a href="#more-bindings-faults">Binding Faults</a><br> &nsp; 4.3.1.2 <a href="#bindingOperations">Binding Operations</a><br> 4.3.2 <a href="#more-bindings-soap">Extensions for SOAP Binding</a><br> 4.3.3 <a href="#more-bindings-http">Extensions for HTTP Binding</a><br> 4.4 <a href="#more-service">More on Service Endpoints </a><br>5. <a href="#advanced-topic_ii">Advanced Topics II - TBD</a><br> 5.1 <a href="#adv-extensibility">Extensibility</a><br> 5.1.1 <a href="#adv-optional-versus-required">Optional Versus Required Extensions</a><br> 5.1.2 <a href="#adv-scope-of-wsdl-required">Scoping of the wsdl:required Attribute</a><br> 5.2 <a href="#adv-FP">Features and Properties</a><br> 5.3 <a href="#adv-import-and-authoring">Import mechanism and authring style</a><br> 5.4 <a href="#adv-multiple-docs-describing-same-service">Multiple Logical WSDL Documents Describing the Same Service</a><br> 5.5 <a href="#adv-versioning">Versioning and Service Equivalency</a><br> 5.6 <a href="#adv-MTOM">MTOM Support</a><br> 5.7 <a href="#adv-security">Security Considerations</a><br> 5.8 <a href="#adv-RPCstyle">Operation Style and RPC</a><br> 5.9 <a href="#adv-message-dispatch">Enabling Easy Message Dispatch</a><br> 5.10 <a href="#adv-get-vs-post">GET Versus POST: Which to Use?</a><br> 5.11 <a href="#adv-service-references">Service References</a><br> 5.11.1 <a href="#reservationDetails">The Reservation Details Web Service</a><br> 5.11.2 <a href="#reservationList">The Reservation List Web Service</a<br> 5.12 <a href="#adv-xml-schema-examples">XML Schema Examples</a><br> 5.13 <a href="#adv-multiple-inline-schemas">Multiple In-Line Schemas</a><br> 5.14 <a href="#adv-schema-location">The schemaLocation Attribute</a><br> 5.15 <a href="#adv-rdf-mapping">Mapping to RDF and Semantic Web</a><br> 5.16 <a href="#adv-notes-on-uris">Notes on URIs</a><br> 5.16.1 <a href="#adv-namespaces-and-schema-locations">XML Namespaces and Schema Locations</a><br> 5.16.2 <a href="#adv-relative-uris">Relative URIs</a><br> 5.16.3 <a href="#adv-generating-uris">Generating Temporary URIs</a><br>6. <a href="#References">References</a><br> 6.1 <a href="#Normative-References">Normative References</a><br> 6.2 <a href="#Informative-Referenes">Informative References</a><br></p></div><hr><div class="body">
***************
*** 245,249 ****
</div><div class="div3">
<h4><a name="example-initial-types-explanation"></a>2.3.1 Explanation of Example</h4><dl><dt class="label"><code>xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc"</code></dt><dd><p>We've added another namespace declaration. The <code>ghns</code> namespace prefix will allow us (later, when defining an interface) to reference the XML Schema target namespace that we define for our message types. Thus, the URI we specify must be the same as the URI that we define as the target namespace of our XML Schema types (below) -- <em>not</em> the target namespace of the WSDL document itself.</p></dd><dt class="label"><code>targetNamespace="http://greath.example.com/2004/schemas/resSvc"</code></dt><dd><p>This is the XML Schema target namespace that we've created for use by the GreatH reservation service. The <code>checkAvailability</code>, <code>checkAvailabilityResponse</code> and <code>invalidDataError</code> element names will be associated with this XML Schema target namespace.</p></dd><dt class="lael"><code>checkAvailability</code>, <code>checkAvailabilityResponse</code> and <code>invalidDataError</code></dt><dd><p>These are the message types that we'll use. Note that these are defined to be XML <em>elements</em>, as explained above.</p></dd></dl><p>Although we have defined several types, we have not yet indicated which ones are to be used as message types for a Web service. We'll do that in the next section. </p></div></div><div class="div2">
! <h3><a name="basics-interface"></a>2.4 Defining an Interface</h3><p>WSDL 2.0 enables one to separate the description of a Web service's abstract functionality from the concrete details of how and where that functionality is offered. This separation facilitates different levels of reusability and distribution of work in the lifecycle of a Web service and the WSDL document that describes it. </p><p>A WSDL 2.0 <code>interface</code> defines the abstract interface of a Web service as a set of abstract <em>operations</em>, each operation representing a simple interaction between the client and the service. Each operation specifies the types of messages that the service can send or receive as part of that operation. Each operation also specifies a message exchange <em>pattern</em> that indicates the sequence in which the associated messages are to be transmitted between the parties. For example, the <em>in-out</em> pattern (see <em>WSDL 2.0 Predefined Extensions</em> [<cite><a href="#WSDL-PART2">WSDL 2.0Predefined Extensions</a></cite>] section 2.2.3 <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">In-Out</a>) indicates that if the client sends a message <em>in</em> to the service, the service will either send a reply message back <em>out</em> to the client (in the normal case) or it will send a fault message back to the client (in the case of an error).</p><p>For the GreatH service, we will (initially) define an interface containing a single operation, <code>opCheckAvailability</code>, using the <code>checkAvailability</code> and <code>checkAvailabilityResponse</code> message types that we defined in the <code>types</code> section. We'll use the <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</a> pattern for this operation, because this is the most natural way to represent a simple request-response interaction. We could have instead (for example) defined two separate operations using the <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-0040803/#in-out">in-only</a> and <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#out-only">out-only</a> patterns (see <em>WSDL 2.0 Predefined Extensions</em> [<cite><a href="#WSDL-PART2">WSDL 2.0 Predefined Extensions</a></cite>] section 2.2.1 <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-only">In-Only</a> and section 2.2.5 <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#out-only">Out-Only</a>), but that would just complicate matters for the client, because we would then have to separately indicate to the client developer that the two operations should be used together as a request-response pair.</p><p>In addition to the normal input and output messages, we also need to specify the fault message that we wish to use in the event of an error. WSDL 2.0 permits fault messages to be declared within the <code>interface</code> element in order to facilitate reuse of faults across operations. If a fault occurs, it terminates whatever message sequence ws indicated by the message exchange pattern of the operation. </p><p>Let's add these to our WSDL document.</p><div class="exampleOuter">
<p class="exampleHead" style="text-align: left"><a name="example-initial-interface"></a><i><span>Example 2-4. </span>GreatH Interface Definition</i></p>
--- 275,279 ----
</div><div class="div3">
<h4><a name="example-initial-types-explanation"></a>2.3.1 Explanation of Example</h4><dl><dt class="label"><code>xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc"</code></dt><dd><p>We've added another namespace declaration. The <code>ghns</code> namespace prefix will allow us (later, when defining an interface) to reference the XML Schema target namespace that we define for our message types. Thus, the URI we specify must be the same as the URI that we define as the target namespace of our XML Schema types (below) -- <em>not</em> the target namespace of the WSDL document itself.</p></dd><dt class="label"><code>targetNamespace="http://greath.example.com/2004/schemas/resSvc"</code></dt><dd><p>This is the XML Schema target namespace that we've created for use by the GreatH reservation service. The <code>checkAvailability</code>, <code>checkAvailabilityResponse</code> and <code>invalidDataError</code> element names will be associated with this XML Schema target namespace.</p></dd><dt class="lael"><code>checkAvailability</code>, <code>checkAvailabilityResponse</code> and <code>invalidDataError</code></dt><dd><p>These are the message types that we'll use. Note that these are defined to be XML <em>elements</em>, as explained above.</p></dd></dl><p>Although we have defined several types, we have not yet indicated which ones are to be used as message types for a Web service. We'll do that in the next section. </p></div></div><div class="div2">
! <h3><a name="basics-interface"></a>2.4 Defining an Interface</h3><p>WSDL 2.0 enables one to separate the description of a Web service's abstract functionality from the concrete details of how and where that functionality is offered. This separation facilitates different levels of reusability and distribution of work in the lifecycle of a Web service and the WSDL document that describes it. </p><p>A WSDL 2.0 <code>interface</code> defines the abstract interface of a Web service as a set of abstract <em>operations</em>, each operation representing a simple interaction between the client and the service. Each operation specifies the types of messages that the service can send or receive as part of that operation. Each operation also specifies a message exchange <em>pattern</em> that indicates the sequence in which the associated messages are to be transmitted between the parties. For example, the <em>in-out</em> pattern (see <em>WSDL 2.0 Predefined Extensions</em> [<cite><a href="#WSDL-PART2">WSDL 2.0Adjuncts</a></cite>] section 2.2.3 <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">In-Out</a>) indicates that if the client sends a message <em>in</em> to the service, the service will either send a reply message back <em>out</em> to the client (in the normal case) or it will send a fault message back to the client (in the case of an error).</p><p>For the GreatH service, we will (initially) define an interface containing a single operation, <code>opCheckAvailability</code>, using the <code>checkAvailability</code> and <code>checkAvailabilityResponse</code> message types that we defined in the <code>types</code> section. We'll use the <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</a> pattern for this operation, because this is the most natural way to represent a simple request-response interaction. We could have instead (for example) defined two separate operations using the <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-ut">in-only</a> and <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#out-only">out-only</a> patterns (see <em>WSDL 2.0 Predefined Extensions</em> [<cite><a href="#WSDL-PART2">WSDL 2.0 Adjuncts</a></cite>] section 2.2.1 <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-only">In-Only</a> and section 2.2.5 <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#out-only">Out-Only</a>), but that would just complicate matters for the client, because we would then have to separately indicate to the client developer that the two operations should be used together as a request-response pair.</p><p>In addition to the normal input and output messages, we also need to specify the fault message that we wish to use in the event of an error. WSDL 2.0 permits fault messages to be declared within the <code>interface</code> element in order to facilitate reuse of faults across operations. If a fault occurs, it terminates whatever message sequence was indicated by the messag exchange pattern of the operation. </p><p>Let's add these to our WSDL document.</p><div class="exampleOuter">
<p class="exampleHead" style="text-align: left"><a name="example-initial-interface"></a><i><span>Example 2-4. </span>GreatH Interface Definition</i></p>
***************
*** 292,300 ****
</description></pre></div></div><div class="div3">
<h4><a name="example-initial-interface-explanation"></a>2.4.1 Explanation of Example</h4><dl><dt class="label"><code><interface name = "reservationInterface" ></code></dt><dd><p>Interfaces are declared directly inside the <code>description</code> element. In this example, we are declaring only one interface, but in general a WSDL document may declare more than one interface (each one for use with a different service). Thus, each interface must be given a name that is unique within the set of interfaces defined in this WSDL target namespace. Interface names are tokens that must not contain a space or colon (":").</p></dd><dt class="label"><code><fault name = "invalidDataFault"
! </code></dt><dd><p>The <code>name</code> attribute defines a name for this fault. The name is required so that when an operation is defined, it can reference the desired fault by name. Fault names must unique within an interface.</p></dd><dt class="label"><code>element = "ghns:invalidDataError"/></code></dt><dd><p>The <code>element</code> attribute specifies the schema type of the fault message, as previously defined in the <code>types</code> section. </p></dd><dt class="label"><code><operation name="opCheckAvailability"</code></dt><dd><p>The <code>name</code> attribute defines a name for this operation, so that it can be referenced later when bindings are defined. Operation names must also be unique within an interface. (WSDL 2.0 uses separate symbol spaces for operation and fault names, so operation name "foo" is distinct from fault name "foo".)</p></dd><dt class="label"><code>pattern="http://www.w3.org/2004/03/wsdl/in-out" ></code></dt><dd><p>This line specifies that this opeation will use the <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</a> pattern as described above. WSDL 2.0 uses URIs to identify message exchange patterns in order to ensure that they are uambiguously identified, while also permitting future new patterns to be defined by anyone. (However, just because someone defines a new pattern and creates a URI to identify it, that does <em>not</em> mean that other WSDL processors will automatically recognize or understand that pattern. As with any other extension, it can be used among processors that do recognize and understand it.)</p></dd><dt class="label"><code><input messageLabel="In"</code></dt><dd><p>The <code>input</code> element specifies an input message. Even though we have already specified which message exchange pattern the operation will use, a message exchange pattern represents a template for a message sequence, and in general it may consist of multiple input and/or output messages. Thus we must also indicate whih potential input message in the pattern this particular input message represents. This is the purpose of the <code>messageLabel</code> attribute. Since the <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</a> pattern that we've chosen to use only has one input message, it is trivial in this case: we simply fill in the message label "In" that was defined in <em>WSDL 2.0 Predefined Extensions</em> [<cite><a href="#WSDL-PART2">WSDL 2.0 Predefined Extensions</a></cite>] section 2.2.3 <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">In-Out</a> for the <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</a> pattern. However, in theory, new patterns could be defined that involve multiple input messages, and the different input messages in the pattern would be distinguished by having different labels.</p></dd><dt class="label"><code>element="ghns:checkAvailability" /></code></dt><dd><p>This specifies the message type for his input message, as defined previously in the <code>types</code> section.</p></dd><dt class="label"><code><output messageLabel="Out" . . .</code></dt><dd><p>This is similar to defining an input message.</p></dd><dt class="label"><code><outfault ref="tns:invalidDataFault" messageLabel="Out"/></code></dt><dd><p>This associates an output fault with this operation. Faults are declared a little differently than normal messages. The <code>ref</code> attribute refers to the name of a previously defined fault in this interface -- not a message schema type directly. Since message exchange patterns could in general involve a sequence of several messages, a fault could potentially occur at various points within the message sequence. Because one may wish to associate a different fault with each permitted point in the sequence, the messageLabel is used to indicate the desired point for this particular fault. It does so indirectly by specifying the message that will either trigger this fault or that this fult will replace, depending on the pattern. (Some patterns use a <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-trigger">message-triggers-fault rule</a>; others use a <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-replacement">fault-replaces-message</a> rule. See <em>WSDL 2.0 Predefined Extensions</em> [<cite><a href="#WSDL-PART2">WSDL 2.0 Predefined Extensions</a></cite>] section 2.1.2 <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-trigger">Message Triggers Fault</a> and section 2.1.1 <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-replacement">Fault Replaces Message</a>.) </p></dd></dl><p>Now that we've defined the abstract interface for the GreatH service, we're ready to define a binding for it.</p><table border="1" summary="Editorial note: dbooth"><tr><td width="50%" valign="top" align="left"><b>Editorial note: dbooth</b></td><td width="50%" valign="top" align="right"> </td></tr><tr><td valign="top align="left" colspan="2">[This note is only relevant to the editors.] Hmm, I just realized that in the source XML for this primer, in some cases we've been using <el> to indicate an element name, and in other cases we've been using <code>. At present, the xmlspec XSLT script seems to translate them both into <code> elements in the generated HTML, but we should probably make them consistent, in case that changes. </td></tr></table></div></div>
<div class="div2">
! <h3><a name="basics-binding"></a>2.5 Defining a Binding</h3><p>Although we have specified <em>what</em> abstract messages can be exchanged with the GreatH Web service, we have not yet specified <em>how</em> those messages can be exchanged. This is the purpose of a <em>binding</em>. A binding specifies concrete message format and transmission protocol details for an interface, and must supply such details for every operation and fault in the interface. </p><p>In the general case, binding details for each operation and fault are specified using <code>operation</code> and <code>fault</code> elements inside a <code>binding</code> element, as shown in the example below. However, in some cases it is possible to use defaulting rules to supply the information. The WSDL 2.0 SOAP binding, for example, defines some defaulting rules for operations. (See <em>Web Services Description Language (WSDL) Version 2.0 Part 3: Bindings</em> [<cite><a href="#WSDL-PART3">WSDL 2.0 Bindings</a></cite>], section 2.3 <a href"http://www.w3.org/TR/2004/WD-wsdl20-bindings-20040803/#soap-defaults">Default Binding Rules</a>.) </p><p>In order to accommodate new kinds of message formats and transmission protocols, bindings are defined using extensions to the WSDL 2.0 language, via WSDL 2.0's open content model. WSDL 2.0 Part 3 defines binding constructs for SOAP 1.2 [<cite><a href="#SOAP12-PART1">SOAP 1.2 Part 1: Messaging Framework</a></cite>] and HTTP 1.1 [<cite><a href="#RFC2616">IETF RFC 2616</a></cite>] as predefined extensions, so that SOAP 1.2 or HTTP 1.1 bindings can be easily defined in WSDL documents. However, other specifications could define new binding constructs that could also be used to define bindings. (As with any extension, other WSDL processors would have to know about the new constructs in order to make use of them.) </p><p>For the GreatH service, we will use SOAP 1.2 as our concrete message format and HTTP as our underlying transmission protocol, as shown below. </p><div class="exampleOuter">
<p class="exampleHead" style="text-align: left"><a name="example-initial-binding"></a><i><span>Example 2-5. </span>GreatH Binding Definition</i></p>
<div class="exampleInner"><pre><?xml version="1.0" encoding="utf-8" ?>
--- 322,367 ----
</description></pre></div></div><div class="div3">
<h4><a name="example-initial-interface-explanation"></a>2.4.1 Explanation of Example</h4><dl><dt class="label"><code><interface name = "reservationInterface" ></code></dt><dd><p>Interfaces are declared directly inside the <code>description</code> element. In this example, we are declaring only one interface, but in general a WSDL document may declare more than one interface (each one for use with a different service). Thus, each interface must be given a name that is unique within the set of interfaces defined in this WSDL target namespace. Interface names are tokens that must not contain a space or colon (":").</p></dd><dt class="label"><code><fault name = "invalidDataFault"
! </code></dt><dd><p>The <code>name</code> attribute defines a name for this fault. The name is required so that when an operation is defined, it can reference the desired fault by name. Fault names must unique within an interface.</p></dd><dt class="label"><code>element = "ghns:invalidDataError"/></code></dt><dd><p>The <code>element</code> attribute specifies the schema type of the fault message, as previously defined in the <code>types</code> section. </p></dd><dt class="label"><code><operation name="opCheckAvailability"</code></dt><dd><p>The <code>name</code> attribute defines a name for this operation, so that it can be referenced later when bindings are defined. Operation names must also be unique within an interface. (WSDL 2.0 uses separate symbol spaces for operation and fault names, so operation name "foo" is distinct from fault name "foo".)</p></dd><dt class="label"><code>pattern="http://www.w3.org/2004/03/wsdl/in-out" ></code></dt><dd><p>This line specifies that this opeation will use the <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</a> pattern as described above. WSDL 2.0 uses URIs to identify message exchange patterns in order to ensure that they are uambiguously identified, while also permitting future new patterns to be defined by anyone. (However, just because someone defines a new pattern and creates a URI to identify it, that does <em>not</em> mean that other WSDL processors will automatically recognize or understand that pattern. As with any other extension, it can be used among processors that do recognize and understand it.)</p></dd><dt class="label"><code><input messageLabel="In"</code></dt><dd><p>The <code>input</code> element specifies an input message. Even though we have already specified which message exchange pattern the operation will use, a message exchange pattern represents a template for a message sequence, and in general it may consist of multiple input and/or output messages. Thus we must also indicate whih potential input message in the pattern this particular input message represents. This is the purpose of the <code>messageLabel</code> attribute. Since the <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</a> pattern that we've chosen to use only has one input message, it is trivial in this case: we simply fill in the message label "In" that was defined in <em>WSDL 2.0 Predefined Extensions</em> [<cite><a href="#WSDL-PART2">WSDL 2.0 Adjuncts</a></cite>] section 2.2.3 <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">In-Out</a> for the <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</a> pattern. However, in theory, new patterns could be defined that involve multiple input messages, and the different input messages in the pattern would be distinguished by having different labels.</p></dd><dt class="label"><code>element="ghns:checkAvailability" /></code></dt><dd><p>This specifies the message type for this input mesage, as defined previously in the <code>types</code> section.</p></dd><dt class="label"><code><output messageLabel="Out" . . .</code></dt><dd><p>This is similar to defining an input message.</p></dd><dt class="label"><code><outfault ref="tns:invalidDataFault" messageLabel="Out"/></code></dt><dd><p>This associates an output fault with this operation. Faults are declared a little differently than normal messages. The <code>ref</code> attribute refers to the name of a previously defined fault in this interface -- not a message schema type directly. Since message exchange patterns could in general involve a sequence of several messages, a fault could potentially occur at various points within the message sequence. Because one may wish to associate a different fault with each permitted point in the sequence, the messageLabel is used to indicate the desired point for this particular fault. It does so indirectly by specifying the message that will either trigger this fault or that this fault will repace, depending on the pattern. (Some patterns use a <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-trigger">message-triggers-fault rule</a>; others use a <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-replacement">fault-replaces-message</a> rule. See <em>WSDL 2.0 Predefined Extensions</em> [<cite><a href="#WSDL-PART2">WSDL 2.0 Adjuncts</a></cite>] section 2.1.2 <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-trigger">Message Triggers Fault</a> and section 2.1.1 <a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-replacement">Fault Replaces Message</a>.) </p></dd></dl><p>Now that we've defined the abstract interface for the GreatH service, we're ready to define a binding for it.</p><table border="1" summary="Editorial note: dbooth"><tr><td width="50%" valign="top" align="left"><b>Editorial note: dbooth</b></td><td width="50%" valign="top" align="right"> </td></tr><tr><td valign="top" align="left" colspan="2"[This note is only relevant to the editors.] Hmm, I just realized that in the source XML for this primer, in some cases we've been using <el> to indicate an element name, and in other cases we've been using <code>. At present, the xmlspec XSLT script seems to translate them both into <code> elements in the generated HTML, but we should probably make them consistent, in case that changes. </td></tr></table></div></div>
<div class="div2">
! <h3><a name="basics-binding"></a>2.5 Defining a Binding</h3>
! <p>
! Although we have specified
! <em>what</em>
! abstract messages can be exchanged with the GreatH Web
! service, we have not yet specified
! <em>how</em>
! those messages can be exchanged. This is the purpose of
! a
! <em>binding</em>. A binding specifies concrete message format and
! transmission protocol details for an interface, and must
! supply such details for every operation and fault in the
! interface.
! </p>
! <p>
! In the general case, binding details for each operation
! and fault are specified using
! <code>operation</code>
! and
! <code>fault</code>
! elements inside a
! <code>binding</code>
! element, as shown in the example below. However, in some
! cases it is possible to use defaulting rules to supply
! the information. The WSDL 2.0 SOAP binding, for example,
! defines some defaulting rules for operations. (See
! <em>
! Web Services Description Language (WSDL) Version 2.0
! Part 2: Adjuncts
! </em>
! [<cite><a href="#WSDL-PART2">WSDL 2.0 Adjuncts</a></cite>]
! , section 4.3
! <a href="http://www.w3.org/TR/2004/WD-wsdl20-adjuncts/#soap-defaults">
! Default Binding Rules
! </a>
! .)
! </p>
! <p>In order to accommodate new kinds of message formats and transmission protocols, bindings are defined using extensions to the WSDL 2.0 language, via WSDL 2.0's open content model. WSDL 2.0 Part 3 defines binding constructs for SOAP 1.2 [<cite><a href="#SOAP12-PART1">SOAP 1.2 Part 1: Messaging Framework</a></cite>] and HTTP 1.1 [<cite><a href="#RFC2616">IETF RFC 2616</a></cite>] as predefined extensions, so that SOAP 1.2 or HTTP 1.1 bindings can be easily defined in WSDL documents. However, other specifications could define new binding constructs that could also be used to define bindings. (As with any extension, other WSDL processors would have to know about the new constructs in order to make use of them.) </p><p>For the GreatH service, we will use SOAP 1.2 as our concrete message format and HTTP as our underlying transmission protocol, as shown below. </p><div class="exampleOuter">
<p class="exampleHead" style="text-align: left"><a name="example-initial-binding"></a><i><span>Example 2-5. </span>GreatH Binding Definition</i></p>
<div class="exampleInner"><pre><?xml version="1.0" encoding="utf-8" ?>
***************
*** 340,344 ****
</description></pre></div>
</div><div class="div3">
! <h4><a name="example-initial-binding-explanation"></a>2.5.1 Explanation of Example</h4><dl><dt class="label"><code>xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"</code></dt><dd><p>We've added two more namespace declarations. This one is the namespace for the SOAP 1.2 binding construct that is defined in WSDL 2.0 Part 3 [<cite><a href="#SOAP12-PART1">SOAP 1.2 Part 1: Messaging Framework</a></cite>]. Elements and attributes prefixed with <code>wsoap:</code> are constructs defined there. </p></dd><dt class="label"><code>xmlns:soap="http://www.w3.org/2003/05/soap-envelope"</code></dt><dd><p>This namespace is defined by the SOAP 1.2 specification itself. The SOAP 1.2 specification defines certain terms within this namespace to unambiguously identify particular concepts. Thus, we will use the <code>soap:</code> prefix when we need to refer to one of those terms.</p></dd><dt class="label"><code><binding name="reservationSOAPBinding"</code></dt><dd><p>Bindings are declared directly inside the <coe>description</code> element. The <code>name</code> attribute defines a name for this binding. Each name must be unique among all bindings in this WSDL target namespace, and will be used later when we define a service endpoint that references this binding. WSDL 2.0 uses separate symbol spaces for interfaces, bindings and services, so interface "foo", binding "foo" and service "foo" are all distinct. </p></dd><dt class="label"><code>interface="tns:reservationInterface"</code></dt><dd><p>This is the name of the interface whose message format and transmission protocols we are specifying. As discussed in <a href="#more-bindings"><b>4.3 More on Bindings</b></a>, a reusable binding can be defined by omitting the <code>interface</code> attribute. Note also the use of the <code>tns:</code> prefix, which refers to the previously defined WSDL target namespace for this WSDL document. In this case it may seem silly to have to specify the <code>tns:</code> prefix, but in <a href="#adv-import-and-authoring"><b>53 Import mechanism and authoring style</b></a>we will see how WSDL 2.0's import mechanism can be used to combine components that are defined in different WSDL target namespaces.</p></dd><dt class="label"><code>type="http://www.w3.org/2004/08/wsdl/soap12"</code></dt><dd><p>This specifies the type of concrete message format to use, in this case SOAP 1.2.</p></dd><dt class="label"><code>wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP"</code></dt><dd><p>This attribute is specific to WSDL 2.0's SOAP binding (thus it uses the <code>wsoap:</code> prefix). It specifies the underlying transmission protocol that should be used, in this case HTTP. </p></dd><dt class="label"><code><operation ref="tns:opCheckAvailability"</code></dt><dd><p>This not defining a new operation. Rather, it is referencing the previously defined <code>opCheckAvailability</code> operation in order to specify binding details for it. This element can be omitted if defaulting rules are instead used to supply the necessary infomation. (See the SOAP binding in <em>WSDL 2.0 Bindings</em> [<cite><a href="#WSDL-PART3">WSDL 2.0 Bindings</a></cite>] section 2.3 <a href="http://www.w3.org/TR/2004/WD-wsdl20-bindings-20040803/#soap-defaults">Default Binding Rules</a>.)</p></dd><dt class="label"><code>wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response"></code></dt><dd><p>This attribute is also specific to WSDL 2.0's SOAP binding. It specifies the SOAP message exchange pattern that will be used to implement the abstract WSDL 2.0 message exchange pattern (<a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</a>) that was specified when the <code>opCheckAvailability</code> operation was defined. </p></dd><dt class="label"><code><fault ref="tns:invalidDataFault"</code></dt><dd><p>As with a binding operation, this is not declaring a new fault. Rather, it is referencing a fault (<code>invalidDataFault</code>) that was previously defined in the <code>opCheckAvailability</code> interface, in ordr to specify binding details for it.</p></dd><dt class="label"><code>wsoap:code="soap:Sender"/></code></dt><dd><p>This attribute is also specific to WSDL 2.0's SOAP binding. This specifies the SOAP 1.2 fault code that will cause this fault message to be sent. If desired, an list of subcodes can also be specified using the optional <code>wsoap:subcodes</code> attribute.</p></dd></dl></div></div><div class="div2">
<h3><a name="basics-service"></a>2.6 Defining a Service</h3><p>Now that our binding has specified <em>how</em> messages will be transmitted, we are ready to specify <em>where</em> the service can be accessed, by use of the <code>service</code> element. </p><p>A WSDL 2.0 <em>service</em> specifies a single interface that the service will support, and a list of <em>endpoint</em> locations where that service can be accessed. Each endpoint must also reference a previously defined binding in order to indicate the binding details that are to be used at that endpoint. A service is only permitted to have one interface. (However, WSDL 2.0 does not prohibit one from declaring multiple services that use different interfaces but happen to use the same endpoint address. See <a href="#adv-multiple-docs-describing-same-service"><b>5.4 Multiple Logical WSDL Documents Describing the Same Service</b></a>.) </p><p>Here is a definition for our GreatH service.</p><div class="exampleOuter">
<p class="exampleHead" style="text-align: left"><a name="example-initial-service"></a><i><span>Example 2-6. </span>GreatH Service Definition</i></p>
--- 407,426 ----
</description></pre></div>
</div><div class="div3">
! <h4><a name="example-initial-binding-explanation"></a>2.5.1 Explanation of Example</h4><dl><dt class="label"><code>xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"</code></dt><dd><p>We've added two more namespace declarations. This one is the namespace for the SOAP 1.2 binding construct that is defined in WSDL 2.0 Part 3 [<cite><a href="#SOAP12-PART1">SOAP 1.2 Part 1: Messaging Framework</a></cite>]. Elements and attributes prefixed with <code>wsoap:</code> are constructs defined there. </p></dd><dt class="label"><code>xmlns:soap="http://www.w3.org/2003/05/soap-envelope"</code></dt><dd><p>This namespace is defined by the SOAP 1.2 specification itself. The SOAP 1.2 specification defines certain terms within this namespace to unambiguously identify particular concepts. Thus, we will use the <code>soap:</code> prefix when we need to refer to one of those terms.</p></dd><dt class="label"><code><binding name="reservationSOAPBinding"</code></dt><dd><p>Bindings are declared directly inside the <coe>description</code> element. The <code>name</code> attribute defines a name for this binding. Each name must be unique among all bindings in this WSDL target namespace, and will be used later when we define a service endpoint that references this binding. WSDL 2.0 uses separate symbol spaces for interfaces, bindings and services, so interface "foo", binding "foo" and service "foo" are all distinct. </p></dd><dt class="label"><code>interface="tns:reservationInterface"</code></dt><dd><p>This is the name of the interface whose message format and transmission protocols we are specifying. As discussed in <a href="#more-bindings"><b>4.3 More on Bindings</b></a>, a reusable binding can be defined by omitting the <code>interface</code> attribute. Note also the use of the <code>tns:</code> prefix, which refers to the previously defined WSDL target namespace for this WSDL document. In this case it may seem silly to have to specify the <code>tns:</code> prefix, but in <a href="#adv-import-and-authoring"><b>53 Import mechanism and authoring style</b></a>we will see how WSDL 2.0's import mechanism can be used to combine components that are defined in different WSDL target namespaces.</p></dd><dt class="label"><code>type="http://www.w3.org/2004/08/wsdl/soap12"</code></dt><dd><p>This specifies the type of concrete message format to use, in this case SOAP 1.2.</p></dd><dt class="label"><code>wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP"</code></dt><dd><p>This attribute is specific to WSDL 2.0's SOAP binding (thus it uses the <code>wsoap:</code> prefix). It specifies the underlying transmission protocol that should be used, in this case HTTP. </p></dd><dt class="label"><code><operation ref="tns:opCheckAvailability"</code></dt><dd>
! <p>
! This not defining a new operation. Rather, it is referencing the
! previously defined
! <code>opCheckAvailability</code>
! operation in order to specify binding details for it. This
! element can be omitted if defaulting rules are instead used to
! supply the necessary information. (See the SOAP binding in
! <em>WSDL 2.0 Bindings</em>
! [<cite><a href="#WSDL-PART2">WSDL 2.0 Adjuncts</a></cite>]
! section 4.3
! <a href="http://www.w3.org/TR/2004/WD-wsdl20-adjuncts/#soap-defaults">
! Default Binding Rules
! </a>.)
! </p>
! </dd><dt class="label"><code>wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response"></code></dt><dd><p>This attribute is also specific to WSDL 2.0's SOAP binding. It specifies the SOAP message exchange pattern that will be used to implement the abstract WSDL 2.0 message exchange pattern (<a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</a>) that was specified when the <code>opCheckAvailability</code> operation was defined. </p></dd><dt class="label"><code><fault ref="tns:invalidDataFault"</code></dt><dd><p>As with a binding operation, this is not declaring a new fault. Rather, it is referencing a fault (<code>invalidDataFault</code>) that was previously defined in the <code>opCheckAvailability</code> interface, in order to specify binding details for it.</p></dd><dt class="label"><code>wsoap:code="soap:Sender"/></code></dt><dd><p>This attribute is also specific to WSDL 2.0's SOAP binding. This specifies the SOAP 1.2 fault code that will cause ths fault message to be sent. If desired, an list of subcodes can also be specified using the optional <code>wsoap:subcodes</code> attribute.</p></dd></dl></div></div><div class="div2">
<h3><a name="basics-service"></a>2.6 Defining a Service</h3><p>Now that our binding has specified <em>how</em> messages will be transmitted, we are ready to specify <em>where</em> the service can be accessed, by use of the <code>service</code> element. </p><p>A WSDL 2.0 <em>service</em> specifies a single interface that the service will support, and a list of <em>endpoint</em> locations where that service can be accessed. Each endpoint must also reference a previously defined binding in order to indicate the binding details that are to be used at that endpoint. A service is only permitted to have one interface. (However, WSDL 2.0 does not prohibit one from declaring multiple services that use different interfaces but happen to use the same endpoint address. See <a href="#adv-multiple-docs-describing-same-service"><b>5.4 Multiple Logical WSDL Documents Describing the Same Service</b></a>.) </p><p>Here is a definition for our GreatH service.</p><div class="exampleOuter">
<p class="exampleHead" style="text-align: left"><a name="example-initial-service"></a><i><span>Example 2-6. </span>GreatH Service Definition</i></p>
***************
*** 1025,1029 ****
interface. The bindings may occur via defaulting rules
which allow one to specify default bindings for all operations
! (for example, see the SOAP binding in <em>WSDL 2.0 Bindings</em> [<cite><a href="#WSDL-PART3">WSDL 2.0 Bindings</a></cite>] section 2.3 <a href="http://www.w3.org/TR/2004/WD-wsdl20-bindings-20040803/#soap-defaults">Default Binding Rules</a>) or by directly
listing each operation of the interface and
defining bindings for them. Thus, it is an error for a binding to not define bindings for all the operations of the corresponding interface.</p>
--- 1107,1114 ----
interface. The bindings may occur via defaulting rules
which allow one to specify default bindings for all operations
! (for example, see the SOAP binding in <em>WSDL 2.0 Bindings</em>
! [<cite><a href="#WSDL-PART2">WSDL 2.0 Adjuncts</a></cite>]
! section 4.3
! <a href="http://www.w3.org/TR/2004/WD-wsdl20-adjuncts/#soap-defaults">Default Binding Rules</a>) or by directly
listing each operation of the interface and
defining bindings for them. Thus, it is an error for a binding to not define bindings for all the operations of the corresponding interface.</p>
***************
*** 1199,1204 ****
<ul>
! <li> /description/binding[@name="reservationSOAP11Binding"]</li>
! <li> /description/service/endpoint[@name="reservationEndpoint2"]</li>
</ul>
--- 1284,1289 ----
<ul>
! <li><p>/description/binding[@name="reservationSOAP11Binding"]</p></li>
! <li><p>/description/service/endpoint[@name="reservationEndpoint2"]</p></li>
</ul>
***************
*** 1360,1366 ****
<p>
! This example defines an interface, <em xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:z="http://www.w3.org/2004/zml">creditCardFaults</em>, that contains four faults, <em xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:z="http://www.w3.org/2004/zml">cancelledCreditCard</em>,
! <em xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:z="http://www.w3.org/2004/zml">expiredCreditCard</em>, <em xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:z="http://www.w3.org/2004/zml">invalidCreditCardNumber</em>, and <em xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:z="http://www.w3.org/2004/zml">invalidExpirationDate</em>.
! These components belong to the namespace <em xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:z="http://www.w3.org/2004/zml">http://finance.example.com/CreditCards/wsdl</em>.
The faults are reused in the following hotel reservation service:
</p>
--- 1445,1451 ----
<p>
! This example defines an interface, <code>creditCardFaults</code>, that contains four faults, <code>cancelledCreditCard</code>,
! <code>expiredCreditCard</code>, <code>invalidCreditCardNumber</code>, and <code>invalidExpirationDate</code>.
! These components belong to the namespace <code>http://finance.example.com/CreditCards/wsdl</code>.
The faults are reused in the following hotel reservation service:
</p>
***************
*** 1409,1420 ****
<p>
! The hotel reservation service declares that it is using components from another namespace via the <em xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:z="http://www.w3.org/2004/zml">import</em> element.
! The import element has a required <em xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:z="http://www.w3.org/2004/zml">namespace</em> attribute that specifies the other namespace, and an optional <em xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:z="http://www.w3.org/2004/zml">location</em> attribute
! that gives the processor a hint where to find the description of the other namespace.
! The <em xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:z="http://www.w3.org/2004/zml">reservation</em> interface extends the <em xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:z="http://www.w3.org/2004/zml">creditCardFault</em> interface from the other namespace in order to make the faults available
! in the reservation interface.
! Finally, the <em xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:z="http://www.w3.org/2004/zml">makeReservation</em> operation refers to the standard faults in its <em xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:z="http://www.w3.org/2004/zml">outfault</em> elements.
</p>
!
<p>
Another typical situation for using imports is to define a standard interface that is to be implemented
--- 1494,1519 ----
<p>
! The hotel reservation service declares that it is using
! components from another namespace via the
! <code>import</code>>
! element. The import element has a required
! <code>namespace</code>
! attribute that specifies the other namespace, and an
! optional
! <code>location</code>
! attribute that gives the processor a hint where to find
! the description of the other namespace. The
! <code>reservation</code>
! interface extends the
! <code>creditCardFault</code>
! interface from the other namespace in order to make the
! faults available in the reservation interface. Finally,
! the
! <code>makeReservation</code>
! operation refers to the standard faults in its
! <code>outfault</code>
! elements.
</p>
!
<p>
Another typical situation for using imports is to define a standard interface that is to be implemented
***************
*** 1445,1449 ****
</td></tr></table>
! <p>This section shows how the [<cite><a href="#">xxx</a></cite>] SOAP Message Transmission Optimization Mechanism may be engaged in the WSDL 2.0 SOAP binding.</p>
<p>Let’s modify the CheckAvailability operation of the GreatH Hotel Reservation Service [ref] to return not only the room rate, but images of the room and the floorplan. We’ll modify the checkAvailabilityResponse data structure to include binary data representing these two images, indicated by xs:base64Binary data type:</p>
--- 1544,1548 ----
</td></tr></table>
! <p>This section shows how the [<cite><a href="#SOAP-MTOM">SOAP MTOM</a></cite>] SOAP Message Transmission Optimization Mechanism may be engaged in the WSDL 2.0 SOAP binding.</p>
<p>Let’s modify the CheckAvailability operation of the GreatH Hotel Reservation Service [ref] to return not only the room rate, but images of the room and the floorplan. We’ll modify the checkAvailabilityResponse data structure to include binary data representing these two images, indicated by xs:base64Binary data type:</p>
***************
*** 1599,1607 ****
--- 1698,2218 ----
<p>[Add material from http://lists.w3.org/Archives/Public/www-ws-desc/2003Mar/0068.html that prescribes when to use GET versus POST as well as some useful example]</p>
</div>
+
<div class="div2">
<h3><a name="adv-service-references"></a>5.11 Service References</h3>
+ <table border="1" summary="Editorial note: Arthur"><tr><td width="50%" valign="top" align="left"><b>Editorial note: Arthur</b></td><td width="50%" valign="top" align="right">20050326</td></tr><tr><td valign="top" align="left" colspan="2">
+ This is the first draft. Please review.
+ The source for all the examples is in the test suite.
+ See <a href="http://dev.w3.org/cvsweb/2002/ws/desc/test-suite/documents/good/ServiceReference-1G/">ServiceReference-1G</a>.
+ </td></tr></table>
<p>[Use http://lists.w3.org/Archives/Public/www-ws-desc/2003Oct/0345.html as a starting point. Also example(s) from Roberto per the resolution at the end of http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0061.html ]</p>
+
+ <p>
+ Hyperlinking is one of the defining characteristics
+ of the Web. The ability to navigate from one Web
+ page to another is extremely useful. It is therefore
+ natural to apply this capability to Web services.
+ This section describes
+ <em>service references</em>
+ which are the Web service analogs of document
+ hyperlinks.
+ </p>
+
+ <div class="div3">
+ <h4><a name="reservationDetails"></a>5.11.1 The Reservation Details Web Service</h4>
+
+ <p>
+ When designing a Web application it is natural to
+ give each important concept a URI. In the hotel
+ reservation system, the important concepts are
+ reservations, so we begin our design by assigning a
+ URI to each reservation. Since each reservation has
+ a unique confirmation number, e.g OMX736, we create
+ a URI for each reservation by appending the
+ confirmation number to a base URI, e.g.
+ http://greath.example.com/2004/reservation/OMX736.
+ This URI will be the endpoint address for a
+ Reservation Detail Web service that can retrieve and
+ update the state of a reservation.
+ <a href="#reservationDetails-OMX736.xml">Example 5-6</a>
+ shows the format of the reservation detail.
+ </p>
+
+ <div class="exampleOuter">
+ <p class="exampleHead" style="text-align: left"><a name="reservationDetails-OMX736.xml"></a><i><span>Example 5-6. </span>Detail for Reservation OMX736</i></p>
+ <div class="exampleInner"><pre><?xml version="1.0" encoding="UTF-8"?>
+ <reservationDetails
+ xmlns="http://greath.example.com/2004/schemas/reservationDetails">
+
+ <confirmationNumber>OMX736</confirmationNumber>
+ <checkInDate>2005-06-01</checkInDate>
+ <checkOutDate>2005-06-03</checkOutDate>
+ <roomType>single</roomType>
+ <smoking>false</smoking>
+
+ </reservationDetails></pre></div>
+ </div>
+
+ <p>
+ The Reservation Details Web service provides operations for retrieving and updating the detail for a reservation.
+ <a href="#reservationDetails.wsdl">Example 5-7</a> shows the description for this Web service.
+ Note that there is no <code>wsdl:service</code> element in this description since the set of reservations is dynamic.
+ Instead, the endpoints for the reservations will be returned by querying the Reservation List Web service.
+ </p>
+
+ <div class="exampleOuter">
+ <p class="exampleHead" style="text-align: left"><a name="reservationDetails.wsdl"></a><i><span>Example 5-7. </span>The Reservation Details Web Service Description: reservationDetails.wsdl</i></p>
+ <div class="exampleInner"><pre><?xml version="1.0" encoding="utf-8" ?>
+ <description xmlns="http://www.w3.org/2004/08/wsdl"
+ targetNamespace="http://greath.example.com/2004/services/reservationDetails"
+ xmlns:tns="http://greath.example.com/2004/services/reservationDetails"
+ xmlns:wdetails="http://greath.example.com/2004/schemas/reservationDetails"
+ xmlns:wsoap="http://www.w3.org/2004/08/wsdl/soap12"
+ xmlns:xs="http://www.w3.org/2001/XMLSchema">
+
+ <documentation>
+ This document describes the GreatH Reservation Details Web
+ services. Use these services to retrieve or update reservation
+ details. Each reservation has its own service and endpoint. To
+ obtain the serice reference for a reservation, make a request to
+ the GreatH Reservation List Web service. See
+ reservationList.wsdl for a description of the Reservation List
+ Web service.
+ </documentation>
+
+ <types>
+ <xs:import
+ namespace="http://greath.example.com/2004/schemas/reservationDetails"
+ schemaLocation="reservationDetails.xsd" />
+ </types>
+
+ <interface name="reservationDetailsInterface">
+
+ <operation name="retrieve"
+ pattern="http://www.w3.org/2004/03/wsdl/in-out">
+ <input messageLabel="In" element="#none" />
+ <output messageLabel="Out"
+ element="wdetails:reservationDetails" />
+ </operation>
+
+ <operation name="update"
+ pattern="http://www.w3.org/2004/03/wsdl/in-out">
+ <input messageLabel="In"
+ element="wdetails:reservationDetails" />
+ <output messageLabel="Out"
+ element="wdetails:reservationDetails" />
+ </operation>
+
+ </interface>
+
+ <binding name="reservationDetailsSOAPBinding"
+ interface="tns:reservationDetailsInterface"
+ type="http://www.w3.org/2004/08/wsdl/soap12"
+ wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP">
+
+ <operation ref="tns:retrieve"
+ wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response" />
+
+ <operation ref="tns:update"
+ wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response" />
+
+ </binding>
+
+ </description>
+
+ </pre></div></div>
+
+ <p>
+ <a href="#reservationDetails.xsd">Example 5-8</a> shows the XML schema elements that are used in this Web service.
+ </p>
+
+ <div class="exampleOuter">
+ <p class="exampleHead" style="text-align: left"><a name="reservationDetails.xsd"></a><i><span>Example 5-8. </span>
+ The Reservation Details Web Service XML Schema:
+ reservationDetails.xsd
+ </i></p>
+ <div class="exampleInner"><pre><?xml version="1.0" encoding="UTF-8"?>
+ <schema xmlns="http://www.w3.org/2001/XMLSchema"
+ elementFormDefault="qualified"
+ targetNamespace="http://greath.example.com/2004/schemas/reservationDetails"
+ xmlns:tns="http://greath.example.com/2004/schemas/reservationDetails"
+ xmlns:wdetails="http://greath.example.com/2004/services/reservationDetails"
+ xmlns:wsdl="http://www.w3.org/2004/08/wsdl">
+
+ <import namespace="http://www.w3.org/2004/08/wsdl"
+ schemaLocation="../../../xmlcatalog/wsdl/wsdl20.xsd" />
+
+ <element name="confirmationNumber" type="string" />
+
+ <element name="checkInDate" type="date" />
+
+ <element name="checkOutDate" type="date" />
+
+ <element name="reservationDetails">
+ <complexType>
+ <sequence>
+ <element ref="tns:confirmationNumber" />
+ <element ref="tns:checkInDate" />
+ <element ref="tns:checkOutDate" />
+ <element name="roomType" type="string" />
+ <element name="smoking" type="boolean" />
+ </sequence>
+ </complexType>
+ </element>
+
+ <complexType name="ReservationDetailsEndpointType">
+ <complexContent>
+ <restriction base="wsdl:EndpointType">
+ <attribute name="binding" type="QName" use="required"
+ fixed="wdetails:reservationDetailsSOAPBinding" />
+ </restriction>
+ </complexContent>
+ </complexType>
+
+ <complexType name="ReservationDetailsServiceType">
+ <complexContent>
+ <restriction base="wsdl:ServiceType">
+ <sequence>
+ <element name="endpoint"
+ type="tns:ReservationDetailsEndpointType" />
+ </sequence>
+ <attribute name="interface" type="QName" use="required"
+ fixed="wdetails:reservationDetailsInterface" />
+ </restriction>
+ </complexContent>
+ </complexType>
+
+ <element name="reservationDetailsService"
+ type="tns:ReservationDetailsServiceType">
+ <annotation>
+ <documentation>
+ This element contains a reference to the Reservation
+ Details Web Service for this reservation.
+ </documentation>
+ </annotation>
+ </element>
+
+ </schema>
+ </pre></div>
+ </div>
+
+ <p>
+ This XML schema contains the usual definitions for the elements
+ that appear in the messages of the Web service. For example, the
+ <code>reservationDetails</code>
+ element is used in the messages of the retrieve and update
+ operations. In addition, the schema defines two
+ <em>restrictions</em>
+ of WSDL complex types. The
+ <code>ReservationDetailsEndpointType</code>
+ complex type restricts the
+ <code>wsdl:EndpointType</code>
+ complex type to have a
+ <code>binding</code>
+ attribute whose value is the Reservation Details binding,
+ <code>wdetails:reservationDetailsSOAPBinding</code>.
+ </p>
+
+ <p>
+ The schema also defines the
+ <code>ReservationDetailsServiceType</code>
+ complex type to restrict the
+ <code>wsdl:ServiceType</code>
+ to have an
+ <code>interface</code>
+ attribute whose have is the Reservation Details service
+ interace,
+ <code>wdetails:reservationDetailsInterface</code>
+ . The
+ <code>reservationDetailsService</code>
+ element is thus a restriction of the
+ <code>wsdl:service</code>
+ element that has the interface and binding for the Reservation
+ Details service and whose endpoint address is that of the
+ corresponing reservation. This element is used in the definition
+ of the Reservation List Web service.
+ </p>
+
+ </div>
+
+ <div class="div3">
+
+ <h4><a name="reservationList"></a>5.11.2 The Reservation List Web Service</h4>
+ <p>
+ Since the set of reservations changes as
+ reservations are made and cancelled, the
+ Reservation Detail endpoints are not described
+ in a fixed WSDL document. Instead they are
+ returned as service references in response to
+ requests made on a Reservation List Web service.
+ The endpoint for the Reservation List service
+ will be
+ http://greath.example.com/2004/reservationList.
+ </p>
+
+ <table border="1" summary="Editorial note: Arthur"><tr><td width="50%" valign="top" align="left"><b>Editorial note: Arthur</b></td><td width="50%" valign="top" align="right">20050326</td></tr><tr><td valign="top" align="left" colspan="2">
+ There is a minor problem in this example.
+ For some reason, the Xerces parser thinks
+ that when I restrict the
+ <code>wsdl:ServiceType</code>
+ complex type by constraining the
+ <code>wsdl:endpoint</code>
+ element to have a fixed value for its
+ <code>binding</code>
+ attribute, that the namespace of the
+ <code>wsdl:endpoint</code>
+ element changes to the target namespace of
+ the schema. I assume this is a bug in
+ Xerces. I'd appreciate it if someone could
+ try validating this example with another
+ processor.
+ </td></tr></table>
+ <p>
+ <a href="#reservationList-all.xml">Example 5-9</a>
+ shows the format of the response from the
+ Reservation List service.
+ </p>
+ <div class="exampleOuter">
+ <p class="exampleHead" style="text-align: left"><a name="reservationList-all.xml"></a><i><span>Example 5-9. </span>
+ Response from the Reservation List Web
+ Service
+ </i></p>
+ <div class="exampleInner"><pre>
+ <?xml version="1.0" encoding="UTF-8"?>
+ <reservationList
+ xmlns="http://greath.example.com/2004/schemas/reservationList"
+ xmlns:details="http://greath.example.com/2004/schemas/reservationDetails"
+ xmlns:wsdli="http://www.w3.org/2004/08/wsdl-instance"
+ wsdli:wsdlLocation="http://greath.example.com/2004/services/reservationDetails reservationDetails.wsdl">
+
+ <reservation>
+ <details:confirmationNumber>HSG635</details:confirmationNumber>
+ <details:checkInDate>2005-06-27</details:checkInDate>
+ <details:checkOutDate>2005-06-28</details:checkOutDate>
+ <details:reservationDetailsService
+ interface="wdetails:reservationDetailsInterface">
+ <details:endpoint name="SOAP"
+ binding="wdetails:reservationDetailsSOAPBinding"
+ address="http://greath.example.com/2004/reservation/HSG635"/>
+ </details:reservationDetailsService>
+ </reservation>
+
+ <reservation>
+ <details:confirmationNumber>OMX736</details:confirmationNumber>
+ <details:checkInDate>2005-06-01</details:checkInDate>
+ <details:checkOutDate>2005-06-03</details:checkOutDate>
+ <details:reservationDetailsService
+ interface="wdetails:reservationDetailsInterface">
+ <details:endpoint name="SOAP"
+ binding="wdetails:reservationDetailsSOAPBinding"
+ address="http://greath.example.com/2004/reservation/OMX736"/>
+ </details:reservationDetailsService>
+ </reservation>
+
+ <reservation>
+ <details:confirmationNumber>WUH663</details:confirmationNumber>
+ <details:checkInDate>2005-06-11</details:checkInDate>
+ <details:checkOutDate>2005-06-15</details:checkOutDate>
+ <details:reservationDetailsService
+ interface="wdetails:reservationDetailsInterface">
+ <details:endpoint name="SOAP"
+ binding="wdetails:reservationDetailsSOAPBinding"
+ address="http://greath.example.com/2004/reservation/WUH663"/>
+ </details:reservationDetailsService>
+ </reservation>
+
+ </reservationList>
+ </pre></div>
+ </div>
+
+ <p>
+ Here, the
+ <code>
+ <details:reservationDetailsService>
+ </code>
+ elements contain service references to the
+ Reservation Details Web services for the
+ reservations HSG635, OMX736, and WUH663. The
+ service references given the interface, binding,
+ and endpoint address of each service. In this
+ example, all endpoints have the same interface
+ and binding, i.e.
+ <code>
+ wdetails:reservationDetailsInterface
+ </code>
+ and
+ <code>
+ wdetails:reservationDetailsSOAPBinding
+ </code>
+ . These QNames identify WSLD Interface and
+ Binding components that are defined in a WSDL
+ document. This example shows the use of the
+ <code>wsdli:wsdlLocation</code>
+ attribute to locate the WSDL document. The
+ address of each endpoint is the URI assigned to
+ each reservation.
+ </p>
+
+ <p>
+ <a href="#reservationList.wsdl">Example 5-10</a>
+ shows the description of the Reservation List
+ Web service. Note that is contains operations to
+ retrieve the entire list and to query for a list
+ of reservations by confirmation number, check-in
+ date, and check-out date. In each case, the
+ operation returns a list of reservations.
+ </p>
+
+ <div class="exampleOuter">
+ <p class="exampleHead" style="text-align: left"><a name="reservationList.wsdl"></a><i><span>Example 5-10. </span>
+ The Reservation List Web Service
+ Description: reservationList.wsdl
+ </i></p>
+ <div class="exampleInner"><pre>
+ <?xml version="1.0" encoding="utf-8" ?>
+ <description xmlns="http://www.w3.org/2004/08/wsdl"
+ targetNamespace="http://greath.example.com/2004/services/reservationList"
+ xmlns:tns="http://greath.example.com/2004/services/reservationList"
+ xmlns:details="http://greath.example.com/2004/schemas/reservationDetails"
+ xmlns:list="http://greath.example.com/2004/schemas/reservationList"
+ xmlns:wsoap="http://www.w3.org/2004/08/wsdl/soap12"
+ xmlns:xs="http://www.w3.org/2001/XMLSchema">
+
+ <documentation>
+ This document describes the GreatH Reservation List Web
+ services. Use this service to retrieve lists of reservations
+ based on a variety of search criteria.
+ </documentation>
+
+ <types>
+ <xs:import
+ namespace="http://greath.example.com/2004/schemas/reservationDetails"
+ schemaLocation="reservationDetails.xsd" />
+ <xs:import
+ namespace="http://greath.example.com/2004/schemas/reservationList"
+ schemaLocation="reservationList.xsd" />
+ </types>
+
+ <interface name="reservationListInterface">
+
+ <operation name="retrieve"
+ pattern="http://www.w3.org/2004/03/wsdl/in-out">
+ <input messageLabel="In" element="#none" />
+ <output messageLabel="Out" element="list:reservationList" />
+ </operation>
+
+ <operation name="retrieveByConfirmationNumber"
+ pattern="http://www.w3.org/2004/03/wsdl/in-out">
+ <input messageLabel="In"
+ element="details:confirmationNumber" />
+ <output messageLabel="Out" element="list:reservationList" />
+ </operation>
+
+ <operation name="retrieveByCheckInDate"
+ pattern="http://www.w3.org/2004/03/wsdl/in-out">
+ <input messageLabel="In" element="details:checkInDate" />
+ <output messageLabel="Out" element="list:reservationList" />
+ </operation>
+
+ <operation name="retrieveByCheckOutDate"
+ pattern="http://www.w3.org/2004/03/wsdl/in-out">
+ <input messageLabel="In" element="details:checkOutDate" />
+ <output messageLabel="Out" element="list:reservationList" />
+ </operation>
+
+ </interface>
+
+ <binding name="reservationListSOAPBinding"
+ interface="tns:reservationListInterface"
+ type="http://www.w3.org/2004/08/wsdl/soap12"
+ wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP">
+
+ <operation ref="tns:retrieve"
+ wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response" />
+
+ <operation ref="tns:retrieveByConfirmationNumber"
+ wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response" />
+
+ <operation ref="tns:retrieveByCheckInDate"
+ wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response" />
+
+ <operation ref="tns:retrieveByCheckOutDate"
+ wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response" />
+
+ </binding>
+
+ <service name="reservationListService"
+ interface="tns:reservationListInterface">
+
+ <endpoint name="reservationListEndpoint"
+ binding="tns:reservationListSOAPBinding"
+ address="http://greath.example.com/2004/reservationList" />
+
+ </service>
+
+ </description>
+ </pre></div>
+ </div>
+
+ <p><a href="#reservationList.xsd">Example 5-11</a>Shows the schema for the messages used in the Reservation List Web service.</p>
+ <div class="exampleOuter">
+ <p class="exampleHead" style="text-align: left"><a name="reservationList.xsd"></a><i><span>Example 5-11. </span></i></p>
+ <div class="exampleInner"><pre><?xml version="1.0" encoding="UTF-8"?>
+ <schema xmlns="http://www.w3.org/2001/XMLSchema"
+ elementFormDefault="qualified"
+ targetNamespace="http://greath.example.com/2004/schemas/reservationList"
+ xmlns:tns="http://greath.example.com/2004/schemas/reservationList"
+ xmlns:details="http://greath.example.com/2004/schemas/reservationDetails"
+ xmlns:wsdli="http://www.w3.org/2004/08/wsdl-instance">
+
+ <import namespace="http://www.w3.org/2004/08/wsdl-instance"
+ schemaLocation="../../../xmlcatalog/wsdl/wsdl20-instance.xsd" />
+
+ <import
+ namespace="http://greath.example.com/2004/schemas/reservationDetails"
+ schemaLocation="reservationDetails.xsd" />
+
+ <element name="reservation">
+ <annotation>
+ <documentation>
+ A reservation contains the confirmation number, check-in
+ and check-out dates, and a reference to a Reservation
+ Details Web service.
+ </documentation>
+ </annotation>
+ <complexType>
+ <sequence>
+ <element ref="details:confirmationNumber" />
+ <element ref="details:checkInDate" />
+ <element ref="details:checkOutDate" />
+ <element ref="details:reservationDetailsService" />
+ </sequence>
+ </complexType>
+ </element>
+
+ <element name="reservationList">
+ <annotation>
+ <documentation>
+ A reservation list contains a sequence of zero or more
+ reservations.
+ </documentation>
+ </annotation>
+ <complexType>
+ <sequence>
+ <element ref="tns:reservation" minOccurs="0"
+ maxOccurs="unbounded">
+ </element>
+ </sequence>
+ <attribute ref="wsdli:wsdlLocation" />
+ </complexType>
+ </element>
+
+ </schema>
+ </pre></div>
+ </div>
+ </div>
</div>
+
<div class="div2">
<h3><a name="adv-xml-schema-examples"></a>5.12 XML Schema Examples</h3>
***************
*** 1747,1784 ****
<a href="http://www.w3.org/2002/ws/desc/wsdl20">latest version of "Web Services Description Language (WSDL) Version 2.0 Part 1: Core Language"</a> is available at http://www.w3.org/2002/ws/desc/wsdl20.
</dd>
!
! <dt class="label"><a name="WSDL-PART2"></a>[WSDL 2.0 Predefined Extensions] </dt><dd>
! <cite><a href="wsdl20-adjuncts.html">Web Services Description Language (WSDL)
! Version 2.0 Part 2: Predefined Extensions</a></cite>,
! M. Gudgin, A. Lewis, and J. Schlimmer, Editors. World
! Wide Web Consortium,
!
! 3 August 2004.
! This version of the "Web Services Description Language (WSDL)
! Version 2.0 Part 2: Predefined Extensions"
! Specification is available at wsdl20-adjuncts.html. The
! <a href="http://www.w3.org/2002/ws/desc/wsdl20-adjuncts">latest version of "Web Services Description Language (WSDL)
! Version 2.0 Part 2: Predefined Extensions"</a> is available at http://www.w3.org/2002/ws/desc/wsdl20-adjuncts.
! </dd>
!
!
!
! <dt class="label"><a name="WSDL-PART3"></a>[WSDL 2.0 Bindings] </dt><dd>
! <cite><a href=".html">Web Services Description Language (WSDL) Version
! 2.0 Part 3: Bindings</a></cite>, H. Haas,
! P. Le Hégaret,
! J-J. Moreau,
! D. Orchard,
! J. Schlimmer,
! S. Weerawarana, Editors. World Wide Web Consortium,
!
! 3 August 2004.
! This version of the "Web
! Services Description Version 2.0: Bindings" Specification
! is available at .html. The <a href="http://www.w3.org/2002/ws/desc/">latest version of "Web Services
! Description Language (WSDL) Version 2.0 Part 3:
! Bindings"</a> is available at http://www.w3.org/2002/ws/desc/.
! </dd>
!
--- 2358,2385 ----
<a href="http://www.w3.org/2002/ws/desc/wsdl20">latest version of "Web Services Description Language (WSDL) Version 2.0 Part 1: Core Language"</a> is available at http://www.w3.org/2002/ws/desc/wsdl20.
</dd>
!
! <dt class="label"><a name="WSDL-PART2"></a>[WSDL 2.0 Adjuncts] </dt><dd>
! <cite><a href="wsdl20-adjuncts.html">
! Web Services Description Language (WSDL)
! Version 2.0 Part 2: Adjuncts
! </a></cite>, M. Gudgin, H. Haas, P. Le Hégaret, A.
! Lewis, J-J. Moreau, D. Orchard, J. Schlimmer, S.
! Weerawarana, Editors. World Wide Web Consortium,
!
! 3 August 2004. This version of the "Web Services
! Description Language (WSDL) Version 2.0 Part 2:
! Adjuncts" Specification is available at
! wsdl20-adjuncts.html. The
! <a href="http://www.w3.org/2002/ws/desc/wsdl20-adjuncts">
! latest version of "Web Services Description
! Language (WSDL) Version 2.0 Part 2:
! Adjuncts"
! </a>
! is available at
! http://www.w3.org/2002/ws/desc/wsdl20-adjuncts.
! </dd>
!
!
!
***************
*** 1854,1857 ****
--- 2455,2472 ----
</dd>
+
+ <dt class="label"><a name="SOAP-MTOM"></a>[SOAP MTOM] </dt><dd>
+ <cite><a href="http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/">
+ SOAP Message Transmission Optimization
+ Mechanism
+ </a></cite>, M. Gudgin, N. Mendelsohn, M. Nottingham, H.
+ Ruellan, Editors. World Wide Web Consortium, 25
+ January, 2005. This version of SOAP Message
+ Transmission Optimization Mechanism is available
+ at
+ <a href="http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/"></a>
+ http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/.
+ </dd>
+
<dt class="label"><a name="XLINK"></a>[XML Linking] </dt><dd>
<cite><a href="http://www.w3.org/TR/2001/REC-xlink-20010627/">XML Linking Language (XLink) Version 1.0</a></cite>, S.
Received on Monday, 28 March 2005 12:23:25 UTC