- From: David Booth <dbooth@dev.w3.org>
- Date: Sat, 11 Dec 2004 23:21:13 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20
In directory hutz:/tmp/cvs-serv2898
Modified Files:
wsdl20-primer.xml
Log Message:
Restructured. Lots of changes. Still working on it, but wanted
to commit a copy for safety.
Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.18
retrieving revision 1.19
diff -C2 -d -r1.18 -r1.19
*** wsdl20-primer.xml 28 Oct 2004 02:53:48 -0000 1.18
--- wsdl20-primer.xml 11 Dec 2004 23:21:11 -0000 1.19
***************
*** 39,44 ****
</authlist>
<abstract id="Abstract">
! <p>This document introduces the Web Services Description Language, version 2.0 (WSDL 2.0). It is intended as a companion to the official WSDL 2.0 specification, for readers who wish to have an easier, less technical introduction to the main features of the language than the official specification provides. </p>
! <p>This primer is <emph>non-normative</emph>. Any specific questions of what WSDL 2.0 requires or forbids should be referred to the WSDL 2.0 specification (@@reference@@).</p>
</abstract>
&status;
--- 39,44 ----
</authlist>
<abstract id="Abstract">
! <p>This document introduces the Web Services Description Language, version 2.0 (WSDL 2.0). It is intended as a companion to the official WSDL 2.0 specification, for readers who wish to have an easier, less technical introduction to the main features of the language. </p><p>This primer is only intended to be a starting point toward use of WSDL 2.0. Hence, it does not intend to describe all features of the language. Users are expected to consult the WSDL 2.0 specification if they wish to make use of more sophisticated features.</p>
! <p>Finally, this primer is <emph>non-normative</emph>. Any specific questions of what WSDL 2.0 requires or forbids should be referred to the WSDL 2.0 specification (@@reference@@).</p>
</abstract>
&status;
***************
*** 64,68 ****
<div2 id="PrimerStructure">
<head>Structure of the Primer</head>
! <p>@@ToDo: Update this@@</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>
--- 64,70 ----
<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>
***************
*** 75,79 ****
"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
--- 77,81 ----
"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 standards, 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
***************
*** 90,94 ****
<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" ?>
--- 92,96 ----
<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" ?>
***************
*** 97,109 ****
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>
! <xs:schema targetNamespace="http://greath.example.com/2004/05/schemas/reservationService.xsd"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
! xmlns="http://greath.example.com/2004/05/schemas/reservationService.xsd">
<xs:element name="checkAvailability" type="tCheckAvailability"/>
--- 99,111 ----
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"/>
***************
*** 174,178 ****
</binding>
! <service name="reservationService" interface="tns:reservation">
<endpoint name="reservationEndpoint"
--- 176,180 ----
</binding>
! <service name="resSvc" interface="tns:reservation">
<endpoint name="reservationEndpoint"
***************
*** 183,247 ****
</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"
! 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"
! >
! . . .
! </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"
! xmlns:xs="http://www.w3.org/2001/XMLSchema"
! xmlns="http://greath.example.com/2004/05/schemas/reservationService.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="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>
! . . .
! ]]></eg><p>Although these lines have defined the schemas for checkAvailability, checkAvailabilityResponse, and invalidDataError elements, these element definitions have not yet been associated with any particular operation in the GreatH interface. That will be done later, when we define the CheckAvailability operation. </p><p>Note also that checkAvailability, checkAvailabilityResponse, and invalidDataError are all defined to be XML <emph>elements</emph>. This is because WSDL 2.0 requires that every message type MUST be an XML element at the topmost level; i.e., it cannot be a simple data type or sequence directly. Furthermore, although these type definitions are textually embedded within the WSDL document in this example, they could instead be defined in a separate document that is <emph>included</emph> by the WSDL document, as described in section @types-include@. </p><p>Finally, although WSDL 2.0 requires WSDL processors to support XML Schema at a minimum, the use of other schema definitionlanguages is permitted.</p></div2>
!
! <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"
--- 185,266 ----
</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>
! <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"
! . . . >
! . . .
! </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[
! <?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"
! . . . >
!
<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>
! . . .
! </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" ?>
! <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"
! . . . >
!
! <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: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"
***************
*** 249,257 ****
<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>
--- 268,322 ----
<output messageLabel="Out"
element="ghns:checkAvailabilityResponse" />
! <outfault ref="tns:invalidDataFault" messageLabel="Out"/>
</operation>
</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
! 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">
! . . .
!
! <interface name = "reservationInterface" >
! . . .
! </interface>
!
! <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"
! 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>
! </example><div3><head>Explanation of Example</head><glist><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><gitem><label><code>@@</code></label><def><p>@@</p></def></gitem></glist><p>@@</p></div3></div2><div2><head>Namespaces</head><p>In <loc href="#example-initial">@example-initial@</loc> above, we declared several namespaces.</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"
! 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"
! >
! . . .
! </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>
***************
*** 413,417 ****
<p>An optional <el>documentation</el> element is also allowed inside any WSDL element as a container for human readable and/or machine processable documentation. The content of <el>documentation</el> is arbitrary characters and elements
! ("mixed" content in XML Schema ). </p><!-- ******* dbooth stopped here ***** --><!-- ************************ targetNamespace *************************** --><div3><head>Target Namespace and Symbol Spaces</head><p>All WSDL documents start with a <el>definitions</el> element. The <el>definitions</el> element has a required <att>targetNamespace</att> attribute and zero or more namespace declarations.The vaule of the <att>targetNamespace</att> must be an absolute URI which unambiguously identifies the set of related WSDL and data type constructs logically grouped by the <el>definitions</el> element. </p>
<p>We will talk about later the flexible authoring style enabled by the importing/including mechanism of WSDL, but it's worth pointing out now that at the component model level, there is no distinction between directly defined components vs. imported/included
components. The <att>targetNamespace</att> groups a set of related component definitions and represents an unambiguous name for the intended semantics of the components. The components directly defined within or included into a single Definitions component are
--- 478,482 ----
<p>An optional <el>documentation</el> element is also allowed inside any WSDL element as a container for human readable and/or machine processable documentation. The content of <el>documentation</el> is arbitrary characters and elements
! ("mixed" content in XML Schema ). </p><!-- ******* dbooth stopped here ***** --><!-- ************************ targetNamespace *************************** --><div3><head>Target Namespace and Symbol Spaces</head><p>All WSDL documents start with a <el>definitions</el> element. The <el>definitions</el> element has a required <att>targetNamespace</att> attribute and zero or more namespace declarations.The value of the <att>targetNamespace</att> must be an absolute URI which unambiguously identifies the set of related WSDL and data type constructs logically grouped by the <el>definitions</el> element. </p>
<p>We will talk about later the flexible authoring style enabled by the importing/including mechanism of WSDL, but it's worth pointing out now that at the component model level, there is no distinction between directly defined components vs. imported/included
components. The <att>targetNamespace</att> groups a set of related component definitions and represents an unambiguous name for the intended semantics of the components. The components directly defined within or included into a single Definitions component are
***************
*** 430,441 ****
<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>
<eg>
! <xs:schema targetNamespace="http://www.greath.com/2004/05/schemas/reservationService.xsd"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
! xmlns="http://www.greath.com/2004/05/schemas/reservationService.xsd">
<xs:element name="checkAvailability" type="tCheckAvailability"/>
--- 495,506 ----
<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 specify 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 we 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>
<eg>
! <xs:schema targetNamespace="http://www.greath.com/2004/05/schemas/resSvc.xsd"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
! xmlns="http://www.greath.com/2004/05/schemas/resSvc.xsd">
<xs:element name="checkAvailability" type="tCheckAvailability"/>
***************
*** 501,505 ****
<div3 id="import-xsd">
<head>Importing XML Schema</head>
! <p>Let's exame the XML Schema <el>import</el> first. Note the schema import mechanism described here is defined in XML Schema Language with some additional restrictions. It is different from the WSDL import/include as explained in section @@@@. The schema components defined in the imported schema are available for reference by QName (see section @@@@ ). Note that only components defined in the schema itself and components included by it via <el>xs:include</el> are available to WSDL. Specifically, components that the schema imports via <el>xs:import</el> are NOT available to WSDL.</p>
<p>A <el>types</el> element can contain zero or more <el>import</el>s which may have one or two attributes as follows:</p>
<ulist>
--- 566,570 ----
<div3 id="import-xsd">
<head>Importing XML Schema</head>
! <p>Let's examine the XML Schema <el>import</el> first. Note the schema import mechanism described here is defined in XML Schema Language with some additional restrictions. It is different from the WSDL import/include as explained in section @@@@. The schema components defined in the imported schema are available for reference by QName (see section @@@@ ). Note that only components defined in the schema itself and components included by it via <el>xs:include</el> are available to WSDL. Specifically, components that the schema imports via <el>xs:import</el> are NOT available to WSDL.</p>
<p>A <el>types</el> element can contain zero or more <el>import</el>s which may have one or two attributes as follows:</p>
<ulist>
***************
*** 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>
--- 622,626 ----
</item>
</ulist>
! <p>After looking 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 to be available for other purposes. So we write down the following WSDL to summarize what we have so far:</p>
<example>
<head>Importing message definitions into WSDL</head>
***************
*** 563,568 ****
<definitions
! targetNamespace= "http://www.greath.com/2004/05/wsdl/reservationService.wsdl"
! xmlns:ghns = "http://www.greath.com/2004/05/schemas/reservationService.xsd"
xmlns = "http://www.w3.org/@@@@/@@/wsdl"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
--- 628,633 ----
<definitions
! targetNamespace= "http://www.greath.com/2004/05/wsdl/resSvc.wsdl"
! xmlns:ghns = "http://www.greath.com/2004/05/schemas/resSvc.xsd"
xmlns = "http://www.w3.org/@@@@/@@/wsdl"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
***************
*** 579,584 ****
</documentation>
! <xs:import namespace="http://www.greath.com/2004/05/schemas/reservationService.xsd"
! schemaLocation= "http://www.greath.com/2004/05/schemas/reservationService.xsd"/>
</<b>types</b>>
--- 644,649 ----
</documentation>
! <xs:import namespace="http://www.greath.com/2004/05/schemas/resSvc.xsd"
! schemaLocation= "http://www.greath.com/2004/05/schemas/resSvc.xsd"/>
</<b>types</b>>
***************
*** 598,602 ****
operations. Before we dive into details of interface defintion, we need to first understand what a WSDL message exchange pattern (MEP) is since they define the sequence and cardinality of abstract messages listed in an operation.</p>
<p>In a nutshell, MEPs define two things: the sequence and cardinality of abstract messages listed in an operation, and which other nodes send messages to, and receive messages from, the service implementing the operation.</p>
! <p>By design, WSDL MEPs are abstract. First of all, they abstract out specific message types. MEPs identify placeholders for messages, and placeholders are associated with specific message types by the operation using the MEP. Secondly, unless explicitly stated otherwise, MEPs also abstract out binding-specific information like timing between messages, whether the pattern is synchronous or asynchronous, and whether the message are sent over a single or multiple channels.</p>
<p>It's worth pointing out that like interfaces and operations, WSDL MEPs do not exhaustively describe the set of messages exchanged between a service and other
nodes; by some prior agreement, another node and/or the service may send other
--- 663,667 ----
operations. Before we dive into details of interface defintion, we need to first understand what a WSDL message exchange pattern (MEP) is since they define the sequence and cardinality of abstract messages listed in an operation.</p>
<p>In a nutshell, MEPs define two things: the sequence and cardinality of abstract messages listed in an operation, and which other nodes send messages to, and receive messages from, the service implementing the operation.</p>
! <p>By design, WSDL MEPs are abstract. First of all, they abstract out specific message types. MEPs identify placeholders for messages, and placeholders are associated with specific message types by the operation using the MEP. Secondly, unless explicitly stated otherwise, MEPs also abstract out binding-specific information like timing between messages, whether the pattern is synchronous or asynchronous, and whether the messages are sent over a single or multiple channels.</p>
<p>It's worth pointing out that like interfaces and operations, WSDL MEPs do not exhaustively describe the set of messages exchanged between a service and other
nodes; by some prior agreement, another node and/or the service may send other
***************
*** 618,622 ****
<p>
<b>Robust In-Only</b> ("http://www.w3.org/2004/03/wsdl/robust-in-only")</p>
! <p>This pattern can be considered as a variation of In-only. It aslo consists of exactly one message received by a service, but in this case faults can be triggered by the message as specified in the "Message Triggers Fault" model. </p>
</item>
<item>
--- 683,687 ----
<p>
<b>Robust In-Only</b> ("http://www.w3.org/2004/03/wsdl/robust-in-only")</p>
! <p>This pattern can be considered as a variation of In-only. It also consists of exactly one message received by a service, but in this case faults can be triggered by the message as specified in the "Message Triggers Fault" model. </p>
</item>
<item>
***************
*** 631,635 ****
</item>
</ulist>
! <p>WSDL2.0 also defines four out-bound MEPs which sort of mirroring the in-bound MEPs with reserved direction:</p>
<ulist>
<item>
--- 696,700 ----
</item>
</ulist>
! <p>WSDL2.0 also defines four out-bound MEPs which sort of mirror the in-bound MEPs with reserved direction:</p>
<ulist>
<item>
***************
*** 641,645 ****
<p>
<b>Robust Out-Only</b> ("http://www.w3.org/2004/03/wsdl/robust-out-only")</p>
! <p>This pattern can be considered as a variation of Out-only. It aslo consists of exactly one message sent to some other node from a service, but in this case faults can be triggered by the message as specified in the "Message Triggers Fault" model. </p>
</item>
<item>
--- 706,710 ----
<p>
<b>Robust Out-Only</b> ("http://www.w3.org/2004/03/wsdl/robust-out-only")</p>
! <p>This pattern can be considered as a variation of Out-only. It also consists of exactly one message sent to some other node from a service, but in this case faults can be triggered by the message as specified in the "Message Triggers Fault" model. </p>
</item>
<item>
***************
*** 654,658 ****
</item>
</ulist>
! <p>While the in-bound MEPs are easier to understand, there have been questions concerning the usefulness of out-bound MEPs, especially how a service can specify the endpoint information for the target node of the initial out-bound message. In their typical use cases, such as in large scale intergration projects where endpoint information is most likely specified at deployment or runtime by mapping and routing facilities, or/and in languages that facilitate services composition where only abstract interfaces are concerned, Out-bound MEPs are useful in the abstract level for fully specifying the functionality of a service, including its requirements for its potential customers, so application integrator can gain a better understanding of how multiple services may be used together, wherea binding and endpoint information may be provided by integration infrastructure in application deployment and runtime.</p>
<ednote>
<name>KevinL</name>
--- 719,723 ----
</item>
</ulist>
! <p>While the in-bound MEPs are easier to understand, there have been questions concerning the usefulness of out-bound MEPs, especially how a service can specify the endpoint information for the target node of the initial out-bound message. In their typical use cases, such as in large scale intergration projects where endpoint information is most likely specified at deployment or runtime by mapping and routing facilities, or/and in languages that facilitate services composition where only abstract interfaces are concerned, Out-bound MEPs are useful in the abstract level for fully specifying the functionality of a service, including its requirements for its potential customers, so application integrator can gain a better understanding of how multiple services may be used together, whereas binding and endpoint information may be provided by integration infrastructure in application deployment and runtime.</p>
<ednote>
<name>KevinL</name>
***************
*** 761,765 ****
<head>Reusable Faults</head>
<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>
--- 826,830 ----
<head>Reusable Faults</head>
<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 value 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>
***************
*** 768,773 ****
<definitions
! targetNamespace= "http://www.greath.com/2004/05/wsdl/reservationService.wsdl"
! xmlns:ghns = "http://www.greath.com/2004/05/schemas/reservationService.xsd"
xmlns = "http://www.w3.org/@@@@/@@/wsdl"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
--- 833,838 ----
<definitions
! targetNamespace= "http://www.greath.com/2004/05/wsdl/resSvc.wsdl"
! xmlns:ghns = "http://www.greath.com/2004/05/schemas/resSvc.xsd"
xmlns = "http://www.w3.org/@@@@/@@/wsdl"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
***************
*** 781,786 ****
<types>
! <xs:import namespace="http://www.greath.com/2004/05/schemas/reservationService.xsd"
! schemaLocation= "http://www.greath.com/2004/05/schemas/reservationService.xsd"/>
</types>
--- 846,851 ----
<types>
! <xs:import namespace="http://www.greath.com/2004/05/schemas/resSvc.xsd"
! schemaLocation= "http://www.greath.com/2004/05/schemas/resSvc.xsd"/>
</types>
***************
*** 850,855 ****
</item>
</ulist>
! <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>
--- 915,920 ----
</item>
</ulist>
! <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 value must match the name of the MEP place holder message. Note that 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 a 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>
***************
*** 857,862 ****
<eg xml:space="preserve">
<definitions
! targetNamespace= "http://www.greath.com/2004/05/wsdl/reservationService.wsdl"
! xmlns:ghns = "http://www.greath.com/2004/05/schemas/reservationService.xsd"
xmlns = "http://www.w3.org/@@@@/@@/wsdl"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
--- 922,927 ----
<eg xml:space="preserve">
<definitions
! targetNamespace= "http://www.greath.com/2004/05/wsdl/resSvc.wsdl"
! xmlns:ghns = "http://www.greath.com/2004/05/schemas/resSvc.xsd"
xmlns = "http://www.w3.org/@@@@/@@/wsdl"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
***************
*** 870,875 ****
<types>
! <xs:import namespace="http://www.greath.com/2004/05/schemas/reservationService.xsd"
! schemaLocation= "http://www.greath.com/2004/05/schemas/reservationService.xsd"/>
</types>
--- 935,940 ----
<types>
! <xs:import namespace="http://www.greath.com/2004/05/schemas/resSvc.xsd"
! schemaLocation= "http://www.greath.com/2004/05/schemas/resSvc.xsd"/>
</types>
***************
*** 919,929 ****
<div1 id="binding">
<head>Binding Abstract Interface to Concrete Protocols </head>
! <p> An <el>interface</el> describes sequences of abstract messages that a service sends and/or receives, but it does not specify how that messages are exchanged. The "how" aspect is where the <el>binding</el> construct comes to the picture. A <el>binding</el> describes a concrete message format and transmission protocol for one or more interfaces. </p>
<p>A <el>binding</el> can be defined for different levels of reusability. It can be used to describe binding information in a re-usable manner for any
interface or specifically for a given interface. Furthermore,
! binding information MAY be specified on a per-operation basis
! (see @@@@) within an
! interface in addition to across all operations of an
! interface. If a <el>binding</el> specifies any operation-specific
binding details or any fault binding details, then it MUST specify an interface the binding information applies to, so as to indicate which interface the operations come from.Conversely, a <el>binding</el> which omits any
operation-specific binding details and any fault binding details
--- 984,992 ----
<div1 id="binding">
<head>Binding Abstract Interface to Concrete Protocols </head>
!
<p>A <el>binding</el> can be defined for different levels of reusability. It can be used to describe binding information in a re-usable manner for any
interface or specifically for a given interface. Furthermore,
! binding information MAY be specified on a per-operation basis if needed.
! If a <el>binding</el> specifies any operation-specific
binding details or any fault binding details, then it MUST specify an interface the binding information applies to, so as to indicate which interface the operations come from.Conversely, a <el>binding</el> which omits any
operation-specific binding details and any fault binding details
***************
*** 931,935 ****
specify an interface MAY be used to specify
operation-independent binding details for Service components
! with different interfaces. That is, such <el>binding</el> are
reusable across one or more interfaces.</p>
<p>A <el>binding</el> tied to a particular interface
--- 994,998 ----
specify an interface MAY be used to specify
operation-independent binding details for Service components
! with different interfaces. That is, such <el>bindings</el> are
reusable across one or more interfaces.</p>
<p>A <el>binding</el> tied to a particular interface
***************
*** 940,946 ****
listing each operation of the interface and
defining bindings for them. Thus, it is an error for a <el>binding</el> to not define bindings for all the operations of the corresponding interface.</p>
! <p>The binding constructs can be grouped in two categories: those in the WSDL namespace of "http://www.w3.org/@@@@/@@/wsdl" and those not in WSDL namespace. WSDL 2.0 part 1 defines a set of binding constructs within the WSDL namespace which can be used to host binding detail definitions. Constructs for defining binding details are defined within their own namespaces which must be different from the WSDL namespace. For example, WSDL 2.0 part 3 defines constructs for defining binding details for SOAP 1.2 in the namespace of "http://www.w3.org/@@@@/@@/wsdl/soap12" <bibref ref="SOAP12-PART1"/> and HTTP in the namespace of "http://www.w3.org/@@@@/@@/wsdl/http" <bibref ref="RFC2616"/>. Additional binding detail constructs can be defined for other protocols by other specifications. All these binding detail constructs are defined outside WSDL namespace, and are typically used as extensions of the hosting WSDL binding constructs. The the following sections, we will introduce the hosting WSDL binding constructsfirst, and then move on the the binding extensions.
! </p>
! <div2 id="WSDLbindingConstructs">
<head>Binding Constructs in WSDL Namespace</head>
<p>Let's have a look at the constructs defined within the WSDL namespace first. The XML syntax of these constructs is summarized below:</p>
--- 1003,1008 ----
listing each operation of the interface and
defining bindings for them. Thus, it is an error for a <el>binding</el> to not define bindings for all the operations of the corresponding interface.</p>
! <p>The binding constructs can be grouped in two categories: those in the WSDL namespace of "http://www.w3.org/@@@@/@@/wsdl" and those not in WSDL namespace. WSDL 2.0 part 1 defines a set of binding constructs within the WSDL namespace that can be used to host binding detail definitions. Constructs for defining binding details are defined within their own namespaces which must be different from the WSDL namespace. ll these binding detail constructs are defined outside WSDL namespace, and are typically used as extensions of the hosting WSDL binding constructs. In the following sections, we will introduce the hosting WSDL binding constructs first, and then move on the the binding extensions.
! </p><div2 id="WSDLbindingConstructs">
<head>Binding Constructs in WSDL Namespace</head>
<p>Let's have a look at the constructs defined within the WSDL namespace first. The XML syntax of these constructs is summarized below:</p>
***************
*** 987,991 ****
<p>One WSDL <el>definitions</el> may contain zero or more <el>binding</el> elements as its direct children.</p>
<p>The <el>binding</el> element has a required <att>name</att> attribute. Within the same target namespace , each binding must have a unique name. The optional <att>interface</att> attribute refers, by QName, to an <el>interface</el>. See the previous section for how the <att>interface</att>attribute can be used to achieve different levels of reusability of the <el>binding</el>. </p>
! <p>Careful readers may have already noticed that the <el>binding</el> syntax is to some extend symmetric with the syntax of <el>interface</el>, in other words, each interface construct has a binding counterpart. Simliar to <el>interface</el>,a <el>binding</el> element can contain zero or more <el>fault</el>, zero or more <el>operation</el>, zero or more <el>feature</el>, and zero or more <el>property</el>. Be aware that despite of the syntax similarity, they are indeed different constructs since they are in different symbol space and are designed for different purspose. The <el>feature</el> and <el>property</el> element will be examined in section @@@@. We will explain the binding <el>fault</el> and <el>operation</el> constructs in the following sections. </p>
<div3 id="bindingFaults">
<head>Binding Faults</head>
--- 1049,1053 ----
<p>One WSDL <el>definitions</el> may contain zero or more <el>binding</el> elements as its direct children.</p>
<p>The <el>binding</el> element has a required <att>name</att> attribute. Within the same target namespace , each binding must have a unique name. The optional <att>interface</att> attribute refers, by QName, to an <el>interface</el>. See the previous section for how the <att>interface</att>attribute can be used to achieve different levels of reusability of the <el>binding</el>. </p>
! <p>Careful readers may have already noticed that the <el>binding</el> syntax is to some extent symmetric with the syntax of <el>interface</el>, in other words, each interface construct has a binding counterpart. Simliar to <el>interface</el>,a <el>binding</el> element can contain zero or more <el>fault</el>, zero or more <el>operation</el>, zero or more <el>feature</el>, and zero or more <el>property</el>. Be aware that despite of the syntax similarity, they are indeed different constructs since they are in different symbol space and are designed for different purpose. The <el>feature</el> and <el>property</el> element will be examined in section @@@@. We will explain the binding <el>fault</el> and <el>operation</el> constructs in the following sections. </p>
<div3 id="bindingFaults">
<head>Binding Faults</head>
***************
*** 1024,1029 ****
<definitions
! targetNamespace= "http://www.greath.com/2004/05/wsdl/reservationService.wsdl"
! xmlns:ghns = "http://www.greath.com/2004/05/schemas/reservationService.xsd"
xmlns = "http://www.w3.org/@@@@/@@/wsdl"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
--- 1086,1091 ----
<definitions
! targetNamespace= "http://www.greath.com/2004/05/wsdl/resSvc.wsdl"
! xmlns:ghns = "http://www.greath.com/2004/05/schemas/resSvc.xsd"
xmlns = "http://www.w3.org/@@@@/@@/wsdl"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
***************
*** 1039,1044 ****
<eg xml:space="preserve">
<definitions
! targetNamespace= "http://www.greath.com/2004/05/wsdl/reservationService.wsdl"
! xmlns:ghns = "http://www.greath.com/2004/05/schemas/reservationService.xsd"
xmlns = "http://www.w3.org/@@@@/@@/wsdl"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
--- 1101,1106 ----
<eg xml:space="preserve">
<definitions
! targetNamespace= "http://www.greath.com/2004/05/wsdl/resSvc.wsdl"
! xmlns:ghns = "http://www.greath.com/2004/05/schemas/resSvc.xsd"
xmlns = "http://www.w3.org/@@@@/@@/wsdl"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
***************
*** 1053,1057 ****
<div1 id="Service">
<head>Defining Service Endpoints </head>
! <p>By now, we have talked about how to define an abstract interface and how to bind the abstract interface to a concrete protocol and message format. One import piece of information is still missing: where the service can be accessed. Here comes the <el>service</el> construct which is essentially a set of alternate endpoints at which the service that implementing an <el>interface</el> is provided. Zero or more <el>services</el> can be defined within a <el>definitions</el> element. The XML syntax of <el>service</el> is summarized below:</p>
<eg xml:space="preserve">
<definitions targetNamespace="<emph>xs:anyURI</emph>" >
--- 1115,1119 ----
<div1 id="Service">
<head>Defining Service Endpoints </head>
! <p>By now, we have talked about how to define an abstract interface and how to bind the abstract interface to a concrete protocol and message format. One import piece of information is still missing: where the service can be accessed. Here comes the <el>service</el> construct which is essentially a set of alternate endpoints at which the service that implements an <el>interface</el> is provided. Zero or more <el>services</el> can be defined within a <el>definitions</el> element. The XML syntax of <el>service</el> is summarized below:</p>
<eg xml:space="preserve">
<definitions targetNamespace="<emph>xs:anyURI</emph>" >
***************
*** 1076,1081 ****
<eg xml:space="preserve">
<definitions
! targetNamespace= "http://www.greath.com/2004/05/wsdl/reservationService.wsdl"
! xmlns:ghns = "http://www.greath.com/2004/05/schemas/reservationService.xsd"
xmlns = "http://www.w3.org/@@@@/@@/wsdl"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
--- 1138,1143 ----
<eg xml:space="preserve">
<definitions
! targetNamespace= "http://www.greath.com/2004/05/wsdl/resSvc.wsdl"
! xmlns:ghns = "http://www.greath.com/2004/05/schemas/resSvc.xsd"
xmlns = "http://www.w3.org/@@@@/@@/wsdl"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
Received on Saturday, 11 December 2004 23:21:22 UTC