- From: David Booth <dbooth@dev.w3.org>
- Date: Wed, 15 Dec 2004 19:24:31 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20
In directory hutz:/tmp/cvs-serv27088
Modified Files:
wsdl20-primer.xml wsdl20-primer.html
Log Message:
Lots more misc edits.
Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.21
retrieving revision 1.22
diff -C2 -d -r1.21 -r1.22
*** wsdl20-primer.xml 15 Dec 2004 05:06:07 -0000 1.21
--- wsdl20-primer.xml 15 Dec 2004 19:24:29 -0000 1.22
***************
*** 55,62 ****
<div1 id="Introduction">
<head>Introduction</head>
! <div2><head>Prerequisites</head>
<p>This primer assumes that the reader has the following prerequisite knowledge:
<ulist><item><p> familiarity with XML (@@reference@@) and XML Namespaces (@@reference@@);</p></item><item><p>some familiarity with XML Schema (@@reference@@);</p></item>
! <item><p> familiarity with basic Web services concepts such as 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>
--- 55,62 ----
<div1 id="Introduction">
<head>Introduction</head>
! <div2 id="Prerequisites"><head>Prerequisites</head>
<p>This primer assumes that the reader has the following prerequisite knowledge:
<ulist><item><p> familiarity with XML (@@reference@@) and XML Namespaces (@@reference@@);</p></item><item><p>some familiarity with XML Schema (@@reference@@);</p></item>
! <item><p> familiarity with basic Web services concepts such as Web service, client, and the purpose and function 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>. However, note that that document uses the slightly more precise terms "<xspecref href="http://www.w3.org/TR/2004/NOTE-ws-gloss-20040211/#requesteragent">requester agent</xspecref>" and "<xspecref href="http://www.w3.org/TR/2004/NOTE-ws-gloss-20040211/#provideragent">provider agent</xspecref>" instead of the terms "client" and "Web service" used in this primer.)</p>
</item>
</ulist>
***************
*** 87,97 ****
</div1>
<!-- ******************************************************* -->
! <div1 id="IntroductionWS">
<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" ?>
--- 87,97 ----
</div1>
<!-- ******************************************************* -->
! <div1 id="basics">
<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 id="basics-greath-scenario"><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. hus, the service will accept a <code>checkAvailability</code> message and return a <code>checkAvailabilityResponse</code> or <code>invalidDataFault</code> message.</p> </item><item><p><emph>MakeReservation</emph>. To make a reservation, a client must provide a name, address, and credit card information, and the service will return a confirmation number if the reservation is successful. The service will return an error message if the credit card number or any other data field is invalid. Thus, the service will accept a <code>makeReservation</code> message and return a <code>makeReservationResponse</code> or <code>invalidCreditCardFault</code> message.</p></item></ulist> We know that we will later need to build a complete system that supports transactions and secured transmission, but initially we will implement only minimal functionality. In fact, to simplify our first example, we will implement only the <emph>CheckAvailability</emph> operation. </p><p>The next several sections proceed step-by-step thrugh the process of developing a WSDL 2.0 document that describes the desired Web service. However, for those who can't wait to see a complete example, here is the WSDL 2.0 document that we'll be creating.</p><example id="example-initial">
! <head>WSDL 2.0 Document for the GreatH Web Service (Initial Example)</head>
<eg><![CDATA[
<?xml version="1.0" encoding="utf-8" ?>
***************
*** 106,110 ****
<documentation>
This document describes the GreatH Web service. Additional
! application-level requirements for its use of this service --
beyond what WSDL 2.0 is able to describe -- are available
at http://greath.example.com/2004/reservation-documentation.html
--- 106,110 ----
<documentation>
This document describes the GreatH Web service. Additional
! application-level requirements for use of this service --
beyond what WSDL 2.0 is able to describe -- are available
at http://greath.example.com/2004/reservation-documentation.html
***************
*** 173,178 ****
</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" ?>
<description
--- 173,178 ----
</description>
]]></eg>
! </example></div2><div2 id="basics-getting-started"><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 al 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 URI, we can begin our WSDL 2.0 document as the following empty shell.</p><example id="example-empty-shell">
! <head>An Initial Empty WSDL Document</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
<description
***************
*** 184,191 ****
</description>]]></eg>
! </example><div3><head>Explanation of Example</head><p><glist><gitem><label><code><description</code></label><def><p>Every WSDL 2.0 document has a <code><description></code> element as its top-most element. This merely acts as a container for the rest of the WSDL 2.0 document, and is used to declare namespaces that will be used throughout the document.</p></def></gitem><gitem><label><code>xmlns="http://www.w3.org/2004/08/wsdl"</code></label><def><p>This is the XML namespace for WSDL 2.0 itself. Because we have not defined a prefix for it, any unprefixed elements or attributes are expected to be WSDL 2.0 elements or attributes (such as the <code><description></code> element).</p></def></gitem><gitem><label><code>targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"</code></label><def><p>This defines the <code>targetNamespace</code> that we have chosen for the GreatH reservation service, as described above. Note that this is not an actual XML namespace declaration. Rather it is a WSDL 2.0 attribute whose purpose is <emph>analogous</emph> to a targetNamespace in XML Schema.</p></def></gitem><gitem><label><code>xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"</code></label><def><p>This is an actual XML namespace declaration for use in our GreatH service description. Note that this is the same URI that was specified above for the <code>targetNamespace</code>. This will allow us later to use the <code>tns:</code> prefix in <xspecref href="@@xml-schema#qname@@">qnames</xspecref>, to refer to the targetNamespace of the GreatH service. </p></def></gitem></glist></p><p> Now we can start describing the GreatH service. </p></div3></div2><div2><head>Defining Message Types</head><p>We know that the GreatH service will be sending and receiving messages, so a good starting point in describing the service is to define the message types that the service will use. We'll use XML Schema to do so, because WSDL 2.0 requires all conformant WSDL processors to support XML Schma at a minimum. However, WSDL 2.0 does not prohibit the use of some other schema definition language.</p><p>WSDL 2.0 allows message types to be defined directly within the WSDL document, inside the <code><types></code> element, which is a child of the <code><description></code> element. (Later we'll see how we can provide the type definitions in a separate document, using XML Schema's <code><import></code> mechanism.) The following schema defines checkAvailability, checkAvailabilityResponse and invalidDataError message types that we'll need. </p><ednote><name>dbooth</name><edtext>@@ Do we really need to show how to use XML Schema import? @@</edtext></ednote><p>In WSDL 2.0, all normal and fault message types must be defined as single <emph>elements</emph> at the topmost level (though of course each element may have any amount of substructure inside it). Thus, a message type must not directly consist of a sequence of elements or other complex type. </p><example id="example-initial-ypes">
! <head>@example-initial-types@ The Initial GreatH Message Types</head>
! <ednote><name>dbooth</name><edtext>@@ Not sure the namespace declarations and prefixes in this schema declaration are correct. In particular, check: xmlns:xs="http://www.w3.org/2001/XMLSchema"
! xmlns="http://greath.example.com/2004/schemas/resSvc.xsd"@@</edtext></ednote><eg><![CDATA[
<?xml version="1.0" encoding="utf-8" ?>
<description
--- 184,191 ----
</description>]]></eg>
! </example><div3 id="example-empty-shell-explanation"><head>Explanation of Example</head><p><glist><gitem><label><code><description</code></label><def><p>Every WSDL 2.0 document has a <code><description></code> element as its top-most element. This merely acts as a container for the rest of the WSDL 2.0 document, and is used to declare namespaces that will be used throughout the document.</p></def></gitem><gitem><label><code>xmlns="http://www.w3.org/2004/08/wsdl"</code></label><def><p>This is the XML namespace for WSDL 2.0 itself. Because we have not defined a prefix for it, any unprefixed elements or attributes are expected to be WSDL 2.0 elements or attributes (such as the <code><description></code> element).</p></def></gitem><gitem><label><code>targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"</code></label><def><p>This defines the <code>targetNamespace</code> that we have chosen for the GreatH reservation service, as described above. Note that this is not an actul XML namespace declaration. Rather, it is a WSDL 2.0 attribute whose purpose is <emph>analogous</emph> to a targetNamespace in XML Schema.</p></def></gitem><gitem><label><code>xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"</code></label><def><p>This is an actual XML namespace declaration for use in our GreatH service description. Note that this is the same URI that was specified above for the <code>targetNamespace</code>. This will allow us later to use the <code>tns:</code> prefix in <xspecref href="@@xml-schema#qname@@">qnames</xspecref>, to refer to the targetNamespace of the GreatH service. </p></def></gitem></glist></p><p> Now we can start describing the GreatH service. </p></div3></div2><div2 id="basics-types"><head>Defining Message Types</head><p>We know that the GreatH service will be sending and receiving messages, so a good starting point in describing the service is to define the message types that the service will use. We'll use XML Schema to do so, because WSDL 2.0 reqires all conformant WSDL processors to support XML Schema at a minimum. However, WSDL 2.0 does not prohibit the use of some other schema definition language.</p><p>WSDL 2.0 allows message types to be defined directly within the WSDL document, inside the <code><types></code> element, which is a child of the <code><description></code> element. (Later we'll see how we can provide the type definitions in a separate document, using XML Schema's <code><import></code> mechanism.) The following schema defines checkAvailability, checkAvailabilityResponse and invalidDataError message types that we'll need. </p><p>In WSDL 2.0, all normal and fault message types must be defined as single <emph>elements</emph> at the topmost level (though of course each element may have any amount of substructure inside it). Thus, a message type must not directly consist of a sequence of elements or other complex type. </p><example id="example-initial-types">
! <head>GreatH Message Types</head>
! <ednote><name>dbooth</name><edtext>Not sure the namespace declarations and prefixes in this schema declaration are correct. In particular, need to check: xmlns:xs="http://www.w3.org/2001/XMLSchema"
! xmlns="http://greath.example.com/2004/schemas/resSvc.xsd"</edtext></ednote><eg><![CDATA[
<?xml version="1.0" encoding="utf-8" ?>
<description
***************
*** 219,224 ****
. . .
</description>]]></eg>
! </example><div3><head>Explanation of Example</head><glist><gitem><label><code>xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"</code></label><def><p>We've added another namespace declaration. The <code>ghns</code> namespace prefix will allow us (later, when defining an interface) to reference the targetNamespace that we define for our message types. Thus, the URI we specify must be the same as the URI that we define as the targetNamespace of our XML Schema types (below) -- <emph>not</emph> the targetNamespace of the WSDL document itself.</p></def></gitem><gitem><label><code>targetNamespace="http://greath.example.com/2004/schemas/resSvc.xsd"</code></label><def><p>This is the XML Schema targetNamespace that we've created for use by the GreatH reservation service. The <code>checkAvailability</code>, <code>checkAvailability</code> and <code>invalidDataError</code> element names will be associated with this targetNamespace.</p></def></gitem><gitem><label><code>checkAvailability</code>,<code>checkAvailabilityResponse</code> and <code>invalidDataError</code></label><def><p>These are the message types that we'll use. Note that these are defined to be XML <emph>elements</emph>, as explained above.</p></def></gitem></glist><p>Although we have defined 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>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
--- 219,224 ----
. . .
</description>]]></eg>
! </example><div3 id="example-initial-types-explanation"><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 id="basics-interface"><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 represeting 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-ot@@">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>GreatH Interface Definition</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
***************
*** 262,271 ****
</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" ?>
<description
--- 262,271 ----
</interface>
. . .
! </description>]]></eg></example><div3 id="example-initial-interface-explanation"><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 id="basics-binding"><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 t the WSDL 2.0 language, via WSDL 2.0's open content model. WSDL 2.0 Part 3 defines binding constructs for SOAP 1.2 <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>GreatH Binding Definition</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
<description
***************
*** 307,312 ****
. . .
</description>]]></eg>
! </example><div3><head>Explanation of Example</head><glist><gitem><label><code>xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"</code></label><def><p>We've added two more namespace declarations. This one is the namespace for the SOAP 1.2 binding construct that is defined in WSDL 2.0 Part 3 <bibref ref="SOAP12-PART1"/>. Elements and attributes prefixed with <code>wsoap:</code> are constructs defined there. </p></def></gitem><gitem><label><code>xmlns:soap="http://www.w3.org/2003/05/soap-envelope"</code></label><def><p>This namespace is defined by the SOAP 1.2 specification itself. The SOAP 1.2 specification defines certain terms within this namespace to unambiguously identify particular concepts. Thus, we will use the <code>soap:</code> prefix when we need to refer to one of those terms.</p></def></gitem><gitem><label><code><binding name="reservationSOAPBinding"</code></label><def><p>Bindings are declared directly inside the <el><description></el> element. The <att>name</att> attribte defines a name for this binding. Each name must be unique among all bindings in this targetNamespace, and will be used later when we define a service endpoint that references this binding. WSDL 2.0 uses separate symbol spaces for interfaces, bindings and services, so interface "foo", binding "foo" and service "foo" are all distinct. </p></def></gitem><gitem><label><code>interface="tns:reservationInterface"</code></label><def><p>This is the name of the interface whose message format and transmission protocols we are specifying. As discussed @later@, a reusable binding can be defined by omitting the <att>interface</att> attribute. Note also the use of the <code>tns:</code> prefix, which refers to the previously defined targetNamespace for this WSDL document. In this case it may seem silly to have to specify the tns: prefix, but @we will see later@ how WSDL 2.0's import mechanism can be used to combine components that are defined in different targetNamespaces.</p></def></gitem><gitem><label><code>type"http://www.w3.org/2004/08/wsdl/soap12"</code></label><def><p>This specifies the type of concrete message format to use, in this case SOAP 1.2.</p></def></gitem><gitem><label><code>wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP"</code></label><def><p>This attribute is specific to WSDL 2.0's SOAP binding (thus it uses the <code>wsoap:</code> prefix). It specifies the underlying transmission protocol that should be used, in this case HTTP. </p></def></gitem><gitem><label><code><operation ref="tns:opCheckAvailability"</code></label><def><p>This not defining a new operation. Rather, it is referencing the previously defined <code>opCheckAvailability</code> operation in order to specify binding details for it. This element can be omitted if defaulting rules are instead used to supply the necessary information. (See @@@@.)</p></def></gitem><gitem><label><code>wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response"></code></label><def><p>This attribute is also specific to WSDL 2.0' SOAP binding. It specifies the SOAP message exchange pattern that will be used to implement the abstract WSDL 2.0 message exchange pattern (<xspecref href="@@part2#in-out@@">in-out</xspecref>) that was specified when the <code>opCheckAvailability</code> operation was defined. </p></def></gitem><gitem><label><code><fault ref="tns:invalidDataFault"</code></label><def><p>As with a binding operation, this is not declaring a new fault. Rather, it is referencing a fault (<code>invalidDataFault</code>) that was previously defined in the <code>opCheckAvailability</code> interface, in order to specify binding details for it.</p></def></gitem><gitem><label><code>wsoap:code="soap:Sender"/></code></label><def><p>This attribute is also specific to WSDL 2.0's SOAP binding. This specifies the SOAP 1.2 fault code that will cause this fault message to be sent. @@ Need to verify that this is correct. @@ If desired, an list of subcodes can also be specified using the optional <att>wsoap:subcodes</att> attibute.</p></def></gitem></glist></div3></div2><div2><head>Defining a Service</head><p>Now that our binding has specified <emph>how</emph> messages will be transmitted, we are ready to specify <emph>where</emph> the service can be accessed, by use of the <el><service></el> element. </p><p>A WSDL 2.0 <emph>service</emph> specifies a single interface that the service will support, and a list of <emph>endpoint</emph> locations where that service can be accessed. Each endpoint must also reference a previously defined binding in order to indicate the binding details that are to be used at that endpoint. A service is only permitted to have one interface. (However, WSDL 2.0 does not prohibit you from declaring multiple services that use different interfaces but happen to use the same endpoint address.) </p><p>Here is a definition for our GreatH service.</p><example id="example-initial-service">
! <head>@example-initial-service@ The Initial GreatH Service</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
<description
--- 307,312 ----
. . .
</description>]]></eg>
! </example><div3 id="example-initial-binding-explanation"><head>Explanation of Example</head><glist><gitem><label><code>xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"</code></label><def><p>We've added two more namespace declarations. This one is the namespace for the SOAP 1.2 binding construct that is defined in WSDL 2.0 Part 3 <bibref ref="SOAP12-PART1"/>. Elements and attributes prefixed with <code>wsoap:</code> are constructs defined there. </p></def></gitem><gitem><label><code>xmlns:soap="http://www.w3.org/2003/05/soap-envelope"</code></label><def><p>This namespace is defined by the SOAP 1.2 specification itself. The SOAP 1.2 specification defines certain terms within this namespace to unambiguously identify particular concepts. Thus, we will use the <code>soap:</code> prefix when we need to refer to one of those terms.</p></def></gitem><gitem><label><code><binding name="reservationSOAPBinding"</code></label><def><p>Bindings are declared directly inside the <el><description><el> element. The <att>name</att> attribute defines a name for this binding. Each name must be unique among all bindings in this targetNamespace, and will be used later when we define a service endpoint that references this binding. WSDL 2.0 uses separate symbol spaces for interfaces, bindings and services, so interface "foo", binding "foo" and service "foo" are all distinct. </p></def></gitem><gitem><label><code>interface="tns:reservationInterface"</code></label><def><p>This is the name of the interface whose message format and transmission protocols we are specifying. As discussed @later@, a reusable binding can be defined by omitting the <att>interface</att> attribute. Note also the use of the <code>tns:</code> prefix, which refers to the previously defined targetNamespace for this WSDL document. In this case it may seem silly to have to specify the tns: prefix, but @we will see later@ how WSDL 2.0's import mechanism can be used to combine components that are defined in different targetNamespaces.<p></def></gitem><gitem><label><code>type="http://www.w3.org/2004/08/wsdl/soap12"</code></label><def><p>This specifies the type of concrete message format to use, in this case SOAP 1.2.</p></def></gitem><gitem><label><code>wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP"</code></label><def><p>This attribute is specific to WSDL 2.0's SOAP binding (thus it uses the <code>wsoap:</code> prefix). It specifies the underlying transmission protocol that should be used, in this case HTTP. </p></def></gitem><gitem><label><code><operation ref="tns:opCheckAvailability"</code></label><def><p>This not defining a new operation. Rather, it is referencing the previously defined <code>opCheckAvailability</code> operation in order to specify binding details for it. This element can be omitted if defaulting rules are instead used to supply the necessary information. (See @@@@.)</p></def></gitem><gitem><label><code>wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response"></code></label><def><p>Thi attribute is also specific to WSDL 2.0's SOAP binding. It specifies the SOAP message exchange pattern that will be used to implement the abstract WSDL 2.0 message exchange pattern (<xspecref href="@@part2#in-out@@">in-out</xspecref>) that was specified when the <code>opCheckAvailability</code> operation was defined. </p></def></gitem><gitem><label><code><fault ref="tns:invalidDataFault"</code></label><def><p>As with a binding operation, this is not declaring a new fault. Rather, it is referencing a fault (<code>invalidDataFault</code>) that was previously defined in the <code>opCheckAvailability</code> interface, in order to specify binding details for it.</p></def></gitem><gitem><label><code>wsoap:code="soap:Sender"/></code></label><def><p>This attribute is also specific to WSDL 2.0's SOAP binding. This specifies the SOAP 1.2 fault code that will cause this fault message to be sent. @@ Need to verify that this is correct. @@ If desired, an list of subcodes can also be specified using th optional <att>wsoap:subcodes</att> attribute.</p></def></gitem></glist></div3></div2><div2 id="basics-service"><head>Defining a Service</head><p>Now that our binding has specified <emph>how</emph> messages will be transmitted, we are ready to specify <emph>where</emph> the service can be accessed, by use of the <el><service></el> element. </p><p>A WSDL 2.0 <emph>service</emph> specifies a single interface that the service will support, and a list of <emph>endpoint</emph> locations where that service can be accessed. Each endpoint must also reference a previously defined binding in order to indicate the binding details that are to be used at that endpoint. A service is only permitted to have one interface. (However, WSDL 2.0 does not prohibit you from declaring multiple services that use different interfaces but happen to use the same endpoint address.) </p><p>Here is a definition for our GreatH service.</p><example id="example-initial-service">
! <head>GreatH Service Definition</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
<description
***************
*** 338,343 ****
</description>]]></eg>
! </example><div3><head>Explanation of Example</head><glist><gitem><label><code><service name="reservationService"</code></label><def><p>This defines a name for this service, which must be unique among service names in the current targetNamespace. @Say why it's required.@<ednote><name>dbooth</name><edtext>Anyone remember why we made the name attribute required? Does WSDL 2.0 use it anywhere?</edtext></ednote></p></def></gitem><gitem><label><code>interface="tns:reservationInterface"></code></label><def><p>This specifies the name of the previously defined interface that these service endpoints will support. </p></def></gitem><gitem><label><code><endpoint name="reservationEndpoint"</code></label><def><p>This defines an endpoint for the service, and a name for this endpoint, which must be unique within this service. @Say why the name is required.@ <ednote><name>dbooth</name><edtext>Anyone remember why we made the name attribute required? Does WSDL 2.0 use it anywhere?</edtext></ednote></p></ef></gitem><gitem><label><code>binding="tns:reservationSOAPBinding"</code></label><def><p>This specifies the name of the previously defined binding to be used by this endpoint. </p></def></gitem><gitem><label><code>address ="http://greath.example.com/2004/reservation"/></code></label><def><p>This specifies the physical address at which this service can be accessed using the binding specified by the <att>binding</att> attribute.</p></def></gitem></glist><p>That's it! Well, almost. </p></div3></div2><div2><head>Documenting the Service</head><p>As we have seen, a WSDL 2.0 document is inherently only a <emph>partial</emph> description of a service. Although it captures the basic mechanics of interacting with the service -- the message types, transmission protocols, service location, etc. -- in general, additional documention will need to explain other application-level requirements for its use. For example, such documentation should explain the purpose and use of the service, the meanings of all message, constraints on their use, and the sequence in which operations should be invoked.</p><p>The <el><documentation></el> element allows you to include some human-readable documentation inside your WSDL document. It is a convenient place to reference any additional documentation that a client developer may need in order to use your service.</p><example id="example-initial-documentation">
! <head>@example-initial-documentation@ Documenting the GreatH Service</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
<description
--- 338,343 ----
</description>]]></eg>
! </example><div3 id="example-initial-service-explanation"><head>Explanation of Example</head><glist><gitem><label><code><service name="reservationService"</code></label><def><p>This defines a name for this service, which must be unique among service names in the current targetNamespace. @@Explain why it's required.@@<ednote><name>dbooth</name><edtext>Anyone remember why we made the name attribute required? Does WSDL 2.0 use it anywhere?</edtext></ednote></p></def></gitem><gitem><label><code>interface="tns:reservationInterface"></code></label><def><p>This specifies the name of the previously defined interface that these service endpoints will support. </p></def></gitem><gitem><label><code><endpoint name="reservationEndpoint"</code></label><def><p>This defines an endpoint for the service, and a name for this endpoint, which must be unique within this service. @@Explain why the name is required.@@ <ednote><name>dbooth</name><edtext>Anyone remember why we made the name attribute required? Des WSDL 2.0 use it anywhere?</edtext></ednote></p></def></gitem><gitem><label><code>binding="tns:reservationSOAPBinding"</code></label><def><p>This specifies the name of the previously defined binding to be used by this endpoint. </p></def></gitem><gitem><label><code>address ="http://greath.example.com/2004/reservation"/></code></label><def><p>This specifies the physical address at which this service can be accessed using the binding specified by the <att>binding</att> attribute.</p></def></gitem></glist><p>That's it! Well, almost. </p></div3></div2><div2 id="basics-documentation"><head>Documenting the Service</head><p>As we have seen, a WSDL 2.0 document is inherently only a <emph>partial</emph> description of a service. Although it captures the basic mechanics of interacting with the service -- the message types, transmission protocols, service location, etc. -- in general, additional documention will need to explain other application-level requirements for its use. For example, such documentationshould explain the purpose and use of the service, the meanings of all messages, constraints on their use, and the sequence in which operations should be invoked.</p><p>The <el><documentation></el> element allows you to include some human-readable documentation inside your WSDL document. It is a convenient place to reference any additional documentation that a client developer may need in order to use your service. It can appear in a number of places in a WSDL 2.0 document (as you can see in the syntax summary presented later), though in this example we have only demonstrated its use at the beginning.</p><example id="example-initial-documentation">
! <head>Documenting the GreatH Service</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
<description
***************
*** 346,350 ****
<documentation>
This document describes the GreatH Web service. Additional
! application-level requirements for its use of this service --
beyond what WSDL 2.0 is able to describe -- are available
at http://greath.example.com/2004/reservation-documentation.html
--- 346,350 ----
<documentation>
This document describes the GreatH Web service. Additional
! application-level requirements for use of this service --
beyond what WSDL 2.0 is able to describe -- are available
at http://greath.example.com/2004/reservation-documentation.html
***************
*** 358,369 ****
</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>
!
! <p>WSDL 2.0 offers two mechanisms for extensibility: an open content model; and Features and Properties.<ulist><item><p>@@ TODO: Reduce the amount of detail in the next paragraph. It is too much detail for this overview section.@@</p><p>WSDL 2.0's <emph>open content model</emph> allows XML elements from non-WSDL namespaces to be intermingled with WSDL constructs in a WSDL document. As specified in section 6 of Part1, WSDL allows extensions to be defined in terms of both elements and attributes. Namespace-qualified elements
! whose namespace is NOT "http://www.w3.org/2004/03/wsdl" (i.e., non-WSDL elements) may appear among the children of specific elements whose [namespace name] is "http://www.w3.org/2004/03/wsdl" (i.e., WSDL elements). Also, WSDL allows qualified attributes whose namespace is NOT "http://www.w3.org/2004/03/wsdl" (i.e., non-WSDL attributes) to appear on any elements whose namespace is "http://www.w3.org/2004/03/wsdl" (i.e., WSDL elements). See more about extensibility in section@@@@. Since extensions can appear anywhere, they are not explicitly indicated in the above syntax and will not be mentioned again in later sections where a particular construct is explained. </p></item><item><p>WSDL 2.0's <emph>Features and Properties</emph> (F&P) mechanism provides another way to specify extensions in a WSDL document, and offers slightly more structure for extensions than the open content model offers. A WSDL 2.0 Feature allows a particular extension to be unambiguously identified by a URI. WSDL 2.0 Properties coplement the notion of Features. Properties permit data values to be associated with Features. For example, a particular extension may require a parameter, and a Property may be used to indicate a value for that parameter.</p></item></ulist></p><p>@@ TODO: Explain optional and required extensions @@</p>
!
!
! </div2><div2><head>XML Syntax Summary</head><p>In the core language specification, WSDL 2.0 constructs are defined as a set of abstract components, along with a mapping to an XML infoset representation for these components. For easier consumption, the primer uses the XML representation of WSDL components and the XML syntax as summarized below to illustrate the language. The following conventions are followed for the syntax: </p>
<ulist>
<item>
--- 358,362 ----
</description>]]></eg>
! </example><div3 id="example-initial-documentation-explanation"><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><p>This completes our presentation of the GreatH example. Let's summarize the syntax we've seen. </p></div3></div2><div2 id="basics-syntax"><head>XML Syntax Summary</head><p>In the core language specification, WSDL 2.0 constructs are defined as a set of abstract components, along with a mapping to an XML infoset representation for these components. For easier consumption, the primer uses the XML representation of WSDL components. The followingconventions are followed for the syntax: </p>
<ulist>
<item>
***************
*** 374,382 ****
</item>
<item>
! <p>Elements names ending in "…" (such as <element…/> or <element…>) indicate that elements/attributes irrelevant to the context are being omitted.</p>
</item>
</ulist>
! <p>@@ TODO: Add an abridged version of this syntax overview, listing only the most important elements described above. @@</p><p>@@ TODO: Delete the <documentation> elements, because they're mentioned below. @@</p><eg xml:space="preserve">
<definitions targetNamespace="<emph>xs:anyURI</emph>" >
<documentation />?
--- 367,377 ----
</item>
<item>
! <p>Elements names ending in "..." (such as <element…/> or <element…>) indicate that elements/attributes irrelevant to the context are being omitted.</p>
</item>
</ulist>
! <ednote><name>dbooth</name><edtext>To do: check the above elipses (...), as they weren't rendering properly at one point.</edtext></ednote><div3 id="basics-syntax-brief"><head>Brief Syntax Summary</head><eg xml:space="preserve">
! @@To do: Insert short summary here@@
! </eg></div3><div3 id="basics-syntax-longer"><head>Longer Syntax Summary</head><ednote><name>dbooth</name><edtext>To do: Update this, and delete the <documentation>, <feature> and <property> elements, because they're mentioned below.</edtext></ednote><eg xml:space="preserve">
<definitions targetNamespace="<emph>xs:anyURI</emph>" >
<documentation />?
***************
*** 517,525 ****
! <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>
--- 512,520 ----
! <p>In addition, <el><feature></el> and <el><property></el> elements are allowed inside most WSDL elements. Also, an optional <el><documentation></el> element is 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></div3></div2></div1>
<!-- ******************MessageTypes********************************** -->
<!-- ******************MessageTypes********************************** -->
! <div1 id="more-types"><head>More on Message Types</head><div2 id="more-types-schema">
<head>Defining Messages Using XML Schema</head>
***************
*** 542,546 ****
<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">
<head>Importing XML Schema</head>
<p>Let's examine the XML Schema <el>import</el> first. Note the schema import mechanism described here is defined in XML Schema Language with some additional restrictions. It is different from the WSDL import/include as explained in section @@@@. The schema components defined in the imported schema are available for reference by QName (see section @@@@ ). Note that only components defined in the schema itself and components included by it via <el>xs:include</el> are available to WSDL. Specifically, components that the schema imports via <el>xs:import</el> are NOT available to WSDL.</p>
--- 537,541 ----
<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="more-types-schema-import">
<head>Importing XML Schema</head>
<p>Let's examine the XML Schema <el>import</el> first. Note the schema import mechanism described here is defined in XML Schema Language with some additional restrictions. It is different from the WSDL import/include as explained in section @@@@. The schema components defined in the imported schema are available for reference by QName (see section @@@@ ). Note that only components defined in the schema itself and components included by it via <el>xs:include</el> are available to WSDL. Specifically, components that the schema imports via <el>xs:import</el> are NOT available to WSDL.</p>
***************
*** 558,562 ****
</ulist>
</div3>
! <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
--- 553,557 ----
</ulist>
</div3>
! <div3 id="more-types-schema-embed">
<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
***************
*** 602,606 ****
<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">
--- 597,601 ----
<p>Here is an example of importing a schema.</p>
<example id="example-schema-import">
! <head>Importing Message Definitions into WSDL 2.0</head>
<ednote><edtext>Need to update this example.</edtext></ednote><eg xml:space="preserve">
***************
*** 632,714 ****
</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>
- <item>
- <p>
- <b>In-Only</b> ("http://www.w3.org/2004/03/wsdl/in-only")</p>
- <p>This patten consists of exactly one message received by a service from some other node. No fault maybe generated. </p>
- </item>
- <item>
- <p>
- <b>Robust In-Only</b> ("http://www.w3.org/2004/03/wsdl/robust-in-only")</p>
- <p>This pattern can be considered as a variation of In-only. It also consists of exactly one message received by a service, but in this case faults can be triggered by the message as specified in the "Message Triggers Fault" model. </p>
- </item>
- <item>
- <p>
- <b>In-Out</b> ("http://www.w3.org/2004/03/wsdl/in-out")</p>
- <p>This patten consists of exactly two message: a message received by a service from some other node, followed by a message sent to the other node. The second message may be replaced by a fault as specified in the "Fault Replace Message" model. </p>
- </item>
- <item>
- <p>
- <b>In-Optional-Out</b> ("http://www.w3.org/2004/03/wsdl/in-opt-out")</p>
- <p>This patten consists of one or two messages: a message received by a service from some other node, optionally followed by a message sent to the other node from the service. Each message may trigger a fault in response as specified in the "Message Triggers Faults" model. </p>
- </item>
- </ulist>
- <p>WSDL2.0 also defines four out-bound MEPs which sort of mirror the in-bound MEPs with reserved direction:</p>
- <ulist>
- <item>
- <p>
- <b>Out-Only</b> ("http://www.w3.org/2004/03/wsdl/out-only")</p>
- <p>This patten consists of exactly one message sent to some other node from a service. No fault maybe generated. </p>
- </item>
- <item>
- <p>
- <b>Robust Out-Only</b> ("http://www.w3.org/2004/03/wsdl/robust-out-only")</p>
- <p>This pattern can be considered as a variation of Out-only. It also consists of exactly one message sent to some other node from a service, but in this case faults can be triggered by the message as specified in the "Message Triggers Fault" model. </p>
- </item>
- <item>
- <p>
- <b>Out-in</b> ("http://www.w3.org/2004/03/wsdl/out-in")</p>
- <p>This patten consists of exactly two message: a message sent to some other node from a service, followed by a message received by the service from the other node. The second message may be replaced by a fault as specified in the "Fault Replace Message" model. </p>
- </item>
- <item>
- <p>
- <b>Out-Optional-In</b> ("http://www.w3.org/2004/03/wsdl/out-opt-in")</p>
- <p>This patten consists of one or two messages: a message sent to some other node from a service, optionally followed by a message received by the service from the other node. Each message may trigger a fault in response as specified in the "Message Triggers Faults" model. </p>
- </item>
- </ulist>
- <p>While the in-bound MEPs are easier to understand, there have been questions concerning the usefulness of out-bound MEPs, especially how a service can specify the endpoint information for the target node of the initial out-bound message. In their typical use cases, such as in large scale intergration projects where endpoint information is most likely specified at deployment or runtime by mapping and routing facilities, or/and in languages that facilitate services composition where only abstract interfaces are concerned, Out-bound MEPs are useful in the abstract level for fully specifying the functionality of a service, including its requirements for its potential customers, so application integrator can gain a better understanding of how multiple services may be used together, whereas binding and endpoint information may be provided by integration infrastructure in application deployment and runtime.</p>
- <ednote>
- <name>KevinL</name>
- <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>" >
--- 627,637 ----
</div3>
! </div2></div1><!-- ******************Interface********************************** --><!-- ******************Interface********************************** --><div1 id="more-interfaces">
<head>More on Interfaces</head>
<!-- ************************interface*************************** -->
! <p>We previously mentioned that a WSDL 2.0 <el>interface</el> is basically a set of <el>operation</el>s. However, there are some additional capabilities that we have not yet covered. First, let's review the syntax for <el>interface</el>.</p><div2 id="more-interfaces-interfaces">
! <head>Interface Syntax </head>
! <ednote><name>dbooth</name><edtext>To do: Simplify this syntax summary.</edtext></ednote><p>Below is the XML syntax summary of the <el>interface</el> element:</p>
<eg xml:space="preserve">
<definitions targetNamespace="<emph>xs:anyURI</emph>" >
***************
*** 784,788 ****
<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>
--- 707,711 ----
<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="more-interfaces-inheritance">
<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>
***************
*** 798,807 ****
<p>Now let's have a look at the children of <el>interface</el>. An <el>interface</el> 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>. <el>feature</el> and <el>property</el> will be examined in section @@@@. We will explain the <el>fault</el> and <el>operation</el> constructs in the following sections. </p>
</div3>
! <div3 id="fault">
<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">
--- 721,730 ----
<p>Now let's have a look at the children of <el>interface</el>. An <el>interface</el> 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>. <el>feature</el> and <el>property</el> will be examined in section @@@@. We will explain the <el>fault</el> and <el>operation</el> constructs in the following sections. </p>
</div3>
! <div3 id="more-interfaces-faults">
<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>To do: Update this example</edtext></ednote><example id="example-faults">
<head>Declaring interface faults</head>
<eg xml:space="preserve">
***************
*** 858,862 ****
</ednote>
</div3>
! <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>
--- 781,785 ----
</ednote>
</div3>
! <div3 id="more-interfaces-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>
***************
*** 893,897 ****
<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">
--- 816,820 ----
<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>To do: Update this example. Also: which features should it illustrate?</edtext></ednote><example id="example-operations">
<head>Defining Interface Operations</head>
<eg xml:space="preserve">
***************
*** 954,961 ****
</div3>
</div2>
! </div1>
<!-- **********************************Binding************************** -->
<!-- **********************************Binding************************** -->
! <div1 id="binding">
<head>More on Bindings</head>
--- 877,956 ----
</div3>
</div2>
! <!-- ************************messages*************************** -->
!
! <!-- ************************MEPs*************************** -->
! <div2 id="more-interfaces-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>
! <item>
! <p>
! <b>In-Only</b> ("http://www.w3.org/2004/03/wsdl/in-only")</p>
! <p>This patten consists of exactly one message received by a service from some other node. No fault maybe generated. </p>
! </item>
! <item>
! <p>
! <b>Robust In-Only</b> ("http://www.w3.org/2004/03/wsdl/robust-in-only")</p>
! <p>This pattern can be considered as a variation of In-only. It also consists of exactly one message received by a service, but in this case faults can be triggered by the message as specified in the "Message Triggers Fault" model. </p>
! </item>
! <item>
! <p>
! <b>In-Out</b> ("http://www.w3.org/2004/03/wsdl/in-out")</p>
! <p>This patten consists of exactly two message: a message received by a service from some other node, followed by a message sent to the other node. The second message may be replaced by a fault as specified in the "Fault Replace Message" model. </p>
! </item>
! <item>
! <p>
! <b>In-Optional-Out</b> ("http://www.w3.org/2004/03/wsdl/in-opt-out")</p>
! <p>This patten consists of one or two messages: a message received by a service from some other node, optionally followed by a message sent to the other node from the service. Each message may trigger a fault in response as specified in the "Message Triggers Faults" model. </p>
! </item>
! </ulist>
! <p>WSDL2.0 also defines four out-bound MEPs which sort of mirror the in-bound MEPs with reserved direction:</p>
! <ulist>
! <item>
! <p>
! <b>Out-Only</b> ("http://www.w3.org/2004/03/wsdl/out-only")</p>
! <p>This patten consists of exactly one message sent to some other node from a service. No fault maybe generated. </p>
! </item>
! <item>
! <p>
! <b>Robust Out-Only</b> ("http://www.w3.org/2004/03/wsdl/robust-out-only")</p>
! <p>This pattern can be considered as a variation of Out-only. It also consists of exactly one message sent to some other node from a service, but in this case faults can be triggered by the message as specified in the "Message Triggers Fault" model. </p>
! </item>
! <item>
! <p>
! <b>Out-in</b> ("http://www.w3.org/2004/03/wsdl/out-in")</p>
! <p>This patten consists of exactly two message: a message sent to some other node from a service, followed by a message received by the service from the other node. The second message may be replaced by a fault as specified in the "Fault Replace Message" model. </p>
! </item>
! <item>
! <p>
! <b>Out-Optional-In</b> ("http://www.w3.org/2004/03/wsdl/out-opt-in")</p>
! <p>This patten consists of one or two messages: a message sent to some other node from a service, optionally followed by a message received by the service from the other node. Each message may trigger a fault in response as specified in the "Message Triggers Faults" model. </p>
! </item>
! </ulist>
! <p>While the in-bound MEPs are easier to understand, there have been questions concerning the usefulness of out-bound MEPs, especially how a service can specify the endpoint information for the target node of the initial out-bound message. In their typical use cases, such as in large scale intergration projects where endpoint information is most likely specified at deployment or runtime by mapping and routing facilities, or/and in languages that facilitate services composition where only abstract interfaces are concerned, Out-bound MEPs are useful in the abstract level for fully specifying the functionality of a service, including its requirements for its potential customers, so application integrator can gain a better understanding of how multiple services may be used together, whereas binding and endpoint information may be provided by integration infrastructure in application deployment and runtime.</p>
! <ednote>
! <name>KevinL</name>
! <date>20040910</date>
! <edtext>
! Add more use cases and example - illustrate use of outbound meps?
!
! </edtext>
! </ednote>
!
!
! </div2></div1>
<!-- **********************************Binding************************** -->
<!-- **********************************Binding************************** -->
! <div1 id="more-bindings">
<head>More on Bindings</head>
***************
*** 979,983 ****
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>
<p>Let's have a look at the constructs defined within the WSDL namespace first. The XML syntax of these constructs is summarized below:</p>
--- 974,978 ----
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="more-bindings-wsdl">
<head>Binding Constructs in WSDL Namespace</head>
<p>Let's have a look at the constructs defined within the WSDL namespace first. The XML syntax of these constructs is summarized below:</p>
***************
*** 1022,1029 ****
</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>
<p>A binding <el>fault</el> describes a concrete binding of an abstract fault
--- 1017,1024 ----
</edtext>
</ednote>
! <ednote><name>dbooth</name><edtext>Trim some of this? Redundant?</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="more-bindings-faults">
<head>Binding Faults</head>
<p>A binding <el>fault</el> describes a concrete binding of an abstract fault
***************
*** 1036,1040 ****
</div3>
<div3 id="bindingOperations">
! <head>Binding Operations</head>
<p>A binding <el>operation</el> describes a concrete binding of a particular
operation of an interface to a particular concrete message format.A particular
--- 1031,1035 ----
</div3>
<div3 id="bindingOperations">
! <head id="more-bindings-operations">Binding Operations</head>
<p>A binding <el>operation</el> describes a concrete binding of a particular
operation of an interface to a particular concrete message format.A particular
***************
*** 1054,1060 ****
</div3>
</div2>
! <div2 id="SOAPBindingExtension">
<head>Extensions for SOAP Binding</head>
! <example>
<head>SOAP binding example placeholder - to be completed</head>
<eg xml:space="preserve">
--- 1049,1055 ----
</div3>
</div2>
! <div2 id="more-bindings-soap">
<head>Extensions for SOAP Binding</head>
! <example id="example-binding-soap">
<head>SOAP binding example placeholder - to be completed</head>
<eg xml:space="preserve">
***************
*** 1070,1076 ****
</example>
</div2>
! <div2 id="HTTPBindingExtension">
<head>Extensions for HTTP Binding</head>
! <example>
<head>HTTP Binding example placeholder - to be completed</head>
<eg xml:space="preserve">
--- 1065,1071 ----
</example>
</div2>
! <div2 id="more-bindings-http">
<head>Extensions for HTTP Binding</head>
! <example id="example-bindings-http">
<head>HTTP Binding example placeholder - to be completed</head>
<eg xml:space="preserve">
***************
*** 1088,1094 ****
<!-- **********************************Service************************** -->
<!-- **********************************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>" >
--- 1083,1089 ----
<!-- **********************************Service************************** -->
<!-- **********************************Service************************** -->
! <div1 id="more-service">
<head>More on Service Endpoints </head>
! <ednote><name>dbooth</name><edtext>This section now seems largely redundant. Perhaps we should reduce or eliminate it.</edtext></ednote><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. However, each service is limited to a single interface. The XML syntax of <el>service</el> is summarized below:</p>
<eg xml:space="preserve">
<definitions targetNamespace="<emph>xs:anyURI</emph>" >
***************
*** 1109,1125 ****
<p>Like the WSDL binding constructs explained in section @@@@, the WSDL <el>endpoint</el> construct is also like an anchor for hosting extension elements that are used to provide information specific to a
particular endpoint in a server. The semantics of such extensions are defined by the specification for those extensions. Such specifications are expected to annotate the WSDL <el>endpoint</el> construct with additional properties and specify the mapping between those properties and the XML representation. For example, The SOAP and HTTP binding extensions defined in WSDL 2.0 part 3 also provides extensions to be used under a service <el>endpoint</el>. </p>
! <example>
! <head>place holder - to be completed</head>
! <eg xml:space="preserve">
! <definitions
! targetNamespace= "http://www.greath.com/2004/05/wsdl/resSvc.wsdl"
! xmlns:ghns = "http://www.greath.com/2004/05/schemas/resSvc.xsd"
! xmlns = "http://www.w3.org/@@@@/@@/wsdl"
! xmlns:xs="http://www.w3.org/2001/XMLSchema">
!
!
! </definitions>
! </eg>
! </example>
</div1>
<!-- **********************************AdvancedTopics***************** -->
--- 1104,1108 ----
<p>Like the WSDL binding constructs explained in section @@@@, the WSDL <el>endpoint</el> construct is also like an anchor for hosting extension elements that are used to provide information specific to a
particular endpoint in a server. The semantics of such extensions are defined by the specification for those extensions. Such specifications are expected to annotate the WSDL <el>endpoint</el> construct with additional properties and specify the mapping between those properties and the XML representation. For example, The SOAP and HTTP binding extensions defined in WSDL 2.0 part 3 also provides extensions to be used under a service <el>endpoint</el>. </p>
!
</div1>
<!-- **********************************AdvancedTopics***************** -->
***************
*** 1141,1183 ****
- Differences b/t WSDL2.0 and WSDL1.1?
</p>
! <div2>
! <head>Import mechanism and authoring style</head>
! <p>[Discuss how WSDL documents should be factored to allow significant components to be reused.]</p>
! </div2>
! <div2>
<head>Extensibility</head>
! <p>WSDL 2.0 provides two extensibility mechanisms: an open content model, which allows XML elements and attributes from other (non-wsdl) XML namespaces to be interspersed into a WSDL document; and <xspecref href="&w3c-designation-part1;#Features">Features</xspecref> and <xspecref href="&w3c-designation-part1;#Properties">Properties</xspecref>. Both mechanisms use URIs to identify the semantics of the extensions. For extension XML elements and attributes, the namespace URI of the extension element or attribute acts as an unambiguous name for the semantics of that extension. For Features and Properties, the Feature or Property is named by a URI.</p><p>In either case, the URI that identifies the semantics of an extension SHOULD be dereferenceable to a document that describes the semantics of that extension. As of this writing, there is no generally accepted standard for what kind of document that should be. However, the <loc href="http://www.w3.org/2001/tag/">W3C TAG</loc> has been discussing the isue (see TAG issue <loc href="http://www.w3.org/2001/tag/issues.html?type=1#namespaceDocument-8">namespaceDocument-8</loc>) and is likely to provide guidance at some point.</p><div3><head>Optional Versus Required Extensions</head><p>Extensions can either be required or optional: An <emph>optional</emph> extension is one that the requester agent may either engage or ignore, entirely at its discretion, and is signaled by attribute <code>wsdl:required="false"</code>; whereas a <emph>required</emph> extension is one that MUST be supported and engaged by the requester agent in order for the interaction to succeed properly, and is signaled by attribute <code>wsdl:required="true"</code>. </p><p>The optionality signaled by <code>wsdl:required="false"</code> pertains only to the <emph>requester</emph> agent -- not the provider agent. The provider agent MUST support both optional and required extensions that it advertises in its WSDL document. </p><p>A WSDL processor (acting to realize a requester agent) need no support every conceivable required extension, but if it sees a required extension that it does not recognize or does not support, then it MUST fault. </p></div3><div3><head>Scoping of the wsdl:required Attribute</head><p>@@ Need to check the scoping rules to see if this is correct. @@</p><p>As a convenience mechanism, the <code>wsdl:required</code> attribute need not be specified on every extension element. If it is omitted from an extension element, its effective value is inherited from the smallest enclosing scope that explicitly sets its value. If there is no enclosing scope that explicitly sets its value, then its value defaults to <code>false</code>. </p><p>Because portions of a Web service description can be written in different physical documents by different people, you should be cautious about setting <code>wsdl:required="false"</code> when an outer scope, written by someone else, had set <code>wsdl:required="true"</code>.</p><p>@@ Add example? @@</p></div3></div2>
! <div2 id="FP">
<head>Features and Properties</head>
<p>[Add material from http://lists.w3.org/Archives/Public/www-ws-desc/2003Oct/0144.html ]</p>
</div2>
! <div2><head>MTOM Support</head>
<p>This section shows how Features and Properties can be used to indicate the use of MTOM. @@ Example from GlenD: http://lists.w3.org/Archives/Public/www-ws-desc/2004May/0076.html @@</p>
</div2>
! <div2>
<head>Security Considerations</head>
</div2>
<div2>
! <head>Versioning and services equivalency</head>
<p>[ See also <loc href="http://lists.w3.org/Archives/Public/www-ws-desc/2003Dec/0047.html">http://lists.w3.org/Archives/Public/www-ws-desc/2003Dec/0047.html</loc> ]</p>
<p>Per decision 2004-03-04 to add the results of the Versioning Task Force also.</p>
</div2>
! <div2 id="RPCstyle">
<head>Operation Style and RPC</head>
</div2>
! <div2><head>GET Versus POST: Which to Use?</head>
<p>[Add material from http://lists.w3.org/Archives/Public/www-ws-desc/2003Mar/0068.html that prescribes when to use GET versus POST as well as some useful example]</p>
</div2>
! <div2>
<head>Service References</head>
<p>[Use http://lists.w3.org/Archives/Public/www-ws-desc/2003Oct/0345.htm as a starting point. Also example(s) from Roberto per the resolution at the end of http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0061.html ]</p>
</div2>
! <div2><head>XML Schema Examples</head>
<p>[Add Paul Downey's contribution at http://lists.w3.org/Archives/Public/www-ws-desc/2004May/0007.html ]</p>
</div2>
! <div2><head>Multiple In-Line Schemas</head><p>[Need to explain that this can be done. See
http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0109.html
--- 1124,1174 ----
- Differences b/t WSDL2.0 and WSDL1.1?
</p>
! <div2 id="adv-extensibility">
<head>Extensibility</head>
! <p>WSDL 2.0 provides two extensibility mechanisms: an open content model, which allows XML elements and attributes from other (non-wsdl) XML namespaces to be interspersed into a WSDL document; and <xspecref href="&w3c-designation-part1;#Features">Features</xspecref> and <xspecref href="&w3c-designation-part1;#Properties">Properties</xspecref>. Both mechanisms use URIs to identify the semantics of the extensions. For extension XML elements and attributes, the namespace URI of the extension element or attribute acts as an unambiguous name for the semantics of that extension. For Features and Properties, the Feature or Property is named by a URI.</p><p>In either case, the URI that identifies the semantics of an extension SHOULD be dereferenceable to a document that describes the semantics of that extension. As of this writing, there is no generally accepted standard for what kind of document that should be. However, the <loc href="http://www.w3.org/2001/tag/">W3C TAG</loc> has been discussing the isue (see TAG issue <loc href="http://www.w3.org/2001/tag/issues.html?type=1#namespaceDocument-8">namespaceDocument-8</loc>) and is likely to provide guidance at some point.</p><div3 id="adv-optional-versus-required"><head>Optional Versus Required Extensions</head><p>Extensions can either be required or optional: An <emph>optional</emph> extension is one that the requester agent may either engage or ignore, entirely at its discretion, and is signaled by attribute <code>wsdl:required="false"</code>; whereas a <emph>required</emph> extension is one that MUST be supported and engaged by the requester agent in order for the interaction to succeed properly, and is signaled by attribute <code>wsdl:required="true"</code>. </p><p>The optionality signaled by <code>wsdl:required="false"</code> pertains only to the <emph>requester</emph> agent -- not the provider agent. The provider agent MUST support both optional and required extensions that it advertises in its WSDL document. </p><p>A WSDL processor (acting to ealize a requester agent) need not support every conceivable required extension, but if it sees a required extension that it does not recognize or does not support, then it MUST fault. </p></div3><div3 id="adv-scope-of-wsdl-required"><head>Scoping of the wsdl:required Attribute</head><p>@@ Need to check the scoping rules to see if this is correct. @@</p><p>As a convenience mechanism, the <code>wsdl:required</code> attribute need not be specified on every extension element. If it is omitted from an extension element, its effective value is inherited from the smallest enclosing scope that explicitly sets its value. If there is no enclosing scope that explicitly sets its value, then its value defaults to <code>false</code>. </p><p>Because portions of a Web service description can be written in different physical documents by different people, you should be cautious about setting <code>wsdl:required="false"</code> when an outer scope, written by someone else, had set <code>wsdl:required="true"</code>.</p>p>@@ Add example? @@</p></div3></div2><div2 id="adv-FP">
<head>Features and Properties</head>
<p>[Add material from http://lists.w3.org/Archives/Public/www-ws-desc/2003Oct/0144.html ]</p>
+ </div2><div2 id="adv-multiple-docs-describing-same-service">
+ <head>Multiple Logical WSDL Documents Describing the Same Service</head>
+ <p>[Acknowledge that multiple logical WSDL documents might try to describe the same service. Explain why some might do this intentionally, why it might cause problems for some systems, and explain that this is outside scope of the WSDL language. See thread starting at http://lists.w3.org/Archives/Public/www-ws-desc/2003Dec/0045.html ]</p>
+ </div2><div2 id="adv-import-and-authoring">
+ <head>Import mechanism and authoring style</head>
+ <p>[Discuss how WSDL documents should be factored to allow significant components to be reused.]</p>
</div2>
!
!
! <div2 id="adv-MTOM"><head>MTOM Support</head>
<p>This section shows how Features and Properties can be used to indicate the use of MTOM. @@ Example from GlenD: http://lists.w3.org/Archives/Public/www-ws-desc/2004May/0076.html @@</p>
</div2>
! <div2 id="adv-security">
<head>Security Considerations</head>
</div2>
<div2>
! <head>Versioning and Service Equivalency</head>
<p>[ See also <loc href="http://lists.w3.org/Archives/Public/www-ws-desc/2003Dec/0047.html">http://lists.w3.org/Archives/Public/www-ws-desc/2003Dec/0047.html</loc> ]</p>
<p>Per decision 2004-03-04 to add the results of the Versioning Task Force also.</p>
</div2>
! <div2 id="adv-RPCstyle">
<head>Operation Style and RPC</head>
</div2>
! <div2 id="adv-message-dispatch">
! <head>Enabling Easy Message Dispatch</head>
! <p>Suppose a WSDL document has two input-output operation and uses the same input message schema for both. When the service receives the input message, how will the service know which operation is supposed to be invoked? Although the data contained in a runtime message may be sufficient to distinguish between the operations, this can be a problem for WSDL toolkits that are looking only at the message schema, rather than the actual messages. (For example, the toolkit may be operating at designtime, without access to the runtime messages.) This is the problem of <emph>dispatch</emph>. How can you write your WSDL document to ensure easy message dispatch? </p>
! <p>One technique is to ensure that the top-level elements declared in your message schema are different for different operations. This is probably the most general solution, since it is guaranteed to provide a way to perform dispatch, without preventing toolkits from potentially using other dispatch techniques.</p>
! <p>Another technique is to define a required feature that enables a particular dispatching convention. This approach makes the dispatching convention explicit, although it may not be supported by every WSDL toolkit.</p>
! </div2><div2 id="adv-get-vs-post"><head>GET Versus POST: Which to Use?</head>
<p>[Add material from http://lists.w3.org/Archives/Public/www-ws-desc/2003Mar/0068.html that prescribes when to use GET versus POST as well as some useful example]</p>
</div2>
! <div2 id="adv-service-references">
<head>Service References</head>
<p>[Use http://lists.w3.org/Archives/Public/www-ws-desc/2003Oct/0345.htm as a starting point. Also example(s) from Roberto per the resolution at the end of http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0061.html ]</p>
</div2>
! <div2 id="adv-xml-schema-examples"><head>XML Schema Examples</head>
<p>[Add Paul Downey's contribution at http://lists.w3.org/Archives/Public/www-ws-desc/2004May/0007.html ]</p>
</div2>
! <div2 id="adv-multiple-inline-schemas"><head>Multiple In-Line Schemas</head><p>[Need to explain that this can be done. See
http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0109.html
***************
*** 1185,1189 ****
http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0130.html ]</p>
</div2>
! <div2>
<head>schemaLocation</head>
<p>[ACTION: 2003-11-13: David to add discussion / example(s) re:
--- 1176,1180 ----
http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0130.html ]</p>
</div2>
! <div2 id="adv-schema-location">
<head>schemaLocation</head>
<p>[ACTION: 2003-11-13: David to add discussion / example(s) re:
***************
*** 1192,1210 ****
See discussion in http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0135.html and thread called "Schemas in imported WSDL" in http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/thread.html ]</p>
</div2>
! <div2>
! <head>Multiple Logical WSDL Documents Describing the Same Service</head>
! <p>[Acknowledge that multiple logical WSDL documents might try to describe the same service. Explain why some might do this intentionally, why it might cause problems for some systems, and explain that this is outside scope of the WSDL language. See thread starting at http://lists.w3.org/Archives/Public/www-ws-desc/2003Dec/0045.html ]</p>
! </div2>
! <div2>
<head>Mapping to RDF and semantic web</head>
</div2>
! <div2>
! <head>Enabling Easy Message Dispatch</head>
! <p>Suppose a WSDL document has two input-output operation and uses the same input message schema for both. When the service receives the input message, how will the service know which operation is supposed to be invoked? Although the data contained in a runtime message may be sufficient to distinguish between the operations, this can be a problem for WSDL toolkits that are looking only at the message schema, rather than the actual messages. (For example, the toolkit may be operating at designtime, without access to the runtime messages.) This is the problem of <emph>dispatch</emph>. How can you write your WSDL document to ensure easy message dispatch? </p>
! <p>One technique is to ensure that the top-level elements declared in your message schema are different for different operations. This is probably the most general solution, since it is guaranteed to provide a way to perform dispatch, without preventing toolkits from potentially using other dispatch techniques.</p>
! <p>Another technique is to define a required feature that enables a particular dispatching convention. This approach makes the dispatching convention explicit, although it may not be supported by every WSDL toolkit.</p>
! </div2><!-- **********************************NotesOnURIs***************** --><div2><head>Notes on URIs</head><p>This section does not directly contribute to the
specification, but provide background that may be useful when
! implementing the specification.</p><div3><head>XML namespaces and schema locations</head><p>It is a common misperception to equate the <att>
targetNamespace</att> of an XML schema or the value of the
<att>xmlns</att> attribute in XML instances with the location
--- 1183,1193 ----
See discussion in http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0135.html and thread called "Schemas in imported WSDL" in http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/thread.html ]</p>
</div2>
!
! <div2 id="adv-rdf-mapping">
<head>Mapping to RDF and semantic web</head>
</div2>
! <!-- **********************************NotesOnURIs***************** --><div2 id="adv-notes-on-uris"><head>Notes on URIs</head><p>This section does not directly contribute to the
specification, but provide background that may be useful when
! implementing the specification.</p><div3 id="adv-namespaces-and-schema-locations"><head>XML namespaces and schema locations</head><p>It is a common misperception to equate the <att>
targetNamespace</att> of an XML schema or the value of the
<att>xmlns</att> attribute in XML instances with the location
***************
*** 1218,1227 ****
specification provides the processing context here via the
<att>import</att> mechanism, which is based on the XML
! schemas grammar for the similar concept.</p></div3><div3><head>Relative URIs</head><p>Throughout this document you see fully qualified URIs used
in WSDL and XSD documents. The use of a fully qualified URI
is simply to illustrate the referencing concepts. The use of
relative URIs is completely allowed and is warranted in many
cases. For information on processing relative URIs, see
! <loc href="http://www.ietf.org/rfc/rfc2396.txt">RFC2396</loc>.</p></div3><div3><head>Generating URIs</head><p>When working with WSDL, it is sometimes desirable to make
up a URI for an entity, but not make the URI globally unique
for all time and have it "mean" that version of the
--- 1201,1210 ----
specification provides the processing context here via the
<att>import</att> mechanism, which is based on the XML
! schemas grammar for the similar concept.</p></div3><div3 id="adv-relative-uris"><head>Relative URIs</head><p>Throughout this document you see fully qualified URIs used
in WSDL and XSD documents. The use of a fully qualified URI
is simply to illustrate the referencing concepts. The use of
relative URIs is completely allowed and is warranted in many
cases. For information on processing relative URIs, see
! <loc href="http://www.ietf.org/rfc/rfc2396.txt">RFC2396</loc>.</p></div3><div3 id="adv-generating-uris"><head>Generating URIs</head><p>When working with WSDL, it is sometimes desirable to make
up a URI for an entity, but not make the URI globally unique
for all time and have it "mean" that version of the
Index: wsdl20-primer.html
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.html,v
retrieving revision 1.10
retrieving revision 1.11
diff -C2 -d -r1.10 -r1.11
*** wsdl20-primer.html 15 Dec 2004 05:06:08 -0000 1.10
--- wsdl20-primer.html 15 Dec 2004 19:24:29 -0000 1.11
***************
*** 140,148 ****
<p class="toc">1. <a href="#Introduction">Introduction</a><br />
! 2. <a href="#IntroductionWS">WSDL 2.0 Basics</a><br />
! 3. <a href="#id5196006">More on Message Types</a><br />
! 4. <a href="#interface">More on Interfaces</a><br />
! 5. <a href="#binding">More on Bindings</a><br />
! 6. <a href="#Service">More on Service Endpoints</a><br />
7. <a href="#advanced">Advanced Topics - TBD</a><br />
8. <a href="#References">References</a><br />
--- 140,148 ----
[...2043 lines suppressed...]
<div class="div3">
! <h4><a id="adv-relative-uris" name="adv-relative-uris"></a>7.16.2
! Relative URIs</h4>
<p>Throughout this document you see fully qualified URIs used in
***************
*** 3210,3214 ****
<div class="div3">
! <h4>7.16.3 Generating URIs</h4>
<p>When working with WSDL, it is sometimes desirable to make up a
--- 3267,3272 ----
<div class="div3">
! <h4><a id="adv-generating-uris"
! name="adv-generating-uris"></a>7.16.3 Generating URIs</h4>
<p>When working with WSDL, it is sometimes desirable to make up a
Received on Wednesday, 15 December 2004 19:24:33 UTC