- From: David Booth <dbooth@dev.w3.org>
- Date: Mon, 13 Dec 2004 22:14:23 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20
In directory hutz:/tmp/cvs-serv31867
Modified Files:
wsdl20-primer.xml
Log Message:
Completed the rewrite/restructuring of the initial example. Now working
on lots of editorial and consistency details.
Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.19
retrieving revision 1.20
diff -C2 -d -r1.19 -r1.20
*** wsdl20-primer.xml 11 Dec 2004 23:21:11 -0000 1.19
--- wsdl20-primer.xml 13 Dec 2004 22:14:20 -0000 1.20
***************
*** 64,72 ****
<div2 id="PrimerStructure">
<head>Structure of the Primer</head>
! <p>@@ToDo: Update this@@</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 types 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 <emph>operations</emph> it performs. Each operation describes a sequence of message types 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 <emph>endpoints</emph> (i.e., network locations) 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, binding and service 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>Section 2 provides a big picture view of WSDL 2.0. It desribes the purpose and scope of the language, and explains its most important concepts.</p>
<p>Section 3 presents an example use case, the GreatH hotel reservation service, and explains how an abstract interface for this Web service is described in WSDL 2.0. It first explains how messages are defined using XML Schema and get used by WSDL 2.0; it then moves on to examine the details of the interface construct. </p>
! <p>Section 4 continues the GreatH example, explaining how to bind an abstract interface to concrete transport protocols. It first introduces the WSDL 2.0 binding constructs, and then explains the binding extensions defined by @WSDL2.0 part 3@, including bindings for SOAP 1.2, SOAP 1.1 and HTTP.</p>
<p>Section 5 covers service endpoint definitions, further developing the GreatH example.</p>
<p>Section 6 covers advanced topics, including features and properties, flexible authoring styles, service references, use of URIs, etc. </p>
--- 64,72 ----
<div2 id="PrimerStructure">
<head>Structure of the Primer</head>
! <p>@@ToDo: Update this@@</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 types 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 <emph>operations</emph> it performs. Each operation describes a sequence of message types 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 transmission and wire format details for one or more interfaces. </p></item><item><p>A <code><service></code> element lists the various <emph>endpoints</emph> (i.e., network locations) where the service can be accessed via a particular transmission protocol and wire format.</p></item></ulist></p>
! <p>This separation of message type, interface, binding and service 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 transmission 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>Section 2 provides a big picture view of WSDL 2.0. It desribes the purpose and scope of the language, and explains its most important concepts.</p>
<p>Section 3 presents an example use case, the GreatH hotel reservation service, and explains how an abstract interface for this Web service is described in WSDL 2.0. It first explains how messages are defined using XML Schema and get used by WSDL 2.0; it then moves on to examine the details of the interface construct. </p>
! <p>Section 4 continues the GreatH example, explaining how to bind an abstract interface to concrete transmission protocols. It first introduces the WSDL 2.0 binding constructs, and then explains the binding extensions defined by @WSDL2.0 part 3@, including bindings for SOAP 1.2, SOAP 1.1 and HTTP.</p>
<p>Section 5 covers service endpoint definitions, further developing the GreatH example.</p>
<p>Section 6 covers advanced topics, including features and properties, flexible authoring styles, service references, use of URIs, etc. </p>
***************
*** 92,159 ****
<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. 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 return an error. Thus, the service will accept a <codecheckAvailability</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. @@ Delete the other operation? @@</p><p>The next several sections proceed step-by-step throughthe process of developing a WSDL 2.0 document that describes the desired Web service. However, for those who can't wait to see a complete example, here is the initial WSDL document that we'll be creating.</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/schemas/resSvc.xsd"
targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
! >
<types>
! <xs:schema targetNamespace="http://greath.example.com/2004/schemas/resSvc.xsd"
! xmlns:xs="http://www.w3.org/2001/XMLSchema"
! xmlns="http://greath.example.com/2004/schemas/resSvc.xsd">
! <xs:element name="checkAvailability" type="tCheckAvailability"/>
! <xs:complexType name="tCheckAvailability">
! <xs:sequence>
! <xs:element name="checkInDate" type="xs:date"/>
! <xs:element name="checkOutDate" type="xs:date"/>
! <xs:element name="roomType" type="tRoomType"/>
! </xs:sequence>
! </xs:complexType>
!
! <xs:simpleType name="tRoomType">
! <xs:restriction base="xs:string">
! <xs:enumeration value="Single"/>
! <xs:enumeration value="Double"/>
! </xs:restriction>
! </xs:simpleType>
!
! <xs:element name="checkAvailabilityResponse" type="xs:double"/>
!
! <xs:element name="MakeReservation" type="tMakeReservation"/>
! <xs:complexType name="tMakeReservation">
<xs:sequence>
! <xs:element name="customerName" type="xs:string"/>
! <xs:element name="billingAddress" type="xs:string"/>
! <xs:element name="creditCardNumber" type="xs:string"/>
</xs:sequence>
! </xs:complexType>
!
! <xs:element name="makeReservationResponse" type="xs:string"/>
! <xs:element name="invalidCreditCardError" type="xs:string"/>
! <xs:element name="invalidDataError" type="tInvalidDataError"/>
! <xs:complexType name="tInvalidDataError">
! <xs:sequence>
! <xs:element name="DataField" type="xs:string"/>
! <xs:element name="Description" type="xs:string"/>
! </xs:sequence>
! </xs:complexType>
! </xs:schema>
</types>
! <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"
--- 92,142 ----
<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. 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 return an error. Thus, the service will accept a <codecheckAvailability</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>The next several sections proceed step-by-step through the process of developing a WSDL2.0 document that describes the desired Web service. However, for those who can't wait to see a complete example, here is the initial WSDL document that we'll be creating.</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"
targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
! xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
! xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"
! xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
!
! <documentation>
! This document describes the GreatH Web service. Additional
! application-level requirements for its use of this service --
! beyond what WSDL 2.0 is able to describe -- are available
! at http://greath.example.com/2004/reservation-documentation.html
! </documentation>
<types>
! <xs:schema
! xmlns:xs="http://www.w3.org/2001/XMLSchema"
! targetNamespace="http://greath.example.com/2004/schemas/resSvc.xsd"
! xmlns="http://greath.example.com/2004/schemas/resSvc.xsd">
! <xs:element name="checkAvailability" type="tCheckAvailability"/>
! <xs:complexType name="tCheckAvailability">
<xs:sequence>
! <xs:element name="checkInDate" type="xs:date"/>
! <xs:element name="checkOutDate" type="xs:date"/>
! <xs:element name="roomType" type="xs:string"/>
</xs:sequence>
! </xs:complexType>
!
! <xs:element name="checkAvailabilityResponse" type="xs:double"/>
! <xs:element name="invalidDataError" type="xs:string"/>
! </xs:schema>
</types>
! <interface name = "reservationInterface" >
<fault name = "invalidDataFault"
element = "ghns:invalidDataError"/>
! <operation name="opCheckAvailability"
pattern="http://www.w3.org/2004/03/wsdl/in-out" >
<input messageLabel="In"
***************
*** 161,165 ****
<output messageLabel="Out"
element="ghns:checkAvailabilityResponse" />
! <outfault ref="invalidDataFault" messageLabel="Out"/>
</operation>
--- 144,148 ----
<output messageLabel="Out"
element="ghns:checkAvailabilityResponse" />
! <outfault ref="tns:invalidDataFault" messageLabel="Out"/>
</operation>
***************
*** 167,188 ****
<binding name="reservationSOAPBinding"
! interface="tns:reservation"
type="http://www.w3.org/2004/08/wsdl/soap12"
! wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP"
! wsoap:mepDefault="http://www.w3.org/2003/05/soap/mep/request-response">
! <fault ref="tns:invalidDataFault" wsoap:code="soap:Sender"/>
</binding>
! <service name="resSvc" interface="tns:reservation">
! <endpoint name="reservationEndpoint"
! binding="tns:reservationSOAPBinding"
! address ="http://greath.example.com/reservation"/>
</service>
! </description>]]></eg>
</example></div2><div2><head>Getting Started: Defining the targetNamespace</head><p>Before writing our WSDL 2.0 document, we need to decide on a <code>targetNamespace</code> URI for it. The <code>targetNamespace</code> in WSDL 2.0 is analogous to a targetNamespace in XML Schema: interface, binding and service names that we define in our WSDL document will be associated with this <code>targetNamespace</code>, and thus will be distinguishable from similar names in a different <code>targetNamespace</code>. (This will become important if you use WSDL 2.0's <code>import</code> or interface inheritance mechanisms.) </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. (And if a WSDL description is split into multiple documents, then the <att>targetNamespace</att> should resolve to a mater document that includes all the WSDL documents needed for that service description.) However, there is no absolute requirement for this URI to be dereferenceable; thus a WSDL processor must not depend on it 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. Since GreatH will be the owner of the service, the targetNamespace URI should refer to a location on the GreatH Web site or otherwise within its control.</p><p>Once we have decided on a targetNamespace, we can begin our WSDL 2.0 document as the following empty shell.</p><example id="example-empty-shell">
<head>@example-empty-shell@ An Empty WSDL Document</head>
--- 150,176 ----
<binding name="reservationSOAPBinding"
! interface="tns:reservationInterface"
type="http://www.w3.org/2004/08/wsdl/soap12"
! wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP">
! <operation ref="tns:opCheckAvailability"
! wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response"/>
!
! <fault ref="tns:invalidDataFault"
! wsoap:code="soap:Sender"/>
</binding>
! <service name="reservationService"
! interface="tns:reservationInterface">
! <endpoint name="reservationEndpoint"
! binding="tns:reservationSOAPBinding"
! address ="http://greath.example.com/reservation"/>
</service>
! </description>
! ]]></eg>
</example></div2><div2><head>Getting Started: Defining the targetNamespace</head><p>Before writing our WSDL 2.0 document, we need to decide on a <code>targetNamespace</code> URI for it. The <code>targetNamespace</code> in WSDL 2.0 is analogous to a targetNamespace in XML Schema: interface, binding and service names that we define in our WSDL document will be associated with this <code>targetNamespace</code>, and thus will be distinguishable from similar names in a different <code>targetNamespace</code>. (This will become important if you use WSDL 2.0's <code>import</code> or interface inheritance mechanisms.) </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. (And if a WSDL description is split into multiple documents, then the <att>targetNamespace</att> should resolve to a mater document that includes all the WSDL documents needed for that service description.) However, there is no absolute requirement for this URI to be dereferenceable; thus a WSDL processor must not depend on it 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. Since GreatH will be the owner of the service, the targetNamespace URI should refer to a location on the GreatH Web site or otherwise within its control.</p><p>Once we have decided on a targetNamespace, we can begin our WSDL 2.0 document as the following empty shell.</p><example id="example-empty-shell">
<head>@example-empty-shell@ An Empty WSDL Document</head>
***************
*** 194,200 ****
. . . >
. . .
</description>]]></eg>
! </example><div3><head>Explanation of Example</head><p><glist><gitem><label><code><description</code></label><def><p>Every WSDL 2.0 document has a <code><description></code> element as its top-most element. This merely acts as a container for the rest of the WSDL 2.0 document, and is used to declare namespaces that will be used throughout the document.</p></def></gitem><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. Because we have not defined a prefix for it, any unprefixed elements or attributes are expected to be WSDL 2.0 elements or attributes (such as the <code><description></code> element).</p></def></gitem><gitem><label><code>targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"</code></label><def><p>This is the <code>targetNamespace</code> that we have chosen for the GreatH reservation service, as described above. Note that this is not an actual XML namespace declaration. Rather, it s a WSDL 2.0 attribute whose purpose is <emph>analogous</emph> to a targetNamespace in XML Schema.</p></def></gitem><gitem><label><code>xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"</code></label><def><p>This is an actual XML namespace declaration for use in our GreatH service description. Note that this is the same URI that was specified above for the <code>targetNamespace</code>. This will allow us later to use the <code>tns:</code> prefix in <xspecref href="@@xml-schema#qname@@">qnames</xspecref>, to refer to the targetNamespace of the GreatH service. </p></def></gitem></glist></p><p> Now we can start describing the GreatH service. </p></div3></div2><div2><head>Defining Message Types</head><p>We know that the GreatH service will be sending and receiving messages, so a good starting point in describing the service is to define the message types that the service will use. We'll use XML Schema to do so, because WSDL 2.0 requires all conformant WSDL processors to support XML Schema a a minimum. However, WSDL 2.0 does not prohibit the use of some other schema definition language.</p><p>WSDL 2.0 allows message types to be defined directly within the WSDL document, inside the <code><types></code> element, which is a child of the <code><description></code> element. (Later we'll see how we can provide the type definitions in a separate document, using XML Schema's <code><import></code> mechanism.) The following schema defines checkAvailability, checkAvailabilityResponse and invalidDataError message types that we'll need. </p><ednote><name>dbooth</name><edtext>@@ Do we really need to show how to use XML Schema import? @@</edtext></ednote><p>In WSDL 2.0, all normal and fault message types must be defined as single <emph>elements</emph> at the topmost level (though of course each element may have any amount of substructure inside it). Thus, a message type must not directly consist of a sequence of elements or other complex type. </p><example id="example-initial-types>
! <head>@example-initial-types@ GreatH Message Types</head>
<ednote><name>dbooth</name><edtext>@@ Not sure the namespace declarations and prefixes in this schema declaration are correct. In particular, check: xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns="http://greath.example.com/2004/schemas/resSvc.xsd"@@</edtext></ednote><eg><![CDATA[
--- 182,189 ----
. . . >
. . .
+
</description>]]></eg>
! </example><div3><head>Explanation of Example</head><p><glist><gitem><label><code><description</code></label><def><p>Every WSDL 2.0 document has a <code><description></code> element as its top-most element. This merely acts as a container for the rest of the WSDL 2.0 document, and is used to declare namespaces that will be used throughout the document.</p></def></gitem><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. Because we have not defined a prefix for it, any unprefixed elements or attributes are expected to be WSDL 2.0 elements or attributes (such as the <code><description></code> element).</p></def></gitem><gitem><label><code>targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"</code></label><def><p>This defines the <code>targetNamespace</code> that we have chosen for the GreatH reservation service, as described above. Note that this is not an actual XML namespace declaration. Rather it is a WSDL 2.0 attribute whose purpose is <emph>analogous</emph> to a targetNamespace in XML Schema.</p></def></gitem><gitem><label><code>xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"</code></label><def><p>This is an actual XML namespace declaration for use in our GreatH service description. Note that this is the same URI that was specified above for the <code>targetNamespace</code>. This will allow us later to use the <code>tns:</code> prefix in <xspecref href="@@xml-schema#qname@@">qnames</xspecref>, to refer to the targetNamespace of the GreatH service. </p></def></gitem></glist></p><p> Now we can start describing the GreatH service. </p></div3></div2><div2><head>Defining Message Types</head><p>We know that the GreatH service will be sending and receiving messages, so a good starting point in describing the service is to define the message types that the service will use. We'll use XML Schema to do so, because WSDL 2.0 requires all conformant WSDL processors to support XML Schma at a minimum. However, WSDL 2.0 does not prohibit the use of some other schema definition language.</p><p>WSDL 2.0 allows message types to be defined directly within the WSDL document, inside the <code><types></code> element, which is a child of the <code><description></code> element. (Later we'll see how we can provide the type definitions in a separate document, using XML Schema's <code><import></code> mechanism.) The following schema defines checkAvailability, checkAvailabilityResponse and invalidDataError message types that we'll need. </p><ednote><name>dbooth</name><edtext>@@ Do we really need to show how to use XML Schema import? @@</edtext></ednote><p>In WSDL 2.0, all normal and fault message types must be defined as single <emph>elements</emph> at the topmost level (though of course each element may have any amount of substructure inside it). Thus, a message type must not directly consist of a sequence of elements or other complex type. </p><example id="example-initial-ypes">
! <head>@example-initial-types@ The Initial GreatH Message Types</head>
<ednote><name>dbooth</name><edtext>@@ Not sure the namespace declarations and prefixes in this schema declaration are correct. In particular, check: xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns="http://greath.example.com/2004/schemas/resSvc.xsd"@@</edtext></ednote><eg><![CDATA[
***************
*** 231,235 ****
</description>]]></eg>
</example><div3><head>Explanation of Example</head><glist><gitem><label><code>xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"</code></label><def><p>We've added another namespace declaration. The <code>ghns</code> namespace prefix will allow us (later, when defining an interface) to reference the targetNamespace that we define for our message types. Thus, the URI we specify must be the same as the URI that we define as the targetNamespace of our XML Schema types (below) -- <emph>not</emph> the targetNamespace of the WSDL document itself.</p></def></gitem><gitem><label><code>targetNamespace="http://greath.example.com/2004/schemas/resSvc.xsd"</code></label><def><p>This is the XML Schema targetNamespace that we've created for use by the GreatH reservation service. The <code>checkAvailability</code>, <code>checkAvailability</code> and <code>invalidDataError</code> element names will be associated with this targetNamespace.</p></def></gitem><gitem><label><code>checkAvailability</code>,<code>checkAvailabilityResponse</code> and <code>invalidDataError</code></label><def><p>These are the message types that we'll use. Note that these are defined to be XML <emph>elements</emph>, as explained above.</p></def></gitem></glist><p>Although we have defined these types, we have not yet indicated that they are to be used specifically as message types for a Web service. We'll do that in the next section. </p></div3></div2><div2><head>Defining an Interface</head><p>Now we're ready to define the abstract interface of the GreatH service.</p><p>A WSDL 2.0 <code><interface></code> defines the abstract interface of a Web service as a set of abstract <emph>operations</emph>, 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 <emph>pattern</emph> that indicates the sequence in which the associated messages ae to be transmitted between the parties. For example, the <xspecref href="@@part2#in-out@@">in-out</xspecref> pattern indicates that if the client sends a message <emph>in</emph> to the service, the service will either send a reply message back <emph>out</emph> 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 <xspecref href="@@part2#in-out@@">in-out</xspecref> pattern for this operation, because this is the most natural way to represent a simple request-response interaction. We could have instead defined two separate operations using the <xspecref href="@@part2#in-only@@">in-only</xspecref> and <xspecref href="@@part2#out-only@@">out-only/xspecref> patterns (for example), 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 message exchange pattern of the operation. </p><p>Let's add these to our WSDL document.</p><example id="example-initial-interface">
! <head>@example-initial-interface@ The GreatH Interface</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
--- 220,224 ----
</description>]]></eg>
</example><div3><head>Explanation of Example</head><glist><gitem><label><code>xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"</code></label><def><p>We've added another namespace declaration. The <code>ghns</code> namespace prefix will allow us (later, when defining an interface) to reference the targetNamespace that we define for our message types. Thus, the URI we specify must be the same as the URI that we define as the targetNamespace of our XML Schema types (below) -- <emph>not</emph> the targetNamespace of the WSDL document itself.</p></def></gitem><gitem><label><code>targetNamespace="http://greath.example.com/2004/schemas/resSvc.xsd"</code></label><def><p>This is the XML Schema targetNamespace that we've created for use by the GreatH reservation service. The <code>checkAvailability</code>, <code>checkAvailability</code> and <code>invalidDataError</code> element names will be associated with this targetNamespace.</p></def></gitem><gitem><label><code>checkAvailability</code>,<code>checkAvailabilityResponse</code> and <code>invalidDataError</code></label><def><p>These are the message types that we'll use. Note that these are defined to be XML <emph>elements</emph>, as explained above.</p></def></gitem></glist><p>Although we have defined these types, we have not yet indicated that they are to be used specifically as message types for a Web service. We'll do that in the next section. </p></div3></div2><div2><head>Defining an Interface</head><p>Now we're ready to define the abstract interface of the GreatH service.</p><p>A WSDL 2.0 <code><interface></code> defines the abstract interface of a Web service as a set of abstract <emph>operations</emph>, 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 <emph>pattern</emph> that indicates the sequence in which the associated messages ae to be transmitted between the parties. For example, the <xspecref href="@@part2#in-out@@">in-out</xspecref> pattern indicates that if the client sends a message <emph>in</emph> to the service, the service will either send a reply message back <emph>out</emph> 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 <xspecref href="@@part2#in-out@@">in-out</xspecref> pattern for this operation, because this is the most natural way to represent a simple request-response interaction. We could have instead defined two separate operations using the <xspecref href="@@part2#in-only@@">in-only</xspecref> and <xspecref href="@@part2#out-only@@">out-only/xspecref> patterns (for example), 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 message exchange pattern of the operation. </p><p>Let's add these to our WSDL document.</p><example id="example-initial-interface">
! <head>@example-initial-interface@ The Initial GreatH Interface</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
***************
*** 273,282 ****
</interface>
. . .
! </description>]]></eg></example><div3><head>Explanation of Example</head><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><fault name = "invalidDataFault"
! </code></label><def><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></def></gitem><gitem><label><code>element = "ghns:invalidDataError"/></code></label><def><p>The <code>element</code> attribute specifies the schema type of the fault message, as previously defined in the <code><types></code> section. </p></def></gitem><gitem><label><code><operation name="opCheckAvailability"</code></label><def><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 unique within an interface. (WSDL 2.0 uses separate symbol spaces, so operation names are distinct from fault, message and interface names.)</p></def></gitem><gitem><label><code>pattern="http://www.w3.org/2004/03/wsdl/in-out" ></code></label><def><p>This line speifies that this operation will use the <xspecref href="@@part2#in-out@@">in-out</xspecref> pattern defined in <xspecref href="@@part2@@">WSDL 2.0 Part 2</xspecref>. 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 <emph>not</emph> 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></def></gitem><gitem><label><code><input messageLabel="In"</code></label><def><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 ad/or output messages. Thus we must also indicate which potential input message in the pattern this particular input message represents. This is the purpose of the <code>messageLabel</code> attribute. Since the WSDL 2.0 <xspecref href="@@part2#in-out@@">in-out</xspecref> pattern that we've chosen to use only has one input message, it is a no-brainer in this case: we simply fill in the message label "In" that was defined in <xspecref href="@@Part2@@">WSDL 2.0 Part 2</xspecref> for the <xspecref href="@@part2#in-out@@">in-out</xspecref> 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></def></gitem><gitem><label><code>element="ghns:checkAvailability" /></code></label><def><p>This specifies the message type for this input message, as defined previously in the <code><types></code> section.</p></def></gitem><gitem><label><code><output messageLabel="ut" . . .</code></label><def><p>This is similar to defining an input message.</p></def></gitem><gitem><label><code><outfault ref="tns:invalidDataFault" messageLabel="Out"/></code></label><def><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 replace, depending on the pattern. (Some patterns use a <xspecref href="@@part2#message-triggers-fault@@">mesage-triggers-fault rule</xspecref>; others use a <xspecref href="@@part2#fault-replaces-message@@">fault-replaces-message</xspecref> rule.) </p></def></gitem></glist><p>Now that we've defined the abstract interface for the GreatH service, we're ready to define a binding for it.</p></div3></div2>
! <div2><head>Defining a Binding</head><p>@@</p><ednote><name>dbooth</name><edtext>[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. </edtext></ednote><p> Although we have specified <emph>what</emph> abstract messages can be exchanged with the GreatH Web service, we have not yet specified <emph>how</emph> those messages can be exchanged. This is the purpose of a <el>binding</el>. A <el>binding</el> specifies a concrete message format and transmission protocol for one or more <el>interfaces</el>. </p><p>Because WSDL 2.0 anticipates the need for new kinds of message formats and transmission protocols, the mechanism that is used to define a binding isextensible. WSDL 2.0 Part 3 predefines binding constructs for SOAP 1.2 <bibref ref="SOAP12-PART1"/> and HTTP 1.1 <bibref ref="RFC2616"/>, so that SOAP 1.2 or HTTP 1.1 bindings can be easily defined. 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, though.) </p><p>For the GreatH service, we will use SOAP 1.2 as our concrete message format and HTTP 1.1 as our transmission protocol, as shown below. </p><example id="example-initial-binding">
! <head>@example-initial-binding@ The GreatH Binding</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
<description
--- 262,271 ----
</interface>
. . .
! </description>]]></eg></example><div3><head>Explanation of Example</head><glist><gitem><label><code><interface name = "reservation" ></code></label><def><p>Interfaces are declared directly inside the <el><description></el> 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 targetNamespace. Interface names are tokens that must not contain a space or colon (":").</p></def></gitem><gitem><label><code><fault name = "invalidDataFault"
! </code></label><def><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></def></gitem><gitem><label><code>element = "ghns:invalidDataError"/></code></label><def><p>The <code>element</code> attribute specifies the schema type of the fault message, as previously defined in the <code><types></code> section. </p></def></gitem><gitem><label><code><operation name="opCheckAvailability"</code></label><def><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></def></gitem><gitem><label><code>pattern="http://www.w3.org/2004/03/wsdl/in-out" ></code></label><df><p>This line specifies that this operation will use the <xspecref href="@@part2#in-out@@">in-out</xspecref> pattern defined in <xspecref href="@@part2@@">WSDL 2.0 Part 2</xspecref>. 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 <emph>not</emph> 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></def></gitem><gitem><label><code><input messageLabel="In"</code></label><def><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 f multiple input and/or output messages. Thus we must also indicate which potential input message in the pattern this particular input message represents. This is the purpose of the <code>messageLabel</code> attribute. Since the WSDL 2.0 <xspecref href="@@part2#in-out@@">in-out</xspecref> pattern that we've chosen to use only has one input message, it is a no-brainer in this case: we simply fill in the message label "In" that was defined in <xspecref href="@@Part2@@">WSDL 2.0 Part 2</xspecref> for the <xspecref href="@@part2#in-out@@">in-out</xspecref> 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></def></gitem><gitem><label><code>element="ghns:checkAvailability" /></code></label><def><p>This specifies the message type for this input message, as defined previously in the <code><types></code> section.</p></def></gitem><gitem><label><code><ouput messageLabel="Out" . . .</code></label><def><p>This is similar to defining an input message.</p></def></gitem><gitem><label><code><outfault ref="tns:invalidDataFault" messageLabel="Out"/></code></label><def><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 replace, depending on the pattern. (Some patterns use a <xspecref href="@@part2#message-trggers-fault@@">message-triggers-fault rule</xspecref>; others use a <xspecref href="@@part2#fault-replaces-message@@">fault-replaces-message</xspecref> rule.) </p></def></gitem></glist><p>Now that we've defined the abstract interface for the GreatH service, we're ready to define a binding for it.</p><ednote><name>dbooth</name><edtext>[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. </edtext></ednote></div3></div2>
! <div2><head>Defining a Binding</head><p> Although we have specified <emph>what</emph> abstract messages can be exchanged with the GreatH Web service, we have not yet specified <emph>how</emph> those messages can be exchanged. This is the purpose of a <emph>binding</emph>. 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 <el><operation></el> and <el><fault></el> elements inside a <el><binding></el> 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 @@@@.) </p><p>In order to accommodate new kinds of message formats and transmission protocols, bindings are defined using extensions to the WSDL 2.0 langage, via WSDL 2.0's open content model. WSDL 2.0 Part 3 defines binding constructs for SOAP 1.2 <bibref ref="SOAP12-PART1"/> and HTTP 1.1 <bibref ref="RFC2616"/> 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><example id="example-initial-binding">
! <head>@example-initial-binding@ The Initial GreatH Binding</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
<description
***************
*** 287,294 ****
xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"
xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
! . . .
<interface name = "reservationInterface" >
! . . .
</interface>
--- 276,294 ----
xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"
xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
!
! <types>
! . . .
! </types>
<interface name = "reservationInterface" >
!
! <fault name = "invalidDataFault"
! element = "ghns:invalidDataError"/>
!
! <operation name="opCheckAvailability"
! pattern="http://www.w3.org/2004/03/wsdl/in-out" >
! . . .
! </operation>
!
</interface>
***************
*** 296,309 ****
interface="tns:reservationInterface"
type="http://www.w3.org/2004/08/wsdl/soap12"
! wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP"
! wsoap:mepDefault="http://www.w3.org/2003/05/soap/mep/request-response">
! <fault ref="tns:invalidDataFault" wsoap:code="soap:Sender"/>
</binding>
. . .
</description>]]></eg>
! </example><div3><head>Explanation of Example</head><glist><gitem><label><code>xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"</code></label><def><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 <bibref ref="SOAP12-PART1"/>. Elements and attributes prefixed with <code>wsoap:</code> are constructs defined there. </p></def></gitem><gitem><label><code>xmlns:soap="http://www.w3.org/2003/05/soap-envelope"</code></label><def><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></def></gitem><gitem><label><code>@@</code></label><def><p>@@</p></def></gitem><gitem><label><code>@@</code></label><def><p>@@</p></def></gitem></glist><p>@@</p></div3></div2><div2><head>@@@@@@@@@@</head><>@@</p><example id="example-foo">
<head>@example-foo@ @@Title@@</head>
<eg><![CDATA[@@]]></eg>
--- 296,362 ----
interface="tns:reservationInterface"
type="http://www.w3.org/2004/08/wsdl/soap12"
! wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP">
!
! <operation ref="tns:opCheckAvailability"
! wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response"/>
! <fault ref="tns:invalidDataFault"
! wsoap:code="soap:Sender"/>
</binding>
. . .
+ </description>]]></eg>
+ </example><div3><head>Explanation of Example</head><glist><gitem><label><code>xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"</code></label><def><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 <bibref ref="SOAP12-PART1"/>. Elements and attributes prefixed with <code>wsoap:</code> are constructs defined there. </p></def></gitem><gitem><label><code>xmlns:soap="http://www.w3.org/2003/05/soap-envelope"</code></label><def><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></def></gitem><gitem><label><code><binding name="reservationSOAPBinding"</code></label><def><p>Bindings are declared directly inside the <el><description></el> element. The <att>name</att> attribte defines a name for this binding. Each name must be unique among all bindings in this targetNamespace, 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></def></gitem><gitem><label><code>interface="tns:reservationInterface"</code></label><def><p>This is the name of the interface whose message format and transmission protocols we are specifying. As discussed @later@, a reusable binding can be defined by omitting the <att>interface</att> attribute. Note also the use of the <code>tns:</code> prefix, which refers to the previously defined targetNamespace for this WSDL document. In this case it may seem silly to have to specify the tns: prefix, but @we will see later@ how WSDL 2.0's import mechanism can be used to combine components that are defined in different targetNamespaces.</p></def></gitem><gitem><label><code>type"http://www.w3.org/2004/08/wsdl/soap12"</code></label><def><p>This specifies the type of concrete message format to use, in this case SOAP 1.2.</p></def></gitem><gitem><label><code>wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP"</code></label><def><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></def></gitem><gitem><label><code><operation ref="tns:opCheckAvailability"</code></label><def><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 @@@@.)</p></def></gitem><gitem><label><code>wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response"></code></label><def><p>This attribute is also specific to WSDL 2.0' SOAP binding. It specifies the SOAP message exchange pattern that will be used to implement the abstract WSDL 2.0 message exchange pattern (<xspecref href="@@part2#in-out@@">in-out</xspecref>) that was specified when the <code>opCheckAvailability</code> operation was defined. </p></def></gitem><gitem><label><code><fault ref="tns:invalidDataFault"</code></label><def><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></def></gitem><gitem><label><code>wsoap:code="soap:Sender"/></code></label><def><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. @@ Need to verify that this is correct. @@ If desired, an list of subcodes can also be specified using the optional <att>wsoap:subcodes</att> attibute.</p></def></gitem></glist></div3></div2><div2><head>Defining a Service</head><p>Now that our binding has specified <emph>how</emph> messages will be transmitted, we are ready to specify <emph>where</emph> the service can be accessed, by use of the <el><service></el> element. </p><p>A WSDL 2.0 <emph>service</emph> specifies a single interface that the service will support, and a list of <emph>endpoint</emph> 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 you from declaring multiple services that use different interfaces but happen to use the same endpoint address.) </p><p>Here is a definition for our GreatH service.</p><example id="example-initial-service">
+ <head>@example-initial-service@ The Initial GreatH Service</head>
+ <eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
+ <description
+ xmlns="http://www.w3.org/2004/08/wsdl"
+ targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
+ xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl" . . . >
+
+ <types>
+ . . .
+ </types>
+
+ <interface name = "reservationInterface" >
+ . . .
+ </interface>
+
+ <binding name="reservationSOAPBinding"
+ interface="tns:reservationInterface" . . . >
+ . . .
+ </binding>
+
+ <service name="reservationService"
+ interface="tns:reservationInterface">
+
+ <endpoint name="reservationEndpoint"
+ binding="tns:reservationSOAPBinding"
+ address ="http://greath.example.com/2004/reservation"/>
+
+ </service>
</description>]]></eg>
! </example><div3><head>Explanation of Example</head><glist><gitem><label><code><service name="reservationService"</code></label><def><p>This defines a name for this service, which must be unique among service names in the current targetNamespace. @Say why it's required.@<ednote><name>dbooth</name><edtext>Anyone remember why we made the name attribute required? Does WSDL 2.0 use it anywhere?</edtext></ednote></p></def></gitem><gitem><label><code>interface="tns:reservationInterface"></code></label><def><p>This specifies the name of the previously defined interface that these service endpoints will support. </p></def></gitem><gitem><label><code><endpoint name="reservationEndpoint"</code></label><def><p>This defines an endpoint for the service, and a name for this endpoint, which must be unique within this service. @Say why the name is required.@ <ednote><name>dbooth</name><edtext>Anyone remember why we made the name attribute required? Does WSDL 2.0 use it anywhere?</edtext></ednote></p></ef></gitem><gitem><label><code>binding="tns:reservationSOAPBinding"</code></label><def><p>This specifies the name of the previously defined binding to be used by this endpoint. </p></def></gitem><gitem><label><code>address ="http://greath.example.com/2004/reservation"/></code></label><def><p>This specifies the physical address at which this service can be accessed using the binding specified by the <att>binding</att> attribute.</p></def></gitem></glist><p>That's it! Well, almost. </p></div3></div2><div2><head>Documenting the Service</head><p>As we have seen, a WSDL 2.0 document is inherently only a <emph>partial</emph> description of a service. Although it captures the basic mechanics of interacting with the service -- the message types, transmission protocols, service location, etc. -- in general, additional documention will need to explain other application-level requirements for its use. For example, such documentation should explain the purpose and use of the service, the meanings of all message, constraints on their use, and the sequence in which operations should be invoked.</p><p>The <el><documentation></el> element allows you to include some human-readable documentation inside your WSDL document. It is a convenient place to reference any additional documentation that a client developer may need in order to use your service.</p><example id="example-initial-documentation">
! <head>@example-initial-documentation@ Documenting the GreatH Service</head>
! <eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
! <description
! . . . >
!
! <documentation>
! This document describes the GreatH Web service. Additional
! application-level requirements for its use of this service --
! beyond what WSDL 2.0 is able to describe -- are available
! at http://greath.example.com/2004/reservation-documentation.html
! </documentation>
!
! <types>
! . . .
! </types>
!
! . . .
!
! </description>]]></eg>
! </example><div3><head>Explanation of Example</head><glist><gitem><label><code><documentation></code></label><def><p> This element is optional, but a good idea to include. It can contain arbitrary mixed content. </p></def></gitem><gitem><label><code>at http://greath.example.com/2004/reservation-documentation.html</code></label><def><p>The most important thing to include is a pointer to any additional documentation that a client developer would need in order to use your service. </p></def></gitem></glist></div3></div2><div2><head>@@@@@@@@@@</head><p>@@</p><example id="example-foo">
<head>@example-foo@ @@Title@@</head>
<eg><![CDATA[@@]]></eg>
***************
*** 318,322 ****
>
. . .
! </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/schemas/resSvc.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/wsdl/resSvc.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 such 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 URI being dereferenceable.) </><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/wsdl/resSvc.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 be used later, when we need to refer to an iterface, operation, binding or service that we have defined within our targetNamespace. </p></def></gitem></glist></p><div3><head>Explanation of Example</head></div3></div2><div2 id="overview">
<head>WSDL 2.0 Extensibility</head>
--- 371,375 ----
>
. . .
! </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 transmission protocol that the GreatH Web service supports.</p></def></gitem><gitem><label><code>xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/oap12"</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/schemas/resSvc.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/wsdl/resSvc.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 such as <code><interfacegt;</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 URI 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/wsdl/resSvc.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 be used later, when we need to refer to a interface, operation, binding or service that we have defined within our targetNamespace. </p></def></gitem></glist></p><div3><head>Explanation of Example</head></div3></div2><div2 id="overview">
<head>WSDL 2.0 Extensibility</head>
Received on Monday, 13 December 2004 22:14:24 UTC