- From: David Booth <dbooth@dev.w3.org>
- Date: Wed, 15 Dec 2004 05:06:10 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20
In directory hutz:/tmp/cvs-serv22529
Modified Files:
wsdl20-primer.xml wsdl20-primer.html
Log Message:
Finished initial edit of major sections except Advanced Topics.
Pretty much ready for release as first public working draft, except
for lots of references (and some embedded notes) that have to be fixed up.
Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.20
retrieving revision 1.21
diff -C2 -d -r1.20 -r1.21
*** wsdl20-primer.xml 13 Dec 2004 22:14:20 -0000 1.20
--- wsdl20-primer.xml 15 Dec 2004 05:06:07 -0000 1.21
***************
*** 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;
--- 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, and hence does not describe every feature of the language. Users are expected to consult the WSDL 2.0 specification if they wish to make use of more sophisticated features or techniques.</p>
! <p>Finally, this primer is <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;
***************
*** 51,56 ****
</header>
<body>
! <!-- ****************@@@@@********************************* -->
! <!-- ****************@@@@@********************************* -->
<div1 id="Introduction">
<head>Introduction</head>
--- 51,56 ----
</header>
<body>
! <!-- ****************Introduction********************************* -->
! <!-- ****************Introduction********************************* -->
<div1 id="Introduction">
<head>Introduction</head>
***************
*** 58,74 ****
<p>This primer assumes that the reader has the following prerequisite knowledge:
<ulist><item><p> familiarity with XML (@@reference@@) and XML Namespaces (@@reference@@);</p></item><item><p>some familiarity with XML Schema (@@reference@@);</p></item>
! <item><p> familiarity with basic Web services concepts such as requester agent, provider agent, and Web service description, as described in <xspecref href="http://www.w3.org/TR/2004/NOTE-ws-arch-20040211/#whatis">Section 1.4</xspecref> of <xspecref href="http://www.w3.org/TR/2004/NOTE-ws-arch-20040211/">Web services architecture</xspecref> and its <xspecref href="http://www.w3.org/TR/2004/NOTE-ws-gloss-20040211/">glossary</xspecref>.</p>
</item>
</ulist>
No previous experience with WSDL is assumed.</p></div2>
<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>
</div2><div2 id="notation">
--- 58,74 ----
<p>This primer assumes that the reader has the following prerequisite knowledge:
<ulist><item><p> familiarity with XML (@@reference@@) and XML Namespaces (@@reference@@);</p></item><item><p>some familiarity with XML Schema (@@reference@@);</p></item>
! <item><p> familiarity with basic Web services concepts such as Web service, client (a/k/a <xspecref href="http://www.w3.org/TR/2004/NOTE-ws-gloss-20040211/#requesteragent">requester agent</xspecref>), and the purpose of a Web service description. (For an explanation of basic Web services concepts, see <xspecref href="http://www.w3.org/TR/2004/NOTE-ws-arch-20040211/#whatis">Section 1.4</xspecref> of <xspecref href="http://www.w3.org/TR/2004/NOTE-ws-arch-20040211/">Web services architecture</xspecref> and its <xspecref href="http://www.w3.org/TR/2004/NOTE-ws-gloss-20040211/">glossary</xspecref>.)</p>
</item>
</ulist>
No previous experience with WSDL is assumed.</p></div2>
<div2 id="PrimerStructure">
! <head>Structure of this Primer</head>
!
!
! <p>Section 2 presents a hypothetical use case involving a hotel reservation service. It then proceeds step-by-step through the development of a simple example WSDL 2.0 document that describes this service:<ulist><item><p>The <code><types></code> element describes the kinds of messages that the service will send and receive. </p></item><item><p>The <code><interface></code> element describes <emph>what</emph> abstract functionality the Web service provides. </p></item><item><p>The <code><binding></code> element describes <emph>how</emph> to access the service. </p></item><item><p>The <code><service></code> element describes <emph>where</emph> to access the service.</p></item></ulist></p>
! <p>Section 3 gives more information on defining message types.</p><p>Section 4 gives more information on interfaces.</p><p>Section 5 gives more information on bindings.</p><p>Section 6 gives more information on defining services.</p>
!
! <p>Section 7 covers various advanced topics, including features and properties, flexible authoring styles, service references, use of URIs, etc. </p>
</div2><div2 id="notation">
***************
*** 90,97 ****
<head>WSDL 2.0 Basics</head>
! <p>This section introduces the basic concepts used in WSDL 2.0 through the description of a hypothetical hotel reservation service. We start with a simple scenario, and add more requirements gradually to illustrate how more advanced WSDL2.0 features may be used. </p>
! <!-- ************************ GreatH *************************** --><div2><head>Example: The GreatH Hotel Reservation Service</head><p>Hotel GreatH is located in a remote island. It has been relying on fax and phone to provide room reservations. 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" ?>
--- 90,97 ----
<head>WSDL 2.0 Basics</head>
! <p>This section introduces the basic concepts used in WSDL 2.0 through the description of a hypothetical hotel reservation service. We start with a simple scenario, and later add more requirements to illustrate how more advanced WSDL2.0 features may be used. </p>
! <!-- ************************ GreatH *************************** --><div2><head>Example Scenario: 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 accep 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>The next several sections proceed step-by-step through the process of developig 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@ Complete Initial WSDL 2.0 Document for the GreatH Web Service</head>
<eg><![CDATA[
<?xml version="1.0" encoding="utf-8" ?>
***************
*** 173,177 ****
</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" ?>
--- 173,177 ----
</description>
]]></eg>
! </example></div2><div2><head>Getting Started: Defining a targetNamespace</head><p>Before writing our WSDL 2.0 document, we need to decide on a <emph>targetNamespace</emph> URI for it. The targetNamespace 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 targetNamespace, and thus will be distinguishable from similar names in a different targetNamespace. (This will become important if you use WSDL 2.0's import 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 owners SHOULD make the WSDL document available from this URI. (And if a WSDL description is split into multiple documents, then the targetNamespace should resolve to a master document that includes all the WSDL documents needed or 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 URI, 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" ?>
***************
*** 219,223 ****
. . .
</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>
--- 219,223 ----
. . .
</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 several types, we have not yet indicated which ones are to be used as message types for a Web service. We'll do that in the next section. </p></div3></div2><div2><head>Defining an Interface</head><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. This separation facilitates different levels of reusability and distribution of work in the lifecycle of a Web service and the WSDL document that describes it. </p><p>A WSDL 2.0 <code><interface></code> defines the abstract interface of a Web service as a set of abstract <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 are 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 tis 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>
***************
*** 262,270 ****
</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" ?>
--- 262,270 ----
</interface>
. . .
! </description>]]></eg></example><div3><head>Explanation of Example</head><glist><gitem><label><code><interface name = "reservationInterface" ></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 languge, 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" ?>
***************
*** 358,375 ****
</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>
! </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 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>
--- 358,362 ----
</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 id="overview">
<head>WSDL 2.0 Extensibility</head>
***************
*** 531,604 ****
<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
! said to belong to the same <att>target namespace</att>. </p>
! <p>Note that it is RECOMMENDED that the value of the <att>targetNamespace</att> SHOULD be dereferencible to a WSDL document. If a WSDL description is split into multiple documents, then the <att>targetNamespace</att> should resolve to a master document which includes all the WSDL documents needed for that service description.</p>
! <p>It's important to note that within a same namespace, there are three symbol spaces defined by WSDL 2.0 for Interface, Binding and Service respectively.The existence of sybmal spaces has significant impact on how constructs should be named. Within a symbol space, all qualified names ( that is, the combination of a construct's name and its associated namespace) are unique. Between symbol spaces, qualified names need not be unique. Thus it is perfectly coherent to have, for example, a binding and an interface that have the same name.</p>
! <p>When XML Schema is being used as one of the type systems for a WSDL description, then six other symbol spaces also exist, one for each of: global
! element declarations, global attribute declarations, named model groups, named
! attribute groups, type definitions and key constraints, as defined by XML Schema: Structures. Other type systems may
! define additional symbol spaces.</p></div3></div2></div1>
! <!-- ******************Interface********************************** -->
! <!-- ******************Interface********************************** -->
! <div1 id="interface">
! <head>Defining an Abstract Interface for a Web Service</head>
! <!-- ************************messages*************************** -->
! <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"/>
! <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:enumeration value="Queen"/>
! <xs:enumeration value="King"/>
! </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>
! </eg>
! </example>
! <p>After the schemas are defined, the second thing we need to decide is how to make this type definitions available to WSDL description. WSDL2.0 provides as a direct child of <el>definitions</el> the <el>types</el> element for enclosing messages definitions. There are two ways to enclose messages defintions within <el>types</el>: use <el>xs:import</el> mechanism provided by XML Schema, or embed the schemas within <el>xs:schema</el> elements. It's perfectly reasonable to use both ways in one WSDL. The following is a summary of the XML syntax for <el>types</el>:</p>
<eg xml:space="preserve"><definitions>
<<b>types</b>>
--- 518,529 ----
<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></div2></div1>
! <!-- ******************MessageTypes********************************** -->
! <!-- ******************MessageTypes********************************** -->
! <div1><head>More on Message Types</head><div2 id="messages">
<head>Defining Messages Using XML Schema</head>
!
!
! <p>As we saw previously, WSDL 2.0 provides a <el>types</el> element for enclosing messages definitions in a WSDL document. There are two ways to enclose messages definitions within the <el>types</el> element: use <el>xs:import</el> mechanism provided by XML Schema, or embed the schemas within <el>xs:schema</el> elements. It's perfectly reasonable to use both ways in one WSDL. The following is a summary of the XML syntax for the <el>types</el> element:</p>
<eg xml:space="preserve"><definitions>
<<b>types</b>>
***************
*** 615,619 ****
<el>xs:schema</el> constructs is a necessary condition for making XML Schema
components available to a WSDL description. </p>
! <p>Please note use of type system other than XML Schema is indicated by the extension elements in the above syntax. See section @@@@@ for more informationis.
</p>
<div3 id="import-xsd">
--- 540,544 ----
<el>xs:schema</el> constructs is a necessary condition for making XML Schema
components available to a WSDL description. </p>
! <p>Please note use of type system other than XML Schema is indicated by the extension elements in the above syntax. See section @@@@@ for more information.
</p>
<div3 id="import-xsd">
***************
*** 635,644 ****
<div3 id="embed-xsd">
<head>Embedding XML Schema</head>
! <p>Embedding an XML schema uses the existing top-level <el>xs:schema</el> element defined by XML Schema <bibref ref="XMLSchemaP1"/> may be viewed as simply cutting and pasting an
! existing, stand-alone schema, to a location inside <el>types</el>.</p>
<p>The schema components defined in the embedded schema are available to
WSDL for reference by QName (see @@@). 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>
--- 560,569 ----
<div3 id="embed-xsd">
<head>Embedding XML Schema</head>
! <p>Embedding an XML schema uses the existing top-level <el>xs:schema</el> element defined by XML Schema <bibref ref="XMLSchemaP1"/>. It comparable to simply cutting and pasting an
! existing, stand-alone schema to a location inside the <el>types</el> element.</p>
<p>The schema components defined in the embedded schema are available to
WSDL for reference by QName (see @@@). 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>
***************
*** 666,670 ****
<p>A REQUIRED <att>targetNamespace</att> attribute of type <emph>xs:anyURI</emph>.</p>
<p>It defines the namespace of the element declarations embedded in its owner <el>xs:schema</el>. Note that WSDL modifies the
! XML Schema definition of XML Schema <el>xs:schema</el> to make the <att>targetNamespace</att> attrbiute required. </p>
</item>
<item>
--- 591,595 ----
<p>A REQUIRED <att>targetNamespace</att> attribute of type <emph>xs:anyURI</emph>.</p>
<p>It defines the namespace of the element declarations embedded in its owner <el>xs:schema</el>. Note that WSDL modifies the
! XML Schema definition of XML Schema <el>xs:schema</el> to make the <att>targetNamespace</att> attribute required. </p>
</item>
<item>
***************
*** 675,682 ****
</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>
! <eg xml:space="preserve">
<definitions
--- 600,607 ----
</item>
</ulist>
! <p>Here is an example of importing a schema.</p>
! <example id="example-schema-import">
! <head>@example-schema-import@ Importing Message Definitions into WSDL 2.0</head>
! <ednote><edtext>Need to update this example.</edtext></ednote><eg xml:space="preserve">
<definitions
***************
*** 705,729 ****
</eg>
</example>
! <p>So far, we have successfully defined the message types and made them available for WSDL. In the following sections, the primer will move on to define the interface for the reservation service. </p>
</div3>
! </div2>
<!-- ************************MEPs*************************** -->
<div2 id="meps">
<head>Understanding Message Exchange Patterns</head>
! <p>An interface describes sequences of messages that a service sends
! and/or receives. It groups related messages into operations. More precisely, an
! operation is a sequence of input and output messages, and an interface is a set of
! 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
messages (to each other or to other nodes) that are not described by the
pattern. For instance, even though a pattern may define a single message sent
from a service to one other node, the Web Service may multicast that message to
other nodes. To maximize reuse, WSDL message exchange patterns identify a minimal contract between other parties and Web Services, and contain only information that is
! relevant to both the Web service and another party.</p>
! <p>A total of 8 MEPs are defined in Part 2 of the WSDL2.0 specification. Hopefully, these MEPs can cover most common use cases the W3C Web Services Description working group can vision, but they are not meant to be an exhaustive list of MEPs that can be used by operations. More MEPs can be defined for particular application needs by interested parties. </p>
! <p>For the 8 MEPs defined by WSDL2.0, some of them are variations of others based on how faults maybe generated. Three common fault generation models are specified. In the first model, so called "Fault Replace Message", any message after the first in the pattern MAY be replaced with a fault message, which MUST have identical cardinality and direction. The fault message MUST be delivered to the same target node as the message it replaces. In the second so called "Message Triggers Fault" model,any message, including the first, MAY trigger a fault message in response. Each recipient MAY generate a fault message, and MUST generate no more than one fault for each triggering message. Each fault message has direction the reverse of its triggering message. The fault message MUST be delivered to the originator of the message which triggered it. If there is no path to this node, the fault MUST be discarded. In the third case, no fault may be generated in the MEP.</p>
<p>Now let's have a look of each of the 8 MEPs. Depends on how the first message in the MEP is initiated, we can probably group the MEPs into in-bound MEPs in which case the service receives the first message in the exchange, and out-bound MEPs in which case the service sends out the first message in the exchange. Such Grouping is only for the purpose of easy reference from discussions in later sections of this primer. WSDL2.0 defines four in-bound MEPS:</p>
<ulist>
--- 630,652 ----
</eg>
</example>
!
</div3>
! </div2></div1><!-- ******************Interface********************************** --><!-- ******************Interface********************************** --><div1 id="interface">
! <head>More on Interfaces</head>
! <!-- ************************messages*************************** -->
!
<!-- ************************MEPs*************************** -->
<div2 id="meps">
<head>Understanding Message Exchange Patterns</head>
! <p>WSDL 2.0 message exchange patterns (MEPs) are used to defines the sequence and cardinality of the abstract messages in an operation. By design, WSDL 2.0 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 when an operation specifies which MEP to use. 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
messages (to each other or to other nodes) that are not described by the
pattern. For instance, even though a pattern may define a single message sent
from a service to one other node, the Web Service may multicast that message to
other nodes. To maximize reuse, WSDL message exchange patterns identify a minimal contract between other parties and Web Services, and contain only information that is
! relevant to both the Web service and the client that engages that service.</p>
! <p>A total of 8 MEPs are defined in Part 2 of the WSDL 2.0 specification. Hopefully, these MEPs will cover the most common use cases, but they are not meant to be an exhaustive list of MEPs that can be used by operations. More MEPs can be defined for particular application needs by interested parties. <ednote><name>dbooth</name><edtext>Add info about how to define a new MEP?</edtext></ednote></p>
! <p>For the 8 MEPs defined by WSDL 2.0, some of them are variations of others based on how faults may be generated. Three common fault generation models are specified. <glist><gitem><label>Fault Replaces Message</label><def><p>Any message after the first in the pattern MAY be replaced with a fault message, which MUST have identical cardinality and direction. The fault message MUST be delivered to the same target node as the message it replaces. </p></def></gitem><gitem><label>Message Triggers Fault</label><def><p>Any message, including the first, MAY trigger a fault message in response. Each recipient MAY generate a fault message, and MUST generate no more than one fault for each triggering message. Each fault message has direction the reverse of its triggering message. The fault message MUST be delivered to the originator of the message which triggered it. If there is no path to this node, the fault MUST be discarded. In the third case, no fault may be generated in the MEP. </p></def></gitem><gitem><abel>No Faults</label><def><p>No faults will be delivered.</p></def></gitem></glist></p>
<p>Now let's have a look of each of the 8 MEPs. Depends on how the first message in the MEP is initiated, we can probably group the MEPs into in-bound MEPs in which case the service receives the first message in the exchange, and out-bound MEPs in which case the service sends out the first message in the exchange. Such Grouping is only for the purpose of easy reference from discussions in later sections of this primer. WSDL2.0 defines four in-bound MEPS:</p>
<ulist>
***************
*** 777,791 ****
<date>20040910</date>
<edtext>
! Add more use cases and example - illustrate use of outbound meps
</edtext>
</ednote>
! <p>Equipped with the knowledge of all the MEPs defined in WSDL2.0, we have analyzed the list of requirements we have in hand and decided that the in-out MEP covers the requirement pretty well. Now we can move on to define the interface for the reservation Web service.</p>
</div2>
<!-- ************************interface*************************** -->
<div2 id="interfaceEL">
! <head>Defining Interface </head>
! <p>We briefly mentioned in the previous section that A WSDL <el>interface</el> is a set of <el>operation</el>s. It's true, but optionally reuseuable faults and features and properties (see section @@@@) can also be defined as child of <el>interface</el>. Let's have a close look into the <el>interface</el> construct in this section. Below is the XML syntax summary of the <el>interface</el> element:</p>
<eg xml:space="preserve">
<definitions targetNamespace="<emph>xs:anyURI</emph>" >
--- 700,714 ----
<date>20040910</date>
<edtext>
! Add more use cases and example - illustrate use of outbound meps?
</edtext>
</ednote>
!
</div2>
<!-- ************************interface*************************** -->
<div2 id="interfaceEL">
! <head>Defining Interfaces </head>
! <ednote><name>dbooth</name><edtext>Cut some/all of this?</edtext></ednote><p>We briefly mentioned that A WSDL 2.0 <el>interface</el> is basically a set of <el>operation</el>s. It's true, but optionally reusable faults and features and properties (see section @@@@) can also be defined as child of <el>interface</el>. Let's have a close look into the <el>interface</el> construct in this section. Below is the XML syntax summary of the <el>interface</el> element:</p>
<eg xml:space="preserve">
<definitions targetNamespace="<emph>xs:anyURI</emph>" >
***************
*** 860,869 ****
</eg>
<p>One WSDL <el>definitions</el> may contain zero or more <el>interface</el> elements as its direct children. Zero <el>interface</el> is permitted since a <el>definitions</el> element may only contain binding and/or endpoint definitions to be aggegrated into a master WSDL definition via import/include mechanisms. </p>
! <p>Let's have a look at the attributes of <el>interface</el> first.It has one required <att>name</att> attribute. Within the same target namespace (might be in different wsdl documents, see section @@@@), each interface must have a unique name. The <el>interface</el> element has two optional attributes:<att>extends</att> and <att>styleDefault</att>. <att>extends</att> will be explained in the next section. We will explain what a <att>style</att> is when we move to the section for <el>operation</el>. For now, you just need to know that the optional <att>styleDefault</att> attribute of <el>interface</el> can be used to define a default value for the <att>style</att> attribute of all <el>operation</el>s under this <el>interface</el>, if any of the operations do not specify a value for its <att>style</att>. </p>
<div3 id="extends">
<head>Interface Inheritance</head>
! <p>The optional <att>extends</att> attribute allows an interface to extend one or more other interfaces. In such cases the interface contains the operations of the interfaces it extends, along with any operations it defines. </p>
! <p>Two things about extending interfaces deserve some attention. The first is about name collision. There may be cases where, due to an interface extending one or more other interfaces,operations from different interface may have name collision. More precisely, within a same namespace, two or more interface operations may have the same name. In such cases, WSDL2.0 requires that the component models of those Interface Operation components MUST be equivalent (Component Equivalence is defined in Part 1 section 2.15 Equivalence of Components. For operations, basically equivalence means the two operations in question have same set of attributes and decedents). If the collisional operations are equivalent then they are considered to collapse into a single operation. It is an error if they are not equivalent. In other words, if two interfaces have name collisional operations, then those two interfaces cannot both form part of the derivation chain of a derived interface unless those operations are exactly he same. For the above reason, it is considered good practic to ensure that all operations within a same namespace are named uniquely whenever possible. Since faults, features and properties can also be defined as children of <el>interface</el> as one can see in later sections, the same name-collision resolution rules apply to those constructs.</p>
! <p>The second is about recursive extension of interfaces. It's disallowed. The interfaces a given interface extends MUST NOT themselves extend that interface either directly or indirectly.</p>
<ednote>
<name>KevinL</name>
--- 783,791 ----
</eg>
<p>One WSDL <el>definitions</el> may contain zero or more <el>interface</el> elements as its direct children. Zero <el>interface</el> is permitted since a <el>definitions</el> element may only contain binding and/or endpoint definitions to be aggegrated into a master WSDL definition via import/include mechanisms. </p>
! <p>Let's have a look at the attributes of <el>interface</el> first. It has one required <att>name</att> attribute. Within the same target namespace (might be in different wsdl documents, see section @@@@), each interface must have a unique name. The <el>interface</el> element has two optional attributes:<att>extends</att> and <att>styleDefault</att>. <att>extends</att> will be explained in the next section. We will explain what a <att>style</att> is when we move to the section for <el>operation</el>. For now, you just need to know that the optional <att>styleDefault</att> attribute of <el>interface</el> can be used to define a default value for the <att>style</att> attribute of all <el>operation</el>s under this <el>interface</el>, if any of the operations do not specify a value for its <att>style</att>. </p>
<div3 id="extends">
<head>Interface Inheritance</head>
! <p>The optional <att>extends</att> attribute allows an interface to extend one or more other interfaces. In such cases the interface contains the operations of the interfaces it extends, along with any operations it defines. Two things about extending interfaces deserve some attention. </p><p>First, recursive extension of interfaces is prohibited. The interfaces that a given interface extends MUST NOT themselves extend that interface either directly or indirectly. </p><p>Second, there may be cases where, due to an interface extending one or more other interfaces, operations from different interface may have a name collision. More precisely, within the same namespace, two or more interface operations end up having the same name. In such cases, WSDL 2.0 requires that the component models of those Interface Operation components MUST be equivalent (Component Equivalence is defined in Part 1 section 2.15 Equivalence of Components. For operations, basically equivalence means the two operations in quesion have same set of attributes and descendents). If the collisional operations are equivalent then they are considered to collapse into a single operation. It is an error if they have the same name in the same targetNamespace but are not equivalent. In other words, if two interfaces have name collisional operations, then those two interfaces cannot both form part of the derivation chain of a derived interface unless those operations are exactly the same. For the above reason, it is considered good practic to ensure that all operations within the same namespace are named uniquely whenever possible. Furthermore, since faults, features and properties can also be defined as children of the <el>interface</el> element (as descrbed later), the same name-collision resolution rules apply to those constructs.</p>
!
<ednote>
<name>KevinL</name>
***************
*** 879,885 ****
<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>
<head>Declaring interface faults</head>
<eg xml:space="preserve">
--- 801,807 ----
<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 fault 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 attributes may need to be defined via WSDL's attribute extension mechanism to allow associating such a message definition with the fault.</p>
! <p>Here is an example of reusing faults.</p>
! <ednote><name>dbooth</name><edtext>Update this example</edtext></ednote><example>
<head>Declaring interface faults</head>
<eg xml:space="preserve">
***************
*** 938,947 ****
<div3 id="operations">
<head>Interface Operations</head>
! <p>Now we are ready to take a close look at the <el>operation</el> element. An operation is an interaction with the service consisting of a set of ordinary and fault messages exchanged between the service and the other roles involved in the interaction, in particular the service requestor. As we have already explained earlier, message types are defined in a type system, and the sequencing and cardinality of the messages involved in a particular interaction is governed by the message exchange pattern (MEP). The <el>operation</el> element is the glueing construct that bring all the pieces together for an interaction. The service indicates its participation in a MEP by using the MEP in its operations. Message placeholders defined in a MEP are associated with specific message types in operations.</p>
<p>WSDL 2.0 defines two required and two optional attributes for an <el>operation</el>:</p>
<ulist>
<item>
<p>A required <att>name</att> attribute</p>
! <p>Operation names must be unique within an interface. Beware that <el>operations</el>are local to an <el>interface</el>,so two <el>interface</el> elements sharing the same target namespace but with different name MAY contain <el>operations</el> which share the same name. Thus, <el>operations</el> cannot be referred to by QName since the <att>name</att> and target namespace are not sufficient to uniquely identify an <el>operation</el>. In order to uniquely identify an <el>operation</el>, one must first identify the <el>interface</el> by QName and then identify the <el>operation</el> within that <el>interface</el> by a further QName. As explained in section@@@, this fact has compound impact when an interface extends other interfaces and its considered a good practice to name operations uniquely within same namespace whenever possible.</p>
</item>
<item>
--- 860,869 ----
<div3 id="operations">
<head>Interface Operations</head>
! <p>Now we are ready to take a close look at the <el>operation</el> element. As explained earlier, message types are defined in a type system, and the sequencing and cardinality of the messages involved in a particular interaction are governed by the message exchange pattern (MEP). The <el>operation</el> element is the glue that brings all the pieces together for an abstract interaction. The service indicates its participation in a MEP by using the MEP in its operations. Message placeholders defined in a MEP are associated with specific message types in operations.</p>
<p>WSDL 2.0 defines two required and two optional attributes for an <el>operation</el>:</p>
<ulist>
<item>
<p>A required <att>name</att> attribute</p>
! <p>Operation names must be unique within an interface. Beware that <el>operations</el>are local to an <el>interface</el>,so two <el>interface</el> elements sharing the same target namespace but with different name MAY contain <el>operations</el> which share the same name. Thus, <el>operations</el> cannot be referenced by QName since the <att>name</att> and targetNamespace are not sufficient to uniquely identify an <el>operation</el>. In order to uniquely identify an <el>operation</el>, one must first identify the <el>interface</el> by QName and then identify the <el>operation</el> within that <el>interface</el> by a further QName. As explained in section @@@, this fact has compound impact when an interface extends other interfaces. It is considered good practice to name operations uniquely within same namespace whenever possible.</p>
</item>
<item>
***************
*** 951,955 ****
<item>
<p>An optional <att>style</att> attribute</p>
! <p>it's an absolute URI identifying the rules that were used to construct the message type definitions used by the <el>operation</el>. Note that the attribute MAY not present, but if it is present, then the rules implied by that value MUST be followed or it is an error. For example, WSDL 2.0 defines a set of rules for constructing so called RPC style messages(See section@@@@). If this attribute is set to "http://www.w3.org/2004/03/wsdl/style/rpc", then all the rules defined for RPC style must be followed. We will have a closer look at RPC style in section@@@. </p>
<ednote>
<name>KevinL</name>
--- 873,877 ----
<item>
<p>An optional <att>style</att> attribute</p>
! <p>it's an absolute URI identifying the rules that were used to construct the message type definitions used by the <el>operation</el>. Note that the attribute MAY not present, but if it is present, then the rules implied by that value MUST be followed or it is an error. For example, WSDL 2.0 defines a set of rules for constructing so called RPC style messages (See section@@@@). If this attribute is set to "http://www.w3.org/2004/03/wsdl/style/rpc", then all the rules defined for the RPC style must be followed. We will have a closer look at RPC style in section@@@. </p>
<ednote>
<name>KevinL</name>
***************
*** 968,975 ****
</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>
<head>Defining Interface Operations</head>
<eg xml:space="preserve">
--- 890,897 ----
</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 is 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 can b 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. 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 reference by 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>
!
! <ednote><name>dbooth</name><edtext>Update this example. Also: which features should it illustrate?</edtext></ednote><example>
<head>Defining Interface Operations</head>
<eg xml:space="preserve">
***************
*** 1028,1032 ****
</eg>
</example>
! <p>Note that in the above example, the <emph>invalidDataFault</emph> is re-used by both operations. In the <emph>makeReservation</emph> operation, two alternative outgoing faults are defined which means either a invaliddDataFault or a invalidCreditCardFault may be returned as a replacement of the outgoing message.</p>
<p>An <el>operation</el> can also contain zero or more <el>feature</el> and <el>property</el> elements. We defer the explanation for <el>feature</el> and <el>property</el> to section @@@@. </p>
</div3>
--- 950,954 ----
</eg>
</example>
! <p>Note that in the above example, the <emph>invalidDataFault</emph> is re-used by both operations. In the <emph>makeReservation</emph> operation, two alternative outgoing faults are defined which means either a invalidDataFault or a invalidCreditCardFault may be returned as a replacement of the outgoing message.</p>
<p>An <el>operation</el> can also contain zero or more <el>feature</el> and <el>property</el> elements. We defer the explanation for <el>feature</el> and <el>property</el> to section @@@@. </p>
</div3>
***************
*** 1036,1040 ****
<!-- **********************************Binding************************** -->
<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
--- 958,962 ----
<!-- **********************************Binding************************** -->
<div1 id="binding">
! <head>More on Bindings</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
***************
*** 1042,1046 ****
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
MAY omit specifying an interface. <el>bindings</el> that do not
--- 964,968 ----
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> that omits any
operation-specific binding details and any fault binding details
MAY omit specifying an interface. <el>bindings</el> that do not
***************
*** 1056,1060 ****
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>
--- 978,982 ----
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 into 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>
***************
*** 1097,1106 ****
<date>20040527</date>
<edtext>
! Need clarification - infault outfault are missing from the binding operation syntax. Is it an overlook?
</edtext>
</ednote>
! <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>
--- 1019,1028 ----
<date>20040527</date>
<edtext>
! Need clarification - infault outfault are missing from the binding operation syntax. Is it an oversight?
</edtext>
</ednote>
! <ednote><name>dbooth</name><edtext>Trim some of this?</edtext></ednote><p>One WSDL <el>description</el> element 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 spaces 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>
***************
*** 1125,1129 ****
<date>20040527</date>
<edtext>
! Need clarification - wording about qname uniqueness in part 1 section 2.10.1 and 2.11.1 need change. it's not correct to say "A particular
operation of an interface is uniquely identified by the target namespace of the interface and the name of the operation within that interface"
</edtext>
--- 1047,1051 ----
<date>20040527</date>
<edtext>
! Need clarification - wording about qname uniqueness in part 1 section 2.10.1 and 2.11.1 need to change. it's not correct to say "A particular
operation of an interface is uniquely identified by the target namespace of the interface and the name of the operation within that interface"
</edtext>
***************
*** 1167,1172 ****
<!-- **********************************Service************************** -->
<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>" >
--- 1089,1094 ----
<!-- **********************************Service************************** -->
<div1 id="Service">
! <head>More on Service Endpoints </head>
! <p>As described previously, the <el>service</el> construct specifies a set of alternate endpoints at which a service is available. 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>" >
Index: wsdl20-primer.html
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.html,v
retrieving revision 1.9
retrieving revision 1.10
diff -C2 -d -r1.9 -r1.10
*** wsdl20-primer.html 28 Oct 2004 02:57:00 -0000 1.9
--- wsdl20-primer.html 15 Dec 2004 05:06:08 -0000 1.10
***************
*** 114,122 ****
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 <em>non-normative</em>. Any specific questions of
! what WSDL 2.0 requires or forbids should be referred to the WSDL
! 2.0 specification (@@reference@@).</p>
</div>
--- 114,128 ----
[...3637 lines suppressed...]
<dl>
--- 3249,3253 ----
<div class="div2">
<h3><a id="Normative-References"
! name="Normative-References"></a>8.1 Normative References</h3>
<dl>
***************
*** 2952,2956 ****
<div class="div2">
<h3><a id="Informative-References"
! name="Informative-References"></a>7.2 Informative References</h3>
<dl>
--- 3408,3412 ----
<div class="div2">
<h3><a id="Informative-References"
! name="Informative-References"></a>8.2 Informative References</h3>
<dl>
Received on Wednesday, 15 December 2004 05:06:11 UTC