- From: David Booth <dbooth@dev.w3.org>
- Date: Thu, 28 Oct 2004 02:53:50 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20
In directory hutz:/tmp/cvs-serv29123
Modified Files:
wsdl20-primer.xml
Log Message:
more progress on rewriting it to start with an early example to explain.
Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.17
retrieving revision 1.18
diff -C2 -d -r1.17 -r1.18
*** wsdl20-primer.xml 26 Oct 2004 21:36:24 -0000 1.17
--- wsdl20-primer.xml 28 Oct 2004 02:53:48 -0000 1.18
***************
*** 57,61 ****
<div2><head>Prerequisites</head>
<p>This primer assumes that the reader has the following prerequisite knowledge:
! <ulist><item><p> familiarity with XML (@@reference@@) and XML Namespaces (@@reference@@);</p></item>
<item><p> familiarity with basic Web services concepts such as requester agent, provider agent, and Web service description, as described in <xspecref href="http://www.w3.org/TR/2004/NOTE-ws-arch-20040211/#whatis">Section 1.4</xspecref> of <xspecref href="http://www.w3.org/TR/2004/NOTE-ws-arch-20040211/">Web services architecture</xspecref> and its <xspecref href="http://www.w3.org/TR/2004/NOTE-ws-gloss-20040211/">glossary</xspecref>.</p>
</item>
--- 57,61 ----
<div2><head>Prerequisites</head>
<p>This primer assumes that the reader has the following prerequisite knowledge:
! <ulist><item><p> familiarity with XML (@@reference@@) and XML Namespaces (@@reference@@);</p></item><item><p>some familiarity with XML Schema (@@reference@@);</p></item>
<item><p> familiarity with basic Web services concepts such as requester agent, provider agent, and Web service description, as described in <xspecref href="http://www.w3.org/TR/2004/NOTE-ws-arch-20040211/#whatis">Section 1.4</xspecref> of <xspecref href="http://www.w3.org/TR/2004/NOTE-ws-arch-20040211/">Web services architecture</xspecref> and its <xspecref href="http://www.w3.org/TR/2004/NOTE-ws-gloss-20040211/">glossary</xspecref>.</p>
</item>
***************
*** 75,156 ****
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in
this document are to be interpreted as described in RFC 2119.</p>
! <p>This document uses namespace prefixes throughout; they are
! listed in <specref ref="tabnsprefixes"/>. Note that the choice of
any namespace prefix is arbitrary and not semantically significant
(see <bibref ref="XMLInfoSet"/>).</p>
- <ednote><edtext>dbooth asks: Should we keep this table here? It duplicates what is in the spec. Maybe it would be better to introduce these as we go.</edtext></ednote><table border="1" summary="Mapping of prefixes used in this document to their
- associated namespace name" id="tabnsprefixes">
- <caption>Prefixes and Namespaces used in this primer</caption>
- <tbody>
- <tr>
- <th>Prefix</th>
- <th>Namespace</th>
- <th>Notes</th>
- </tr>
- <tr>
- <td>wsdl</td>
- <td>
- <attval>&wsdl-ns;</attval>
- </td>
- <td>A normative XML Schema <bibref ref="XMLSchemaP1"/>, <bibref ref="XMLSchemaP2"/> document for the
- <attval>&wsdl-ns;</attval> namespace can be found at <loc href="&wsdl-ns;">&wsdl-ns;</loc>. WSDL documents that do NOT
- conform to this schema are not valid WSDL documents. WSDL
- documents that DO conform to this schema and also conform to
- the other constraints defined in this specification are valid
- WSDL documents.</td>
- </tr>
- <tr>
- <td>wsdli</td>
- <td>
- <attval>&wsdl-i-ns;</attval>
- </td>
- <td>A normative XML Schema <bibref ref="XMLSchemaP1"/>, <bibref ref="XMLSchemaP2"/> document for the
- <attval>&wsdl-i-ns;</attval> namespace can be found at <loc href="&wsdl-i-ns;">&wsdl-i-ns;</loc>. </td>
- </tr>
- <tr>
- <td>wrpc</td>
- <td>
- <attval>&wsdl-rpc-ns;</attval>
- </td>
- <td>A normative XML Schema <bibref ref="XMLSchemaP1"/>, <bibref ref="XMLSchemaP2"/> document for the
- <attval>&wsdl-rpc-ns;</attval> namespace can be found at <loc href="&wsdl-rpc-ns;">&wsdl-rpc-ns;</loc>. WSDL documents that
- do NOT conform to this schema are not valid WSDL
- documents. WSDL documents that DO conform to this schema and
- also conform to the other constraints defined in this
- specification are valid WSDL documents. </td>
- </tr>
- <tr>
- <td>wsoap12</td>
- <td>
- <attval>&wsdl-soap12-ns;</attval>
- </td>
- <td rowspan="2">Defined by WSDL 2.0: Bindings <bibref ref="WSDL-PART3"/>.</td>
- </tr>
- <tr>
- <td>whttp</td>
- <td>
- <attval>&wsdl-http-ns;</attval>
- </td>
- </tr>
- <tr>
- <td>xs</td>
- <td>
- <attval>http://www.w3.org/2001/XMLSchema</attval>
- </td>
- <td rowspan="2">Defined in the W3C XML Schema
- specification <bibref ref="XMLSchemaP1"/>, <bibref ref="XMLSchemaP2"/>.</td>
- </tr>
- <tr>
- <td>xsi</td>
- <td>
- <attval>http://www.w3.org/2001/XMLSchema-instance</attval>
- </td>
- </tr>
- </tbody>
- </table>
- <p>Namespace names of the general form
- <attval>http://example.org/...</attval> and
- <attval>http://example.com/...</attval> represent application or
- context-dependent URIs <bibref ref="RFC2396"/>.</p>
</div2>
--- 75,83 ----
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in
this document are to be interpreted as described in RFC 2119.</p>
! <p>This document uses several XML namespaces, some of which are defined by standars, and some are application-specific. Namespace names of the general form
! <attval>http://greath.example.com/...</attval> represent application or
! context-dependent URIs <bibref ref="RFC2396"/>.Note also that the choice of
any namespace prefix is arbitrary and not semantically significant
(see <bibref ref="XMLInfoSet"/>).</p>
</div2>
***************
*** 161,175 ****
<head>WSDL 2.0 Basics</head>
! <p>This section introduces the basic concepts used in WSDL 2.0.</p>
! <!-- ************************ GreatH *************************** --><div2><head>Example: The GreatH Hotel Reservation Service</head><p>Throughout this primer, we use a hypothetical hotel reservation service to help explain WSDL2.0 concepts and constructs. We start with a simple scenario, and add more requirements gradually to illustrate how more advanced WSDL2.0 features may be used. </p><p>Hotel GreatH is located in a remote island. It has been relying on fax and phone to provide room reservations, both to travel agents and to customers directly. Even though the facilities and prices at GreatH are better than what its competitor offers, GreatH notices that its competitor is getting more customers than GreatH. After research, GreatH realizes that this is because the competitor offers a Web service that permits travel agent reservation systems to reserve rooms directly over the Internet. GreatH then hires a Web services architect, Joe Somebody, to build a reservation Web service, and provides him wih a list of requirements: <ulist><item><p>The service must be accessible by travel agents via their booking systems and directly by customers via GreatH's website site or email. </p></item><item><p>To check availability, a user must specify a check-in date, a check-out date, and room type room, and the Web service will provide the room rate if such a room is available. </p></item><item><p>To make a reservation, a user must provide a name, address, and credit card information, and the service will return a confirmation number if the reservation is sucessful. </p></item><item><p>The service will return an error message if the credit card number or any other data field is invalid.</p></item></ulist> Joe knows that he will later need to build a complete system that supports transactions and secured transmission. But as the first step, he decides to focus on the basic functionality so that he can begin testing and gain feedback from his customer, GreatH. He designs the Web service and begins writing a WSDL dcument to describe that service. Although he has chosen to create both the WSDL document and the Web service at the same time, it is certainly possible to create one before the other. Although the Web service must faithfully implement the WSDL document (or conversely, the WSDL document must accurately describe the Web service), WSDL 2.0 makes no requirement about which is created first. </p><p>Here is the initial WSDL 2.0 document that Joe creates. We will dissect and explain this example as we go along.</p><ednote><name>dbooth</name><edtext>ToDo: Further simplify this first example to define only one operation, CheckAvailability, and no faults. Or perhaps only one fault, using the in-out MEP.</edtext></ednote><example id="example-initial">
<head>@example-initial@ Initial WSDL Document for GreatH</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
! <definitions xmlns="http://www.w3.org/2004/08/wsdl"
! targetNamespace= "http://greath.example.com/2004/05/wsdl/reservationService.wsdl"
! xmlns:ghns = "http://greath.example.com/2004/05/schemas/reservationService.xsd"
! xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"
xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
! xmlns:tns= "http://greath.example.com/2004/05/wsdl/reservationService.wsdl">
<types>
--- 88,104 ----
<head>WSDL 2.0 Basics</head>
! <p>This section introduces the basic concepts used in WSDL 2.0 through the description of a hypothetical hotel reservation service. We start with a simple scenario, and add more requirements gradually to illustrate how more advanced WSDL2.0 features may be used. </p>
! <!-- ************************ GreatH *************************** --><div2><head>Example: The GreatH Hotel Reservation Service</head><p>Hotel GreatH is located in a remote island. It has been relying on fax and phone to provide room reservations, both to travel agents and to customers directly. Even though the facilities and prices at GreatH are better than what its competitor offers, GreatH notices that its competitor is getting more customers than GreatH. After research, GreatH realizes that this is because the competitor offers a Web service that permits travel agent reservation systems to reserve rooms directly over the Internet. GreatH then hires us to build a reservation Web service with the following functionality: <ulist><item><p><emph>CheckAvailability</emph>. To check availability, the client must specify a check-in date, a check-out date, and room type room, and the Web service will provide the room rate if such a room is available. If any input data is invalid, the service should returnan error. Thus, the service will accept a <code>checkAvailability</code> message and return a <code>checkAvailabilityResponse</code> or <code>invalidDataFault</code> message.</p> </item><item><p><emph>MakeReservation</emph>. To make a reservation, a client must provide a name, address, and credit card information, and the service will return a confirmation number if the reservation is successful. The service will return an error message if the credit card number or any other data field is invalid. Thus, the service will accept a <code>makeReservation</code> message and return a <code>makeReservationResponse</code> or <code>invalidCreditCardFault</code> message.</p></item></ulist> We know that we will later need to build a complete system that supports transactions and secured transmission, but initially we will implement only minimal functionality. In fact, to simplify our first example, we will implement only the <emph>CheckAvailability</emph> operation.</p><p>We begin by writing a WSDL 2.0 documentto describe a Web service that initially provides only the . Although the Web service must faithfully implement the WSDL document (or conversely, the WSDL document must accurately describe the Web service), WSDL 2.0 makes no requirement about which is created first. </p><p>Here is the initial WSDL 2.0 document we create. We will dissect and explain this example as we go along.</p><example id="example-initial">
<head>@example-initial@ Initial WSDL Document for GreatH</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
! <description
! xmlns="http://www.w3.org/2004/08/wsdl"
xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
! xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"
! xmlns:ghns = "http://greath.example.com/2004/05/schemas/reservationService.xsd"
! targetNamespace= "http://greath.example.com/2004/05/wsdl/reservationService.wsdl"
! xmlns:tns= "http://greath.example.com/2004/05/wsdl/reservationService.wsdl"
! >
<types>
***************
*** 191,196 ****
<xs:enumeration value="Single"/>
<xs:enumeration value="Double"/>
- <xs:enumeration value="Queen"/>
- <xs:enumeration value="King"/>
</xs:restriction>
</xs:simpleType>
--- 120,123 ----
***************
*** 211,215 ****
<xs:element name="invalidCreditCardError" type="xs:string"/>
! <xs:element name="inValidDataError" type="tInvalidDataError"/>
<xs:complexType name="tInvalidDataError">
<xs:sequence>
--- 138,142 ----
<xs:element name="invalidCreditCardError" type="xs:string"/>
! <xs:element name="invalidDataError" type="tInvalidDataError"/>
<xs:complexType name="tInvalidDataError">
<xs:sequence>
***************
*** 222,252 ****
<interface name = "reservation" >
-
- <fault name = "inValidCreditCardFault"
- element = "ghns:invalidCreditCardError"/>
-
- <fault name = "inValidDataFault"
- element = "ghns:invalidDataError"/>
-
- <operation name="checkAvailability" pattern="http://www.w3.org/2004/03/wsdl/in-out" >
-
- <input messageLabel="In" element="ghns:checkAvailability" />
-
- <output messageLabel="Out" element="ghns:checkAvailabilityResponse" />
-
- <outfault ref="inValidDataFault" messageLabel="Out"/>
-
- </operation>
-
- <operation name="makeReservation" pattern="http://www.w3.org/2004/03/wsdl/in-out" >
-
- <input messageLabel="In" element="ghns:makeReservation"/>
-
- <output messageLabel="Out" element="ghns:makeReservationResponse"/>
-
- <outfault ref="inValidDataFault" messageLabel="Out"/>
-
- <outfault ref="inValidCreditCardFault" messageLabel="Out"/>
</operation>
--- 149,163 ----
<interface name = "reservation" >
+ <fault name = "invalidDataFault"
+ element = "ghns:invalidDataError"/>
+
+ <operation name="checkAvailability"
+ pattern="http://www.w3.org/2004/03/wsdl/in-out" >
+ <input messageLabel="In"
+ element="ghns:checkAvailability" />
+ <output messageLabel="Out"
+ element="ghns:checkAvailabilityResponse" />
+ <outfault ref="invalidDataFault" messageLabel="Out"/>
</operation>
***************
*** 259,264 ****
wsoap:mepDefault="http://www.w3.org/2003/05/soap/mep/request-response">
- <fault ref="tns:invalidCreditCardFault" wsoap:code="soap:Sender"/>
-
<fault ref="tns:invalidDataFault" wsoap:code="soap:Sender"/>
--- 170,173 ----
***************
*** 273,287 ****
</service>
! </definitions>
! ]]></eg>
</example></div2><div2 id="Web_Service_Descriptions">
<head>The Purpose of the WSDL Document</head>
! <p>Before we dive into the details of the above example, it is helpful to understand this document represents from a big picture point of view. </p><p>A WSDL document is an XML document that describes the <emph>mechanics</emph> of interacting with a particular Web service, in this case, the GreatH hotel reservation service. Although the WSDL document is written solely from the point of view of the Web service (for example "input" is relative to the Web service), it is inherently intended to constrain <emph>both</emph> the Web service <emph>and</emph> any client application that makes use of that service, as illustrated below. It represents a take-it-or-leave-it "contract" that governs the interaction between the Web service and a client application. Of course, this "contract" is only partial because in general it only describes the mechanics of the interaction -- not the intended <emph>semantics</emph>. (Description of the application semantics is beyond the scope of WSDL 2.0.) The WSDL dcument is therefore concerned only with information that <emph>both</emph> parties must agree upon -- not information that is relevant only to one party or the other, such as internal implementation details. Furthermore, although the GreatH Web service may be used in conjunction with other Web services to perform a coordinated task, Web service <emph>composition</emph> is beyond the scope of WSDL 2.0. WSDL 2.0 is limited to the description of <emph>individual</emph> Web services. </p>
! <graphic source="images/requester-provider.gif" alt="WSDL document governing the interaction between a client application and a Web service."/>
</div2><div2><head>Major Elements of a Web Service Description</head><p>Let's start looking at the overall structure of example @@ above. </p><p>First, the top-most element of every WSDL 2.0 document is a <code><description></code> element, which merely acts as a container for the rest of the WSDL document. Attached to this element are several lines of namespace declarations. We'll explain the purpose of each one in a moment, but for now, let's just skip over them and look at some of the major elements within the WSDL document.</p><p>WSDL 2.0 enables you to separate the description of a Web service's abstract functionality from the concrete details of how and where that functionality is offered. WSDL 2.0 therefore divides a WSDL document into the following major elements.<ulist><item><p>A <code><types></code> element contains schema declarations of the kinds of messages that the GreatH Web service may send or receive, independent of any specific wire format. Although these tpes are typically defined using XML Schema (as in this example), WSDL 2.0 does permit the use of other schema defininition languages. </p></item><item><p>An <code><interface></code> element describes the abstract functionality of the Web service in terms of the abstract operations it performs. Thus, an interface consists of a set of <emph>operations</emph>. </p></item><item><p>An <code><operation></code> element describes a sequence of messages that may be exchanged with the Web service in a particular interaction, such as an input (request) message followed by an output (response) message. </p></item><item><p>A <code><binding></code> element describes how to access a Web service. It specifies transport and wire format details for one or more interfaces. </p></item><item><p>A <code><service></code> element lists the various locations where the described Web service can be accessed. Each location is known as an <emph>endpoint</emph>.</p></item><item><p>An <code><endpoint&g;</code> element specifies the network address where the service can be accessed via a particular transport protocol and wire format.</p></item></ulist></p>
<p>This separation of message type, interface, operation, binding, service and endpoint facilitates different levels of reusability and distribution of work in the lifecycle of a Web service and the WSDL document that describes it. For example, an interface describes the functionality and supported features of a service, and is used at design time. It has the highest level of reusability, and should be abstract and reusable for different bindings. A binding is used at configuration time. It provides transport protocol specific information about how to access a service, and should be reusable by different endpoints. An endpoint provides the concrete location of a service, and is used at run time. The endpoint is the most concrete element, specific to a particular instance of a service, and is therefore not reusable. </p><p>Now let's dig into this example in more detail.</p></div2><div2><head>Namespaces</head><p>In <loc href="#example-initial">@example-initial@</loc> above, several namespaces were dclared at the beginning:</p><eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
! <definitions
xmlns="http://www.w3.org/2004/08/wsdl"
xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
--- 182,195 ----
</service>
! </description>]]></eg>
</example></div2><div2 id="Web_Service_Descriptions">
<head>The Purpose of the WSDL Document</head>
! <p>Before we dive into the details of the above example, it is helpful to understand what this document represents as a whole. </p><p>A WSDL document is an XML document that describes the <emph>mechanics</emph> of interacting with a particular Web service, in this case, the GreatH hotel reservation service. Although the WSDL document is written solely from the point of view of the Web service (for example "input" is relative to the Web service), it is inherently intended to constrain <emph>both</emph> the Web service <emph>and</emph> any client application that makes use of that service, as illustrated below. It represents a take-it-or-leave-it "contract" that governs the interaction between the Web service and a client application. Of course, this "contract" is only partial because in general it only describes the mechanics of the interaction -- not the intended <emph>semantics</emph>. (Description of the application semantics is beyond the scope of WSDL 2.0.) The WSDL document is therefre concerned only with information that <emph>both</emph> parties must agree upon -- not information that is relevant only to one party or the other, such as internal implementation details. Furthermore, although the GreatH Web service may be used in conjunction with other Web services to perform a coordinated task, Web service <emph>composition</emph> is beyond the scope of WSDL 2.0. WSDL 2.0 is limited to the description of <emph>individual</emph> Web services. </p>
! <ednote><name>dbooth</name><edtext>Diagram below still needs to be updated to reflect the most recent change in client/service terminology.</edtext></ednote><graphic source="images/requester-provider.gif" alt="WSDL document governing the interaction between a client application and a Web service."/>
</div2><div2><head>Major Elements of a Web Service Description</head><p>Let's start looking at the overall structure of example @@ above. </p><p>First, the top-most element of every WSDL 2.0 document is a <code><description></code> element, which merely acts as a container for the rest of the WSDL document. Attached to this element are several lines of namespace declarations. We'll explain the purpose of each one in a moment, but for now, let's just skip over them and look at some of the major elements within the WSDL document.</p><p>WSDL 2.0 enables you to separate the description of a Web service's abstract functionality from the concrete details of how and where that functionality is offered. WSDL 2.0 therefore divides a WSDL document into the following major elements.<ulist><item><p>A <code><types></code> element contains schema declarations of the kinds of messages that the GreatH Web service may send or receive, independent of any specific wire format. Although these tpes are typically defined using XML Schema (as in this example), WSDL 2.0 does permit the use of other schema defininition languages. </p></item><item><p>An <code><interface></code> element describes the abstract functionality of the Web service in terms of the abstract operations it performs. Thus, an interface consists of a set of <emph>operations</emph>. </p></item><item><p>An <code><operation></code> element describes a sequence of messages that may be exchanged with the Web service in a particular interaction, such as an input (request) message followed by an output (response) message. </p></item><item><p>A <code><binding></code> element describes how to access a Web service. It specifies transport and wire format details for one or more interfaces. </p></item><item><p>A <code><service></code> element lists the various locations where the described Web service can be accessed. Each location is known as an <emph>endpoint</emph>.</p></item><item><p>An <code><endpoint&g;</code> element specifies the network address where the service can be accessed via a particular transport protocol and wire format.</p></item></ulist></p>
<p>This separation of message type, interface, operation, binding, service and endpoint facilitates different levels of reusability and distribution of work in the lifecycle of a Web service and the WSDL document that describes it. For example, an interface describes the functionality and supported features of a service, and is used at design time. It has the highest level of reusability, and should be abstract and reusable for different bindings. A binding is used at configuration time. It provides transport protocol specific information about how to access a service, and should be reusable by different endpoints. An endpoint provides the concrete location of a service, and is used at run time. The endpoint is the most concrete element, specific to a particular instance of a service, and is therefore not reusable. </p><p>Now let's dig into this example in more detail.</p></div2><div2><head>Namespaces</head><p>In <loc href="#example-initial">@example-initial@</loc> above, several namespaces were dclared at the beginning:</p><eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
! <description
xmlns="http://www.w3.org/2004/08/wsdl"
xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
***************
*** 292,296 ****
>
. . .
! </definitions>]]></eg><p>Some of these are used as normal XML namespaces; others have special treatment within WSDL 2.0. <glist><gitem><label><code>xmlns="http://www.w3.org/2004/08/wsdl"</code></label><def><p>This is the XML namespace for WSDL 2.0 itself. The WSDL 2.0 vocabulary (<code><description></code>, <code><types></code>, <code><interface></code>, etc.) is in this namespace. For convenience, Joe has chosen not to define a namespace prefix for this namespace, so by default unprefixed elements and attributes are from the WSDL 2.0 namespace.</p></def></gitem><gitem><label><code>xmlns:soap="http://www.w3.org/2003/05/soap-envelope"</code></label><def><p>This is the XML namespace for SOAP 1.2, and is needed because the GreatH service will use SOAP 1.2. This namespace prefix (<code>soap:</code>) will be used in section @@, when we specify the transport protocol that the GreatH Web service supports.</p></def></gitem><gitem><label><code>xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soa12"</code></label><def><p>This is the XML namespace for the WSDL 2.0 binding of SOAP 1.2. This is needed because the WSDL 2.0 language does not define any binding vocabulary directly. Instead, the various binding styles are defined as extensions to the WSDL 2.0 language, and each one is defined in its own XML namespace. The GreatH binding will be explained in section @@.</p></def></gitem><gitem><label><code>xmlns:ghns = "http://greath.example.com/2004/05/schemas/reservationService.xsd"</code></label><def><p>This is the XML namespace for the GreatH message schemas that are defined in the <code><types></code> element. This is a separate namespace because these types may exist and be used independently of WSDL. </p></def></gitem><gitem><label><code>targetNamespace= "http://greath.example.com/2004/05/wsdl/reservationService.wsdl"</code></label><def><p>This is not technically an XML namespace, but it serves an analogous purpose within WSDL 2.0. As mentioned above, a WSDL document contains elements uch as <code><interface></code>, <code><operation></code>, <code><binding></code> and <code><service></code>; and each of these elements can have a <code>name</code> attribute to enable other portions of the WSDL document to refer to that element by name. (We'll see how this works later.) The targetNamespace URI represents a globally unambiguous name for the set of interface, operation, binding, service, etc., names that your WSDL document has declared. This is pertinent if one WSDL document imports another WSDL document, as described in section @@, because it prevents accidental name clashes.</p><p>The value of the targetNamespace MUST be an absolute URI. Furthermore, it SHOULD be dereferenceable to a WSDL document that describes the Web service that the targetNamespace is used to describe, i.e., the GreatH SHOULD make the WSDL document available from this URI. (However, there is no absolute requirement for GreatH to do so; thus a WSDL processor must not depend on this UI being dereferenceable.) </p><p>This recommendation may sound circular, but bear in mind that the user might have obtained the WSDL document from anywhere -- not necessarily an authoritative source. But by dereferencing the targetNamespace URI, a user SHOULD be able to obtain an authoritative version. @@Add reference to WebArch on the meaning of "authoritative"?@@ Since GreatH is the owner of the service, the targetNamespace URI refers to a location on the GreatH Web site.</p></def></gitem><gitem><label><code>xmlns:tns= "http://greath.example.com/2004/05/wsdl/reservationService.wsdl"</code></label><def><p>This is an XML namespace declaration with the same URI value that was specified above for the <code>targetNamespace</code>. Note that this is an <emph>actual</emph> XML namespace declaration, whereas the <code>targetNamespace</code> declaration above is a WSDL 2.0 attribute whose purpose is <emph>analogous</emph> to an XML namespace. The <code>tns:</code> namespace prefix that it defines will b used later, when we need to refer to an interface, operation, binding or service that we have defined within our targetNamespace. </p></def></gitem><gitem><label><code>@@</code></label><def><p>@@</p></def></gitem></glist></p></div2><div2><head>Defining Message Types</head><p>Continuing our tour through <loc href="#example-initial">@example-initial@</loc> above, the next portion defines the types of messages that the GreatH service will send and receive:</p><eg><![CDATA[. . .
<types>
<xs:schema targetNamespace="http://greath.example.com/2004/05/schemas/reservationService.xsd"
--- 200,204 ----
>
. . .
! </description>]]></eg><p>Some of these are used as normal XML namespaces; others have special treatment within WSDL 2.0. <glist><gitem><label><code>xmlns="http://www.w3.org/2004/08/wsdl"</code></label><def><p>This is the XML namespace for WSDL 2.0 itself. The WSDL 2.0 vocabulary (<code><description></code>, <code><types></code>, <code><interface></code>, etc.) is in this namespace. For convenience, we have chosen not to define a namespace prefix for this namespace, so by default unprefixed elements and attributes are from the WSDL 2.0 namespace.</p></def></gitem><gitem><label><code>xmlns:soap="http://www.w3.org/2003/05/soap-envelope"</code></label><def><p>This is the XML namespace for SOAP 1.2, and is needed because the GreatH service will use SOAP 1.2. This namespace prefix (<code>soap:</code>) will be used in section @@, when we specify the transport protocol that the GreatH Web service supports.</p></def></gitem><gitem><label><code>xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soa12"</code></label><def><p>This is the XML namespace for the WSDL 2.0 binding of SOAP 1.2. This is needed because the WSDL 2.0 language does not define any binding vocabulary directly. Instead, the various binding styles are defined as extensions to the WSDL 2.0 language, and each one is defined in its own XML namespace. The GreatH binding will be explained in section @@.</p></def></gitem><gitem><label><code>xmlns:ghns = "http://greath.example.com/2004/05/schemas/reservationService.xsd"</code></label><def><p>This is the XML namespace for the GreatH message schemas that are defined in the <code><types></code> element. This is a separate namespace because these types may exist and be used independently of WSDL. </p></def></gitem><gitem><label><code>targetNamespace= "http://greath.example.com/2004/05/wsdl/reservationService.wsdl"</code></label><def><p>This is not technically an XML namespace, but it serves an analogous purpose within WSDL 2.0. As mentioned above, a WSDL document contains elements uch as <code><interface></code>, <code><operation></code>, <code><binding></code> and <code><service></code>; and each of these elements can have a <code>name</code> attribute to enable other portions of the WSDL document to refer to that element by name. (We'll see how this works later.) The targetNamespace URI represents a globally unambiguous name for the set of interface, operation, binding, service, etc., names that your WSDL document has declared. This is pertinent if one WSDL document imports another WSDL document, as described in section @@, because it prevents accidental name clashes.</p><p>The value of the targetNamespace MUST be an absolute URI. Furthermore, it SHOULD be dereferenceable to a WSDL document that describes the Web service that the targetNamespace is used to describe, i.e., the GreatH SHOULD make the WSDL document available from this URI. (However, there is no absolute requirement for GreatH to do so; thus a WSDL processor must not depend on this UI being dereferenceable.) </p><p>This recommendation may sound circular, but bear in mind that the client might have obtained the WSDL document from anywhere -- not necessarily an authoritative source. But by dereferencing the targetNamespace URI, a user SHOULD be able to obtain an authoritative version. @@Add reference to WebArch on the meaning of "authoritative"?@@ Since GreatH is the owner of the service, the targetNamespace URI refers to a location on the GreatH Web site.</p></def></gitem><gitem><label><code>xmlns:tns= "http://greath.example.com/2004/05/wsdl/reservationService.wsdl"</code></label><def><p>This is an XML namespace declaration with the same URI value that was specified above for the <code>targetNamespace</code>. Note that this is an <emph>actual</emph> XML namespace declaration, whereas the <code>targetNamespace</code> declaration above is a WSDL 2.0 attribute whose purpose is <emph>analogous</emph> to an XML namespace. The <code>tns:</code> namespace prefix that it defines willbe used later, when we need to refer to an interface, operation, binding or service that we have defined within our targetNamespace. </p></def></gitem></glist></p></div2><div2><head>Defining Message Types</head><p>Continuing our tour through <loc href="#example-initial">@example-initial@</loc> above, the next portion defines the types of messages that the GreatH service will send and receive:</p><eg><![CDATA[. . .
<types>
<xs:schema targetNamespace="http://greath.example.com/2004/05/schemas/reservationService.xsd"
***************
*** 329,333 ****
! <div2><head>Defining an Interface</head><p>The next portion of <loc href="#example-initial">@example-initial@</loc> above defines the abstract interface that the GreatH service provides to its client applications:</p><eg><![CDATA[@dbooth stopped here@]]></eg><p><?xm-replace_text {p}?></p></div2><div2 id="overview">
<head>WSDL 2.0 Extensibility</head>
--- 237,257 ----
! <div2><head>Defining an Interface</head><p>The next portion of <loc href="#example-initial">@example-initial@</loc> above defines the abstract interface that the GreatH service provides to its client applications:</p><eg><![CDATA[. . .
! <interface name = "reservation" >
!
! <fault name = "invalidDataFault"
! element = "ghns:invalidDataError"/>
!
! <operation name="checkAvailability"
! pattern="http://www.w3.org/2004/03/wsdl/in-out" >
! <input messageLabel="In"
! element="ghns:checkAvailability" />
! <output messageLabel="Out"
! element="ghns:checkAvailabilityResponse" />
! <outfault ref="invalidDataFault" messageLabel="Out"/>
! </operation>
!
! </interface>
! . . .]]></eg><p>Let's look at this line by line. </p><glist><gitem><label><code><interface name = "reservation" ></code></label><def><p>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 targetNamespace. Interface names are tokens that must not contain a space or colon (":").</p></def></gitem><gitem><label><code>@dbooth stopped here@</code></label><def><p>@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@</p></def></gitem><gitem><label><code>@@</code></label><def><p>@@</p></def></gitem><gitem><label><code>@@</code></label><def><p>@@</p></def></gitem><gitem><label><code>@@</code></label><def><p>@@</p></def></gitem></glist></div2><div2 id="overview">
<head>WSDL 2.0 Extensibility</head>
***************
*** 506,511 ****
<div2 id="messages">
<head>Defining Messages Using XML Schema</head>
! <p>Based on the requirements he got for our hotel reservation service, Joe realizes that the service will exchange at least two sets of messages with its requesters. To check availability, a requester of the service must provide a check-in date, a check-out date, and specifies the type of room, and the Web service will provide the room rate if any desired room is available. To make a reservation, a requester must provide a name, address, and credit card information, and the service will return a confirmation number.</p>
! <p>The first decision Joe has to make is what type system to use for defining these messages. Though WSDL2.0 allows messages being defined in theoretically any type systems via extensions (the primer covers use of other type systems in section @@@@), all WSDL2.0 processors are required to support W3C XML Schema Description Language. Joe decides that XML Schema will be used for the reservation service. He also note that how the actual XML schema should be constructed is guided by XML Schema Language specification with one additional restriction added WSDL2.0 specification that all messages must be defined as a global element delcaration. After consulted with XML schema experts in GreatH, Joe have the following schema defined for the messages to cover the initial requirements: </p>
<example>
<head>Message definitions for the reservation service</head>
--- 430,435 ----
<div2 id="messages">
<head>Defining Messages Using XML Schema</head>
! <p>Based on the requirements we got for our hotel reservation service, we can see that the service will exchange at least two sets of messages with its requesters. To check availability, a requester of the service must provide a check-in date, a check-out date, and specifies the type of room, and the Web service will provide the room rate if any desired room is available. To make a reservation, a requester must provide a name, address, and credit card information, and the service will return a confirmation number.</p>
! <p>The first decisionwe need to make is what type system to use for defining these messages. Though WSDL2.0 allows messages being defined in theoretically any type systems via extensions (the primer covers use of other type systems in section @@@@), all WSDL2.0 processors are required to support W3C XML Schema Description Language. We decide that XML Schema will be used for the reservation service. We also note that how the actual XML schema should be constructed is guided by XML Schema Language specification with one additional restriction added WSDL2.0 specification that all messages must be defined as a global element delcaration. After consulted with XML schema experts in GreatH, we have the following schema defined for the messages to cover the initial requirements: </p>
<example>
<head>Message definitions for the reservation service</head>
***************
*** 558,562 ****
</eg>
</example>
! <p>After the schemas are defined, the second thing Joe needs to decide is how to make this type definitions available to WSDL description. WSDL2.0 provides as a direct child of <el>definitions</el> the <el>types</el> element for enclosing messages definitions. There are two ways to enclose messages defintions within <el>types</el>: use <el>xs:import</el> mechanism provided by XML Schema, or embed the schemas within <el>xs:schema</el> elements. It's perfectly reasonable to use both ways in one WSDL. The following is a summary of the XML syntax for <el>types</el>:</p>
<eg xml:space="preserve"><definitions>
<<b>types</b>>
--- 482,486 ----
</eg>
</example>
! <p>After the schemas are defined, the second thing we need to decide is how to make this type definitions available to WSDL description. WSDL2.0 provides as a direct child of <el>definitions</el> the <el>types</el> element for enclosing messages definitions. There are two ways to enclose messages defintions within <el>types</el>: use <el>xs:import</el> mechanism provided by XML Schema, or embed the schemas within <el>xs:schema</el> elements. It's perfectly reasonable to use both ways in one WSDL. The following is a summary of the XML syntax for <el>types</el>:</p>
<eg xml:space="preserve"><definitions>
<<b>types</b>>
***************
*** 633,637 ****
</item>
</ulist>
! <p>After look into these two options, Joe figures out that importing the schema is the easiest way for him since the schema is already defined in its own file. In addition, he also want the schema definitions be available for other purposes. So Joe writes down the following WSDL to summarizes what he has got so far:</p>
<example>
<head>Importing message definitions into WSDL</head>
--- 557,561 ----
</item>
</ulist>
! <p>After look into these two options, we decide that importing the schema is the easiest way, since the schema is already defined in its own file. In addition, we also want the schema definitions be available for other purposes. So we writes down the following WSDL to summarize what we have so far:</p>
<example>
<head>Importing message definitions into WSDL</head>
***************
*** 663,667 ****
</eg>
</example>
! <p>So far, Joe has successfully defined the message types and made them available for WSDL. In the following sections, the primer will move on to define the interface for the reservation service. </p>
</div3>
</div2>
--- 587,591 ----
</eg>
</example>
! <p>So far, we have successfully defined the message types and made them available for WSDL. In the following sections, the primer will move on to define the interface for the reservation service. </p>
</div3>
</div2>
***************
*** 740,744 ****
</ednote>
! <p>Equipped with the knowledge of all the MEPs defined in WSDL2.0, Joe has analyzed the list of requirements he has in hand and decided that the in-out MEP covers his requirement pretty well. Now he can move on to define the interface for the reservation Web service.</p>
</div2>
<!-- ************************interface*************************** -->
--- 664,668 ----
</ednote>
! <p>Equipped with the knowledge of all the MEPs defined in WSDL2.0, we have analyzed the list of requirements we have in hand and decided that the in-out MEP covers the requirement pretty well. Now we can move on to define the interface for the reservation Web service.</p>
</div2>
<!-- ************************interface*************************** -->
***************
*** 838,842 ****
<p>The <el>fault</el> element can be used to declare faults that may occur during execution of operations of an interface. Declaring <el>fault</el>s directly under <el>interface</el> and referencing these faults in operations where they apply allow one to easily indicate that some faults can occur in multiple operations. </p>
<p>The <el>fault</el> element has a required <att>name</att> attribute. Within a same namespace, all faults must be named uniquely. The optional <att>element</att> attribute can be used to indicate the content or playload of the falut message. Its vaule should be the qname of the XML schema global element declaration which defines the fault message.Please note when other type systems are used to define a fault message, additional attribute needs to be defined via the WSDL's attribute extension mechanism to allow associating such message definition with the fault.</p>
! <p>For our reservation service of GreatH hotel, Joe has defined the fault messages in XML Schema in example 4-1 and imported the schema into his WSDL in example 4-2, now it's time for Joe to add to his WSDL the assiciation of that fault message schema with the actual fault declarations.</p>
<example>
<head>Declaring interface faults</head>
--- 762,766 ----
<p>The <el>fault</el> element can be used to declare faults that may occur during execution of operations of an interface. Declaring <el>fault</el>s directly under <el>interface</el> and referencing these faults in operations where they apply allow one to easily indicate that some faults can occur in multiple operations. </p>
<p>The <el>fault</el> element has a required <att>name</att> attribute. Within a same namespace, all faults must be named uniquely. The optional <att>element</att> attribute can be used to indicate the content or playload of the falut message. Its vaule should be the qname of the XML schema global element declaration which defines the fault message.Please note when other type systems are used to define a fault message, additional attribute needs to be defined via the WSDL's attribute extension mechanism to allow associating such message definition with the fault.</p>
! <p>For our reservation service of GreatH hotel, we have defined the fault messages in XML Schema in example 4-1 and imported the schema into the WSDL document in example 4-2, now it's time to add the association of that fault message schema with the actual fault declarations.</p>
<example>
<head>Declaring interface faults</head>
***************
*** 928,932 ****
<p>An <el>operation</el> references a set of ordinary and fault messages it accepts or sends via zero or more <el>input</el>, <el>output</el>,<el>infault</el>, and <el>outfault</el> element. Which of these constructs to use is governed by the MEP in use. As we have seen in section@@@@,an MEP defines a set of placeholder messages that participate in the pattern and assigns them unique names within the pattern. The <el>input</el> and <el>output</el> element are used to associate an actual mesage type with that message placeholder in the MEP. Such association is done via two attributes:<att>messageLabel</att> and <att>element</att>. The <att>messageLabel</att> attribute can be used to identify the role this message plays in the MEP. Its vaule muse match the name of the MEP place holder message. Note thta the <att>messageLabel</att> is optional, since it's not necessary to explicitly set the messageLabel when the MEP in use has only one message with a given direction. The <att>element</att> attribute ca be used to identify the messages content (aka payload) when the content model is defined in XML Schema (see section @@@@ for using other type systems). The content model is a token with one of the values <emph>#any</emph>, <emph>#none</emph>, or <emph>#element</emph>. A value of <emph>#any</emph> indicates that the message content is any single element. In other, the message can be any XML message. A value of <emph>#none</emph> indicates there is no message content. It means that the payload will be empty. When the value is set to a Qname, it indicates that the message consists of a single element described by the referenced global element declaration pointed to by the Qname. In addition, the direction implied by the <b>in</b>put, and <b>out</b>put must also match the direction of the placeholder message identified by <att>messageLabel</att>. </p>
<p>We have already talked about how to associate a message type with a reusable interface <el>fault</el>. We have also covered the fault generation rules a MEP may use. Here under <el>operation</el>, the <el>infault</el> and <el>outfault</el> elements can be used to associate an interface <el>fault</el> with an specific message in the MEP used by an <el>operation</el>. Such association is done via a few attributes: the now familiar <att>messageLabel</att> attribute, the direction implied by the <b>in</b>fault and <b>out</b>fault, and a required <att>ref</att> attrbiute which points to the Qname of an interface <el>fault</el>.when <el>infault</el> and/or <el>outfault</el> occur multiple times within an <el>operation</el>, they define alternative fault message. </p>
! <p>Going back to our hotel reservation service, Joe now is ready to add the operations into his WSDL. Based on the requirements, Joe decides that the reservation service has two operations, the first is for checking availability, the second one is for making reservation. </p>
<example>
<head>Defining Interface Operations</head>
--- 852,856 ----
<p>An <el>operation</el> references a set of ordinary and fault messages it accepts or sends via zero or more <el>input</el>, <el>output</el>,<el>infault</el>, and <el>outfault</el> element. Which of these constructs to use is governed by the MEP in use. As we have seen in section@@@@,an MEP defines a set of placeholder messages that participate in the pattern and assigns them unique names within the pattern. The <el>input</el> and <el>output</el> element are used to associate an actual mesage type with that message placeholder in the MEP. Such association is done via two attributes:<att>messageLabel</att> and <att>element</att>. The <att>messageLabel</att> attribute can be used to identify the role this message plays in the MEP. Its vaule muse match the name of the MEP place holder message. Note thta the <att>messageLabel</att> is optional, since it's not necessary to explicitly set the messageLabel when the MEP in use has only one message with a given direction. The <att>element</att> attribute ca be used to identify the messages content (aka payload) when the content model is defined in XML Schema (see section @@@@ for using other type systems). The content model is a token with one of the values <emph>#any</emph>, <emph>#none</emph>, or <emph>#element</emph>. A value of <emph>#any</emph> indicates that the message content is any single element. In other, the message can be any XML message. A value of <emph>#none</emph> indicates there is no message content. It means that the payload will be empty. When the value is set to a Qname, it indicates that the message consists of a single element described by the referenced global element declaration pointed to by the Qname. In addition, the direction implied by the <b>in</b>put, and <b>out</b>put must also match the direction of the placeholder message identified by <att>messageLabel</att>. </p>
<p>We have already talked about how to associate a message type with a reusable interface <el>fault</el>. We have also covered the fault generation rules a MEP may use. Here under <el>operation</el>, the <el>infault</el> and <el>outfault</el> elements can be used to associate an interface <el>fault</el> with an specific message in the MEP used by an <el>operation</el>. Such association is done via a few attributes: the now familiar <att>messageLabel</att> attribute, the direction implied by the <b>in</b>fault and <b>out</b>fault, and a required <att>ref</att> attrbiute which points to the Qname of an interface <el>fault</el>.when <el>infault</el> and/or <el>outfault</el> occur multiple times within an <el>operation</el>, they define alternative fault message. </p>
! <p>Going back to our hotel reservation service, we are now ready to add the operations into our WSDL. Based on the requirements, we decide that the reservation service has two operations, the first is for checking availability, the second one is for making reservation. </p>
<example>
<head>Defining Interface Operations</head>
Received on Thursday, 28 October 2004 02:53:50 UTC