- From: Kevin Liu via cvs-syncmail <cvsmail@w3.org>
- Date: Fri, 24 Jun 2005 23:34:01 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20
In directory hutz:/tmp/cvs-serv11087/ws/desc/wsdl20
Modified Files:
wsdl20-primer.html wsdl20-primer.xml
Log Message:
Further reorganize the contents. Now the topics are grouped into 4 major sections:
2. WSDL 2.0 Basics
3. Advanced Topics I: Importing Mechanisms
4. Advanced Topics II: Extensibility and Predefined Extensions
5. Advanced Topics III: Miscellaneous
Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.107
retrieving revision 1.108
diff -C2 -d -r1.107 -r1.108
*** wsdl20-primer.xml 24 Jun 2005 22:13:54 -0000 1.107
--- wsdl20-primer.xml 24 Jun 2005 23:33:59 -0000 1.108
***************
*** 86,90 ****
<!-- ****************Introduction********************************* -->
<div1 id="Introduction">
! <head>Introduction</head>
<div2 id="Prerequisites"><head>Prerequisites</head>
<p>This primer assumes that the reader has the following prerequisite knowledge:
--- 86,90 ----
<!-- ****************Introduction********************************* -->
<div1 id="Introduction">
! <head>Introduction</head>
<div2 id="Prerequisites"><head>Prerequisites</head>
<p>This primer assumes that the reader has the following prerequisite knowledge:
***************
*** 99,108 ****
! <p>Section 2 presents a hypothetical use case involving a hotel reservation service. It then proceeds step-by-step through the development of a simple example WSDL 2.0 document that describes this service:<ulist><item><p>The <code>types</code> element describes the kinds of messages that the service will send and receive. </p></item><item><p>The <code>interface</code> element describes <emph>what</emph> abstract functionality the Web service provides. </p></item><item><p>The <code>binding</code> element describes <emph>how</emph> to access the service. </p></item><item><p>The <code>service</code> element describes <emph>where</emph> to access the service.</p></item></ulist></p>
! <p>Section 3 introduces the WSDL2.0 infoset, schema and component model.</p>
! <p>Section 4 gives more information on defining message types.</p><p>Section 5 gives more information on interfaces.</p><p>Section 6 gives more information on bindings and services.</p>
! <p>Section 7 covers various advanced topics.</p>
</div2><div2 id="notation">
<head>Notational Conventions</head>
--- 99,113 ----
! <p>Section 2 starts with a hypothetical use case involving a hotel reservation service. It proceeds step-by-step through the development of a simple example WSDL 2.0 document that describes this service:<ulist><item><p>The <code>types</code> element describes the kinds of messages that the service will send and receive. </p></item><item><p>The <code>interface</code> element describes <emph>what</emph> abstract functionality the Web service provides. </p></item><item><p>The <code>binding</code> element describes <emph>how</emph> to access the service. </p></item><item><p>The <code>service</code> element describes <emph>where</emph> to access the service.</p></item></ulist></p>
! <p>After presenting the example, it moves on to introduce the WSDL2.0 infoset, schema, and component model. Then it provides more detailed coverage on defining message types, interfaces, bindings, and services.</p>
! <p>Section 3 explains the WSDL2.0 importing mechanisms in great details.</p>
+ <p>Section 4 talks about WSDL 2.0 extensibility and various predefined extensions. </p>
+
+ <p>Section 5 covers various topics that may fall outside the scope of WSDL 2.0, but shall provide useful background and best practice guidances that may be useful when authoring a WSDL 2.0 document or implementing the WSDL 2.0 specification.
+ </p>
+
+
</div2><div2 id="notation">
<head>Notational Conventions</head>
***************
*** 131,137 ****
<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 WSDL 2.0 features may be used. </p>
! <!-- ************************ GreatH *************************** --><div2 id="basics-greath-scenario"><head>Example Scenario: The GreatH Hotel Reservation Service</head><p>Hotel GreatH (a fictional hotel)) 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. The Web service will return a room rate (a floating point number in USD$) if such a room is available, or a zero room rate if ot. If any input data is invalid, the service should return an error. Thus, the service will accept a <code>checkAvailability</code> message and return a <code>checkAvailabilityResponse</code> or <code>invalidDataFault</code> message.</p> </item><item><p><emph>MakeReservation</emph>. To make a reservation, a client must provide a name, address, and credit card information, and the service will return a confirmation number if the reservation is successful. The service will return an error message if the credit card number or any other data field is invalid. Thus, the service will accept a <code>makeReservation</code> message and return a <code>makeReservationResponse</code> or <code>invalidCreditCardFault</code> message.</p></item></ulist> We know that we will later need to build a complete system that supports transactions and secured transmission, but initially we will implement only minimal functionality. In fact, to simplify our first example, we will implement only the <emph>CheckAvailability</emp> operation. </p><p>The next several sections proceed step-by-step through 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[
--- 136,143 ----
<head>WSDL 2.0 Basics</head>
+ <div2 id="basic-example"><head>Getting Started: The GreatH Hotel Example</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 WSDL 2.0 features may be used. </p>
! <!-- ************************ GreatH *************************** --><div3 id="basics-greath-scenario"><head>Example Scenario: The GreatH Hotel Reservation Service</head><p>Hotel GreatH (a fictional hotel)) 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. The Web service will return a room rate (a floating point number in USD$) if such a room is available, or a zero room rate if ot. If any input data is invalid, the service should return an error. Thus, the service will accept a <code>checkAvailability</code> message and return a <code>checkAvailabilityResponse</code> or <code>invalidDataFault</code> message.</p> </item><item><p><emph>MakeReservation</emph>. To make a reservation, a client must provide a name, address, and credit card information, and the service will return a confirmation number if the reservation is successful. The service will return an error message if the credit card number or any other data field is invalid. Thus, the service will accept a <code>makeReservation</code> message and return a <code>makeReservationResponse</code> or <code>invalidCreditCardFault</code> message.</p></item></ulist> We know that we will later need to build a complete system that supports transactions and secured transmission, but initially we will implement only minimal functionality. In fact, to simplify our first example, we will implement only the <emph>CheckAvailability</emp> operation. </p><p>The next several sections proceed step-by-step through 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[
***************
*** 219,223 ****
! </div2><div2 id="basics-getting-started"><head>Getting Started: Defining a WSDL 2.0 Target Namespace</head><p>Before writing our WSDL 2.0 document, we need to decide on a <emph>WSDL 2.0 target namespace</emph> URI for it. The WSDL 2.0 target namespace is analogous to an XML Schema target namespace. Interface, binding and service names that we define in our WSDL 2.0 document will be associated with the WSDL 2.0 target namespace, and thus will be distinguishable from similar names in a different WSDL 2.0 target namespace. (This will become important if using WSDL 2.0's import or interface inheritance mechanisms.) </p><p>The value of the WSDL 2.0 target namespace must be an absolute URI. Furthermore, it should be dereferenceable to a WSDL 2.0 document that describes the Web service that the WSDL 2.0 target namespace is used to describe. For example, the GreatH owners should make the WSDL 2.0 document available from this URI. (And if a WSDL 2.0 description is split into multiple documents, then the WSL 2.0 target namespace should resolve to a master document that includes all the WSDL 2.0 documents needed for that service description.) However, there is no absolute requirement for this URI to be dereferenceable, so a WSDL 2.0 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 2.0 document from anywhere -- not necessarily an authoritative source. But by dereferencing the WSDL 2.0 target namespace URI, a user should be able to obtain an authoritative version. Since GreatH will be the owner of the service, the WSDL 2.0 target namespace URI should refer to a location on the GreatH Web site or otherwise within its control.</p><p>Once we have decided on a WSDL 2.0 target namespace 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 2.0 Document</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
--- 225,231 ----
! </div3>
!
! <div3 id="basics-getting-started"><head>Defining a WSDL 2.0 Target Namespace</head><p>Before writing our WSDL 2.0 document, we need to decide on a <emph>WSDL 2.0 target namespace</emph> URI for it. The WSDL 2.0 target namespace is analogous to an XML Schema target namespace. Interface, binding and service names that we define in our WSDL 2.0 document will be associated with the WSDL 2.0 target namespace, and thus will be distinguishable from similar names in a different WSDL 2.0 target namespace. (This will become important if using WSDL 2.0's import or interface inheritance mechanisms.) </p><p>The value of the WSDL 2.0 target namespace must be an absolute URI. Furthermore, it should be dereferenceable to a WSDL 2.0 document that describes the Web service that the WSDL 2.0 target namespace is used to describe. For example, the GreatH owners should make the WSDL 2.0 document available from this URI. (And if a WSDL 2.0 description is split into multiple documents, then the WSDL 2.0 target namespace hould resolve to a master document that includes all the WSDL 2.0 documents needed for that service description.) However, there is no absolute requirement for this URI to be dereferenceable, so a WSDL 2.0 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 2.0 document from anywhere -- not necessarily an authoritative source. But by dereferencing the WSDL 2.0 target namespace URI, a user should be able to obtain an authoritative version. Since GreatH will be the owner of the service, the WSDL 2.0 target namespace URI should refer to a location on the GreatH Web site or otherwise within its control.</p><p>Once we have decided on a WSDL 2.0 target namespace 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 2.0 Document</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
***************
*** 230,234 ****
. . .
</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/2005/05/wsdl"</code></label>
<def>
<p>
--- 238,242 ----
. . .
</description>]]></eg>
! </example><div4 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/2005/05/wsdl"</code></label>
<def>
<p>
***************
*** 236,240 ****
</p>
</def>
! </gitem><gitem><label><code>targetNamespace= "http://greath.example.com/2004/wsdl/resSvc"</code></label><def><p>This defines the WSDL 2.0 target namespace 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 an XML Schema target namespace.</p></def></gitem><gitem><label><code>xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc"</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 as the value of the <att>targetNamespace</att> attribute. This will allow us later to use the <code>tns:</code> prefix in QNames, to refer to the WSDL 2.0 target namespace of the GreatH service. (For more on QNames see <bibref ref="XMLNS"/> section 3 <xspecref href="http://www.w3.org/TR/1999/REC-xml-names-19990114/#ns-qualnames">Qualified Names</xsecref>.)</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 processors are likely 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 2.0 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 <code>checkAvailability</code>, <code>checkAvailabilityResponse</code> and <code>invalidDataError</code> message types thatwe'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>
<eg><![CDATA[
--- 244,250 ----
</p>
</def>
! </gitem><gitem><label><code>targetNamespace= "http://greath.example.com/2004/wsdl/resSvc"</code></label><def><p>This defines the WSDL 2.0 target namespace 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 an XML Schema target namespace.</p></def></gitem><gitem><label><code>xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc"</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 as the value of the <att>targetNamespace</att> attribute. This will allow us later to use the <code>tns:</code> prefix in QNames, to refer to the WSDL 2.0 target namespace of the GreatH service. (For more on QNames see <bibref ref="XMLNS"/> section 3 <xspecref href="http://www.w3.org/TR/1999/REC-xml-names-19990114/#ns-qualnames">Qualified Names</xsecref>.)</p></def></gitem></glist></p><p> Now we can start describing the GreatH service. </p></div4></div3>
!
! <div3 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 processors are likely 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 2.0 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 <code>checkAvailability</code>, <code>checkAvailabilityResponse</code> and <code>invalidDataError</code> message types that we'll need. </p><p>In WSDL 2.0, all normal and fault message types must be defined as single <emph>element</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>
<eg><![CDATA[
***************
*** 272,278 ****
. . .
</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"</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 XML Schema target namespace that we define for our message types. Thus, the URI we specify must be the same as the URI that we define as the target namespace of our XML Schema types (below) -- <emph>not</emph> the target namespace of the WSDL 2.0 document itself.</p></def></gitem><gitem><label><code>targetNamespace="http://greath.example.com/2004/schemas/resSvc"</code></label><def><p>This is the XML Schema target namespace that we've created for use by the GreatH reservation service. The <code>checkAvailability</code>, <code>checkAvailabilityResponse</code> and <code>invalidDataError</code> element names will be associated with this XML Schema target namspace.</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 one 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 2.0 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 <emph>in-out</emph> pattern (see <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSD-PART2"/> section 2.2.3 <xspecref href="&w3c-designation-part2;#in-out">In-Out</xspecref>) 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). We will explain more about message exchange <emph>pattern</emph>s in <specref ref = "more-interfaces-meps"/></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="&w3c-designation-part2;#in-out">in-out</xspecref> pattern for this operation, because this is the most natural way to represent a simple request-response interaction. We could have instead (for example) defined two separate operations using the <xspecref href="&w3c-designation-part2;#in-out">in-only</xspecref> and <xspecref href="&w3c-designation-part2;#out-only">out-only</xspecref> patterns (see <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSDL-PART2"/> section 2.2.1 <xspecref href="&w3c-designation-part2;#in-only">In-Only</xspecref> and section 2.2.5 <xspecref href="&w3c-designation-part2;#out-only">Out-Only</xspecref>), but that would just complicate matters for the client, bcause 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 2.0 document.</p><example id="example-initial-interface">
--- 282,288 ----
. . .
</description>]]></eg>
! </example><div4 id="example-initial-types-explanation"><head>Explanation of Example</head><glist><gitem><label><code>xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc"</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 XML Schema target namespace that we define for our message types. Thus, the URI we specify must be the same as the URI that we define as the target namespace of our XML Schema types (below) -- <emph>not</emph> the target namespace of the WSDL 2.0 document itself.</p></def></gitem><gitem><label><code>targetNamespace="http://greath.example.com/2004/schemas/resSvc"</code></label><def><p>This is the XML Schema target namespace that we've created for use by the GreatH reservation service. The <code>checkAvailability</code>, <code>checkAvailabilityResponse</code> and <code>invalidDataError</code> element names will be associated with this XML Schema target namspace.</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></div4></div3>
! <div3 id="basics-interface"><head>Defining an Interface</head><p>WSDL 2.0 enables one 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 2.0 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 <emph>in-out</emph> pattern (see <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSD-PART2"/> section 2.2.3 <xspecref href="&w3c-designation-part2;#in-out">In-Out</xspecref>) 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). We will explain more about message exchange <emph>pattern</emph>s in <specref ref = "more-interfaces-meps"/></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="&w3c-designation-part2;#in-out">in-out</xspecref> pattern for this operation, because this is the most natural way to represent a simple request-response interaction. We could have instead (for example) defined two separate operations using the <xspecref href="&w3c-designation-part2;#in-out">in-only</xspecref> and <xspecref href="&w3c-designation-part2;#out-only">out-only</xspecref> patterns (see <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSDL-PART2"/> section 2.2.1 <xspecref href="&w3c-designation-part2;#in-only">In-Only</xspecref> and section 2.2.5 <xspecref href="&w3c-designation-part2;#out-only">Out-Only</xspecref>), but that would just complicate matters for the client, bcause 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 2.0 document.</p><example id="example-initial-interface">
***************
*** 312,316 ****
. . .
! </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 <code>description</code> element. In this example, we are declaring only one interface, but in general a WSDL 2.0 document may declare more than one interface. Thus, each interface must be given a name that is unique within the set of interfaces defined in this WSDL 2.0 target namespace. 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 be 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>
--- 322,326 ----
. . .
! </description>]]></eg></example><div4 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 <code>description</code> element. In this example, we are declaring only one interface, but in general a WSDL 2.0 document may declare more than one interface. Thus, each interface must be given a name that is unique within the set of interfaces defined in this WSDL 2.0 target namespace. 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 be 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>
***************
*** 321,328 ****
</p></def></gitem>
! <gitem><label><code>wsdlx:safe="true" ></code></label><def><p>This line indicates that this operation will not obligate the client in any way, i.e., the client can safely invoke this operation without fear that it may be incurring an obligation (such as agreeing to buy something). This is further explained in <specref ref="more-interfaces-operations"/>. </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 theory could consist of 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 <xspecref href="&w3c-designation-part2;#in-out">in-out</xspecref> patern that we've chosen to use only has one input message, it is trivial in this case: we simply fill in the message label "In" that was defined in <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSDL-PART2"/> section 2.2.3 <xspecref href="&w3c-designation-part2;#in-out">In-Out</xspecref> for the <xspecref href="&w3c-designation-part2;#in-out">in-out</xspecref> pattern. However, if a new pattern is defined that involve multiple input messages, then the different input messages in the pattern could then be distinguished by using different labels.</p></def></gitem><gitem><label><code>element="ghns:checkAvailability" /></code></label><def><p>This specifies the message type for this input message, as defined previously in the <code>types</code> section.</p></def></gitem><gitem><label><code><output messageLabel="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></abel><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 <code>messageLabel</code> 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="&w3c-designation-part2;#fault-trigger">message-triggers-fault rule</xspecref>; others use a <xspecref href="&w3c-designation-part2;#fault-replacement">fault-replaces-message</xspecref> rule. See <emph>WSDL 2.0 Pedefined Extensions</emph> <bibref ref="WSDL-PART2"/> section 2.1.2 <xspecref href="&w3c-designation-part2;#fault-trigger">Message Triggers Fault</xspecref> and section 2.1.1 <xspecref href="&w3c-designation-part2;#fault-replacement">Fault Replaces Message</xspecref>.) </p></def></gitem></glist><p>Now that we've defined the abstract interface for the GreatH service, we're ready to define a binding for it.</p></div3></div2>
! <div2 id="basics-binding"><head>Defining a Binding</head>
<p>
Although we have specified
--- 331,338 ----
</p></def></gitem>
! <gitem><label><code>wsdlx:safe="true" ></code></label><def><p>This line indicates that this operation will not obligate the client in any way, i.e., the client can safely invoke this operation without fear that it may be incurring an obligation (such as agreeing to buy something). This is further explained in <specref ref="more-interfaces-operations"/>. </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 theory could consist of 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 <xspecref href="&w3c-designation-part2;#in-out">in-out</xspecref> patern that we've chosen to use only has one input message, it is trivial in this case: we simply fill in the message label "In" that was defined in <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSDL-PART2"/> section 2.2.3 <xspecref href="&w3c-designation-part2;#in-out">In-Out</xspecref> for the <xspecref href="&w3c-designation-part2;#in-out">in-out</xspecref> pattern. However, if a new pattern is defined that involve multiple input messages, then the different input messages in the pattern could then be distinguished by using different labels.</p></def></gitem><gitem><label><code>element="ghns:checkAvailability" /></code></label><def><p>This specifies the message type for this input message, as defined previously in the <code>types</code> section.</p></def></gitem><gitem><label><code><output messageLabel="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></abel><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 <code>messageLabel</code> 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="&w3c-designation-part2;#fault-trigger">message-triggers-fault rule</xspecref>; others use a <xspecref href="&w3c-designation-part2;#fault-replacement">fault-replaces-message</xspecref> rule. See <emph>WSDL 2.0 Pedefined Extensions</emph> <bibref ref="WSDL-PART2"/> section 2.1.2 <xspecref href="&w3c-designation-part2;#fault-trigger">Message Triggers Fault</xspecref> and section 2.1.1 <xspecref href="&w3c-designation-part2;#fault-replacement">Fault Replaces Message</xspecref>.) </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></div4></div3>
! <div3 id="basics-binding"><head>Defining a Binding</head>
<p>
Although we have specified
***************
*** 411,415 ****
. . .
</description>]]></eg>
! </example><div3 id="example-initial-binding-explanation"><head>Explanation of Example</head><glist><gitem><label><code>xmlns:wsoap= "http://www.w3.org/2005/05/wsdl/soap"</code></label><def><p>We've added two more namespace declarations. This one is the namespace for the SOAP 1.2 binding extension 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 <code>description</code> eement. The <att>name</att> attribute defines a name for this binding. Each name must be unique among all bindings in this WSDL 2.0 target namespace, 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 in <specref ref="more-bindings"/>, 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 WSDL 2.0 target namespace for this WSDL 2.0 document. In this case it may seem silly to have to specify the <code>tns:</code> prefix, but in <specref ref="adv-import-and-authoring"/> we will see how WSDL 2.0's impot mechanism can be used to combine components that are defined in different WSDL 2.0 target namespaces.</p></def></gitem><gitem><label><code>type="http://www.w3.org/2005/05/wsdl/soap"</code></label><def><p>This specifies what kind 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 extension (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 is not defining a new operation; rather, it is referencing the
--- 421,425 ----
. . .
</description>]]></eg>
! </example><div4 id="example-initial-binding-explanation"><head>Explanation of Example</head><glist><gitem><label><code>xmlns:wsoap= "http://www.w3.org/2005/05/wsdl/soap"</code></label><def><p>We've added two more namespace declarations. This one is the namespace for the SOAP 1.2 binding extension 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 <code>description</code> eement. The <att>name</att> attribute defines a name for this binding. Each name must be unique among all bindings in this WSDL 2.0 target namespace, 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 in <specref ref="more-bindings"/>, 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 WSDL 2.0 target namespace for this WSDL 2.0 document. In this case it may seem silly to have to specify the <code>tns:</code> prefix, but in <specref ref="adv-import-and-authoring"/> we will see how WSDL 2.0's impot mechanism can be used to combine components that are defined in different WSDL 2.0 target namespaces.</p></def></gitem><gitem><label><code>type="http://www.w3.org/2005/05/wsdl/soap"</code></label><def><p>This specifies what kind 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 extension (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 is not defining a new operation; rather, it is referencing the
***************
*** 427,431 ****
</p>
</def></gitem><gitem><label><code>wsoap:mep="http://www.w3.org/2003/05/soap/mep/soap-response"></code></label><def><p>This attribute is also specific to WSDL 2.0's SOAP binding extension. It specifies the SOAP message exchange pattern (MEP) that will be used to implement the abstract WSDL 2.0 message exchange pattern (<xspecref href="&w3c-designation-part2;#in-out">in-out</xspecref>) that was specified when the <code>opCheckAvailability</code> operation was defined. </p>
! <p>When HTTP is used as the underlying transport protocol (as in this example) the <code>wsoap:mep</code> attribute also controls whether GET or POST will be used as the underlying HTTP method. In this case, the use of <code>wsoap:mep="http://www.w3.org/2003/05/soap/mep/soap-response"</code> causes GET to be used by default. See also <specref ref="adv-get-vs-post"/>.</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 extension. This specifies the SOAP 1.2 fault code that will cause this fault message to be sent. If desired, a list of subcodes can also be speified using the 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 <code>service</code> 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 to indicate what protocols and transmission formats are to be used at that endpoint. A service is only permitted to have one interface. (See <specref ref="adv-multiple-docs-describing-same-service"/> for further discussion of this limitation.) </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" ?>
--- 437,443 ----
</p>
</def></gitem><gitem><label><code>wsoap:mep="http://www.w3.org/2003/05/soap/mep/soap-response"></code></label><def><p>This attribute is also specific to WSDL 2.0's SOAP binding extension. It specifies the SOAP message exchange pattern (MEP) that will be used to implement the abstract WSDL 2.0 message exchange pattern (<xspecref href="&w3c-designation-part2;#in-out">in-out</xspecref>) that was specified when the <code>opCheckAvailability</code> operation was defined. </p>
! <p>When HTTP is used as the underlying transport protocol (as in this example) the <code>wsoap:mep</code> attribute also controls whether GET or POST will be used as the underlying HTTP method. In this case, the use of <code>wsoap:mep="http://www.w3.org/2003/05/soap/mep/soap-response"</code> causes GET to be used by default. See also <specref ref="adv-get-vs-post"/>.</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 extension. This specifies the SOAP 1.2 fault code that will cause this fault message to be sent. If desired, a list of subcodes can also be speified using the optional <att>wsoap:subcodes</att> attribute.</p></def></gitem></glist></div4></div3>
!
! <div3 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 <code>service</code> 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 to indicate what protocols and transmission formats are to be used at that endpoint. A service is only permitted to have one interface. (See <specref ref="adv-multiple-docs-describing-same-service"/> for further discussion of this limitation.) </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" ?>
***************
*** 463,469 ****
</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 WSDL 2.0 target namespace. The name attribute is required. It allows URIs to be created that identify components in WSDL 2.0 description. (See <emph>WSDL 2.0 Core Language</emph> <bibref ref="WSDL-PART1"/> appendix C <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-20040803/#wsdl-uri-references">URI References for WSDL 2.0 constructs</xspecref>.)</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 uniqu within this service. </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 documentation 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 messages, constraints on their use, and the sequence in which operations should be invoked.</p><p>The <code>documentation</code> element allows the WSDL 2.0 author to include some human-readable documentation inside a WSDL 2.0 document. It is also a convenient place to reference any additional external documentation that a client developer may need in order to use the service. It can appear in a number of places in a WSDL 2.0 document (see <specref ref="wsdl-infoset-diagram/>), 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" ?>
--- 475,481 ----
</description>]]></eg>
! </example><div4 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 WSDL 2.0 target namespace. The name attribute is required. It allows URIs to be created that identify components in WSDL 2.0 description. (See <emph>WSDL 2.0 Core Language</emph> <bibref ref="WSDL-PART1"/> appendix C <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-20040803/#wsdl-uri-references">URI References for WSDL 2.0 constructs</xspecref>.)</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 uniqu within this service. </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></div4></div3>
! <div3 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 documentation 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 messages, constraints on their use, and the sequence in which operations should be invoked.</p><p>The <code>documentation</code> element allows the WSDL 2.0 author to include some human-readable documentation inside a WSDL 2.0 document. It is also a convenient place to reference any additional external documentation that a client developer may need in order to use the service. It can appear in a number of places in a WSDL 2.0 document (see <specref ref="wsdl-infoset-diagram/>), 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" ?>
***************
*** 481,496 ****
</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 the service. </p></def></gitem></glist>
! <p>This completes our presentation of the GreatH example. In the following sections, we will move on to look into more details of various aspects of WSDL2.0 specification. </p></div3></div2>
! </div1>
<!-- ****************WSL2.0 Infoset, Schema and Component Model********************************* -->
<!-- ****************WSL2.0 Infoset, Schema and Component Model********************************* -->
! <div1 id="wsdl-xml-representation"><head>WSDL 2.0 Infoset, Schema and Component Model</head>
<p>In computer science theory, a language consists of a (possibly infinite) set of sentences, and each sentence is a finite string of literal symbols or characters. A language specification must therefore define the set sentences in that language, and, to be useful, it should also indicate the meaning of each sentence. Indeed, this is the purpose of the WSDL 2.0 specification.</p><p>However, instead of defining WSDL 2.0 in terms of literal symbols or characters, to avoid dependency on any particular character encoding, WSDL 2.0 is defined in terms of the <emph>XML Infoset</emph> <bibref ref="XMLInfoSet"/>. Specifically, a <emph>WSDL 2.0 document</emph> consists of a <code>description</code> element information item (in the XML Infoset) that conforms to the WSDL 2.0 specification. In other words, a sentence in the WSDL 2.0 language is a <code>description</code> element information item that obeys the additional constraints spelled out in the WSDL 2.0 specification.</p><p>Since an XML Infoset cn be created from more than one physical document, a WSDL 2.0 document does not necessarily correspond to a single <emph>physical</emph> document: the word "document" is used figuratively, for convenience. Furthermore, since WSDL 2.0 provides <code>import</code> and <code>include</code> mechanisms, a WSDL 2.0 document may reference other WSDL 2.0 documents to facilitate convenient organization or reuse. In such cases, the meaning of the including or importing document as a whole will depend (in part) on the meaning of the included or imported document.</p><p>The XML Infoset uses terms like "element information item" and "attribute information item". Unfortunately, those terms are rather lengthy to repeat often. Thus, for convenience, this primer often uses the terms "element" and "attribute" instead, as a shorthand. It should be understood, however, that since WSDL 2.0 is based on the XML Infoset, we really mean "element information item" and "attribute information item", respectively.</p>
! <div2 id="wsdl-infoset-diagram"><head>WSDL 2.0 Infoset</head>
<p>The following diagram gives an overview of the XML Infoset for a WSDL 2.0 document.
--- 493,509 ----
</example>
! <div4 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 the service. </p></def></gitem></glist>
! <p>This completes our presentation of the GreatH example. In the following sections, we will move on to look into more details of various aspects of WSDL2.0 specification. </p></div4></div3>
! </div2>
!
<!-- ****************WSL2.0 Infoset, Schema and Component Model********************************* -->
<!-- ****************WSL2.0 Infoset, Schema and Component Model********************************* -->
! <div2 id="wsdl-xml-representation"><head>WSDL 2.0 Infoset, Schema and Component Model</head>
<p>In computer science theory, a language consists of a (possibly infinite) set of sentences, and each sentence is a finite string of literal symbols or characters. A language specification must therefore define the set sentences in that language, and, to be useful, it should also indicate the meaning of each sentence. Indeed, this is the purpose of the WSDL 2.0 specification.</p><p>However, instead of defining WSDL 2.0 in terms of literal symbols or characters, to avoid dependency on any particular character encoding, WSDL 2.0 is defined in terms of the <emph>XML Infoset</emph> <bibref ref="XMLInfoSet"/>. Specifically, a <emph>WSDL 2.0 document</emph> consists of a <code>description</code> element information item (in the XML Infoset) that conforms to the WSDL 2.0 specification. In other words, a sentence in the WSDL 2.0 language is a <code>description</code> element information item that obeys the additional constraints spelled out in the WSDL 2.0 specification.</p><p>Since an XML Infoset cn be created from more than one physical document, a WSDL 2.0 document does not necessarily correspond to a single <emph>physical</emph> document: the word "document" is used figuratively, for convenience. Furthermore, since WSDL 2.0 provides <code>import</code> and <code>include</code> mechanisms, a WSDL 2.0 document may reference other WSDL 2.0 documents to facilitate convenient organization or reuse. In such cases, the meaning of the including or importing document as a whole will depend (in part) on the meaning of the included or imported document.</p><p>The XML Infoset uses terms like "element information item" and "attribute information item". Unfortunately, those terms are rather lengthy to repeat often. Thus, for convenience, this primer often uses the terms "element" and "attribute" instead, as a shorthand. It should be understood, however, that since WSDL 2.0 is based on the XML Infoset, we really mean "element information item" and "attribute information item", respectively.</p>
! <div3 id="wsdl-infoset-diagram"><head>WSDL 2.0 Infoset</head>
<p>The following diagram gives an overview of the XML Infoset for a WSDL 2.0 document.
***************
*** 499,505 ****
</p>
! </div2>
! <div2 id="wsdl-schema">
<head>WSDL 2.0 Schema</head>
--- 512,518 ----
</p>
! </div3>
! <div3 id="wsdl-schema">
<head>WSDL 2.0 Schema</head>
***************
*** 513,517 ****
</ednote>
</p>
! <div3 id="element-order"><head>WSDL2.0 Element Ordering</head>
<p>This section gives an example of how WSDL 2.0 specification constrains the WSDL 2.0 schema about the ordering of top WSDL2.0 elements.</p>
--- 526,530 ----
</ednote>
</p>
! <div4 id="element-order"><head>WSDL2.0 Element Ordering</head>
<p>This section gives an example of how WSDL 2.0 specification constrains the WSDL 2.0 schema about the ordering of top WSDL2.0 elements.</p>
***************
*** 599,606 ****
<p>Note the term "extension" is used above as a convenient way to refer to namespace-qualified extension elements. The namespace name of such extension elements must not be<attval>&wsdl-ns;</attval>.
</p>
</div3>
- </div2>
! <div2 id="component-model"><head>WSDL 2.0 Component Model</head>
<p>The WSDL 2.0 Infoset model above illustrates the required structure of a WSDL 2.0 document, using the XML Infoset. However, the WSDL 2.0 language also imposes many semantic constraints over and above structural conformance to this XML Infoset. In order to precisely describe these constraints, and as an aid in precisely defining the meaning of each WSDL 2.0 document, the WSDL 2.0 specification defines a <emph>component model</emph> as an additional layer of abstraction above the XML Infoset. Constraints and meaning are defined in terms of this component model, and the definition of each component includes a mapping that specifies how values in the component model are derived from corresponding items in the XML Infoset. The following diagram gives an overview of the WSDL 2.0 components and their containment hierarchy.
--- 612,619 ----
<p>Note the term "extension" is used above as a convenient way to refer to namespace-qualified extension elements. The namespace name of such extension elements must not be<attval>&wsdl-ns;</attval>.
</p>
+ </div4>
</div3>
! <div3 id="component-model"><head>WSDL 2.0 Component Model</head>
<p>The WSDL 2.0 Infoset model above illustrates the required structure of a WSDL 2.0 document, using the XML Infoset. However, the WSDL 2.0 language also imposes many semantic constraints over and above structural conformance to this XML Infoset. In order to precisely describe these constraints, and as an aid in precisely defining the meaning of each WSDL 2.0 document, the WSDL 2.0 specification defines a <emph>component model</emph> as an additional layer of abstraction above the XML Infoset. Constraints and meaning are defined in terms of this component model, and the definition of each component includes a mapping that specifies how values in the component model are derived from corresponding items in the XML Infoset. The following diagram gives an overview of the WSDL 2.0 components and their containment hierarchy.
***************
*** 613,617 ****
</p>
! <div3 id="import-component"><head>WSDL 2.0 Import and Include</head>
<p>
The WSDL 2.0 component model is particularly helpful in defining
--- 626,630 ----
</p>
! <div4 id="import-component"><head>WSDL 2.0 Import and Include</head>
<p>
The WSDL 2.0 component model is particularly helpful in defining
***************
*** 667,672 ****
</p>
<p>We will cover a lot more about how to use WSDL 2.0 import and include in <specref ref="adv-import-and-authoring"/></p>
! </div3>
! </div2></div1>
--- 680,686 ----
</p>
<p>We will cover a lot more about how to use WSDL 2.0 import and include in <specref ref="adv-import-and-authoring"/></p>
! </div4>
! </div3></div2>
!
***************
*** 674,678 ****
<!-- ******************MessageTypes********************************** -->
! <div1 id="more-types"><head>More on Message Types</head>
<p>The WSDL 2.0 <code>types</code> element provides a mechanism for enclosing message schemas in a WSDL 2.0 document. Because WSDL 2.0 directly supports schemas written in XML Schema
<bibref ref="XMLSchemaP1"/>, we will focus here on the use of XML Schema to define message types. Schemas written in other type definition languages must be defined using a WSDL 2.0 language extension. For examples of other schema languages, see WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> Appendix E "<xspecref href="&w3c-designation-part1;#other-schemalang">Examples of Specifications of Extension Elements for Alternative Schema Language Support. (Non-Normative)</xspecref>".
--- 688,692 ----
<!-- ******************MessageTypes********************************** -->
! <div2 id="more-types"><head>More on Message Types</head>
<p>The WSDL 2.0 <code>types</code> element provides a mechanism for enclosing message schemas in a WSDL 2.0 document. Because WSDL 2.0 directly supports schemas written in XML Schema
<bibref ref="XMLSchemaP1"/>, we will focus here on the use of XML Schema to define message types. Schemas written in other type definition languages must be defined using a WSDL 2.0 language extension. For examples of other schema languages, see WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> Appendix E "<xspecref href="&w3c-designation-part1;#other-schemalang">Examples of Specifications of Extension Elements for Alternative Schema Language Support. (Non-Normative)</xspecref>".
***************
*** 708,712 ****
</eg>
! <div2 id="more-types-schema-inline">
<head>Inlining XML Schema</head>
<p>We have already seen an example of using inlined schema definitions in section <specref ref="basics-types"/>, so we will merely add a few additional points here. </p>
--- 722,726 ----
</eg>
! <div3 id="more-types-schema-inline">
<head>Inlining XML Schema</head>
<p>We have already seen an example of using inlined schema definitions in section <specref ref="basics-types"/>, so we will merely add a few additional points here. </p>
***************
*** 722,728 ****
! </div2>
! <div2 id="more-types-schema-import">
<head>Importing XML Schema</head>
<p> There are many cases where one would prefer importing schema definitions from separate schema files instead of
--- 736,742 ----
! </div3>
! <div3 id="more-types-schema-import">
<head>Importing XML Schema</head>
<p> There are many cases where one would prefer importing schema definitions from separate schema files instead of
***************
*** 763,768 ****
</description>]]></eg>
</example>
! </div2>
! <div2
id="more-types-import-include-summary"><head>Summary of Import and Include Mechanisms</head>
<p>So far we have briefly covered both WSDL import/include and schema import/include. The following table summarizes the similarities and differences
--- 777,782 ----
</description>]]></eg>
</example>
! </div3>
! <div3
id="more-types-import-include-summary"><head>Summary of Import and Include Mechanisms</head>
<p>So far we have briefly covered both WSDL import/include and schema import/include. The following table summarizes the similarities and differences
***************
*** 821,837 ****
! </div2>
! </div1>
<!-- ******************Interface********************************** -->
<!-- ******************Interface********************************** -->
! <div1 id="more-interfaces">
<head>More on Interfaces</head>
<!-- ************************interface*************************** -->
<p>We previously mentioned that a WSDL 2.0 interface is basically a set of operations. However, there are some additional capabilities that we have not yet covered. First, let's review the syntax for the <code>interface</code> element. </p>
! <div2 id="more-interfaces-interfaces">
<head>Interface Syntax </head>
--- 835,853 ----
! </div3>
! </div2>
!
!
<!-- ******************Interface********************************** -->
<!-- ******************Interface********************************** -->
! <div2 id="more-interfaces">
<head>More on Interfaces</head>
<!-- ************************interface*************************** -->
<p>We previously mentioned that a WSDL 2.0 interface is basically a set of operations. However, there are some additional capabilities that we have not yet covered. First, let's review the syntax for the <code>interface</code> element. </p>
! <div3 id="more-interfaces-interfaces">
<head>Interface Syntax </head>
***************
*** 878,883 ****
<p>The <code>interface</code> element has two optional attributes: <att>styleDefault</att> and <att>extends</att>. The <att>styleDefault</att> attribute can be used to define a default value for the <att>style</att> attributes of all operations under this interface (see WSDL 2.0 Part 1 "<xspecref href="&w3c-designation-part1;#Interface_styleDefault_attribute">styleDefault attribute information item</xspecref>"). The <att>extends</att> attribute is for inheritance, and is explained next. </p>
! </div2>
! <div2 id="more-interfaces-inheritance">
<head>Interface Inheritance</head>
<p>
--- 894,899 ----
<p>The <code>interface</code> element has two optional attributes: <att>styleDefault</att> and <att>extends</att>. The <att>styleDefault</att> attribute can be used to define a default value for the <att>style</att> attributes of all operations under this interface (see WSDL 2.0 Part 1 "<xspecref href="&w3c-designation-part1;#Interface_styleDefault_attribute">styleDefault attribute information item</xspecref>"). The <att>extends</att> attribute is for inheritance, and is explained next. </p>
! </div3>
! <div3 id="more-interfaces-inheritance">
<head>Interface Inheritance</head>
<p>
***************
*** 972,977 ****
<p>Now let's have a look at the element children of <code>interface</code>, beginning with <code>fault</code>. </p>
! </div2>
! <div2 id="more-interfaces-faults">
<head>Interface Faults</head>
<p>The <code>fault</code> element is used to declare faults that may occur during execution of operations of an interface. They are declared directly under <code>interface</code>, and referenced from operations where they apply, in order to permit reuse across multiple operations. </p>
--- 988,993 ----
<p>Now let's have a look at the element children of <code>interface</code>, beginning with <code>fault</code>. </p>
! </div3>
! <div3 id="more-interfaces-faults">
<head>Interface Faults</head>
<p>The <code>fault</code> element is used to declare faults that may occur during execution of operations of an interface. They are declared directly under <code>interface</code>, and referenced from operations where they apply, in order to permit reuse across multiple operations. </p>
***************
*** 1012,1017 ****
! </div2>
! <div2 id="more-interfaces-operations">
<head>Interface Operations</head>
<p>As shown earlier, the <code>operation</code> element is used to indicate an operation supported by the containing interface. It associates message schemas with a message exchange pattern (MEP), in order to abstractly describe a simple interaction with a Web service. </p>
--- 1028,1033 ----
! </div3>
! <div3 id="more-interfaces-operations">
<head>Interface Operations</head>
<p>As shown earlier, the <code>operation</code> element is used to indicate an operation supported by the containing interface. It associates message schemas with a message exchange pattern (MEP), in order to abstractly describe a simple interaction with a Web service. </p>
***************
*** 1019,1023 ****
! <div3 id="more-interfaces-op-attr"><head>Operation Attributes</head><p>An <code>operation</code> has two required attributes and one optional attribute:</p>
<ulist>
<item>
--- 1035,1039 ----
! <div4 id="more-interfaces-op-attr"><head>Operation Attributes</head><p>An <code>operation</code> has two required attributes and one optional attribute:</p>
<ulist>
<item>
***************
*** 1045,1050 ****
<p>Note that <bibref ref="WSDL-PART2"/> provides a predefined extension for indicating operation safety. The <att>wsdlx:safe</att> global attribute whose value is a boolean can be used with an operation to indicate whether the operation is asserted to be "safe" (as defined in Section 3.5 of the Web Architecture <bibref ref="webarch"/>) for clients to invoke. In essence, a safe operation is any operation that does not give the client any new obligations. For example, an operation that permits the client to check prices on products typically would not obligate the client to buy those products, and thus would be safe, whereas an operation for purchasing products would obligate the client to pay for the products that were ordered, and thus would not be safe. </p><p>An operation should be marked safe (by using the <att>wsdlx:safe</att> and by setting its value to "true") if it meets the criteria for a safe interaction defined in Section 3.5 of the Web Architecture <bibref ref="webarch"/>, because tis permits the infrastructure to perform efficiency optimizations, such as pre-fetch, re-fetch and caching. </p><p>The default value of this attribute is false. If it is false or is not set, then no assertion is made about the safety of the operation; thus the operation may or may not be safe.</p>
! </div3><div3><head>Operation Message References</head><p>An <code>operation</code> will also have <code>input</code>, <code>output</code>,<code>infault</code>, and/or <code>outfault</code> element children that specify the ordinary and fault message types to be used by that operation. The MEP specified by the <code>pattern</code> attribute determines which of these elements should be included, since each MEP has placeholders for the message types involved in its pattern. </p><p>Since operations were already discussed in <specref ref="basics-interface"/>, this section will merely comment on additional capabilities that were not previously explained.</p>
! <div4>
<head>The messageLabel Attribute</head>
<p>
--- 1061,1066 ----
<p>Note that <bibref ref="WSDL-PART2"/> provides a predefined extension for indicating operation safety. The <att>wsdlx:safe</att> global attribute whose value is a boolean can be used with an operation to indicate whether the operation is asserted to be "safe" (as defined in Section 3.5 of the Web Architecture <bibref ref="webarch"/>) for clients to invoke. In essence, a safe operation is any operation that does not give the client any new obligations. For example, an operation that permits the client to check prices on products typically would not obligate the client to buy those products, and thus would be safe, whereas an operation for purchasing products would obligate the client to pay for the products that were ordered, and thus would not be safe. </p><p>An operation should be marked safe (by using the <att>wsdlx:safe</att> and by setting its value to "true") if it meets the criteria for a safe interaction defined in Section 3.5 of the Web Architecture <bibref ref="webarch"/>, because tis permits the infrastructure to perform efficiency optimizations, such as pre-fetch, re-fetch and caching. </p><p>The default value of this attribute is false. If it is false or is not set, then no assertion is made about the safety of the operation; thus the operation may or may not be safe.</p>
! </div4><div4><head>Operation Message References</head><p>An <code>operation</code> will also have <code>input</code>, <code>output</code>,<code>infault</code>, and/or <code>outfault</code> element children that specify the ordinary and fault message types to be used by that operation. The MEP specified by the <code>pattern</code> attribute determines which of these elements should be included, since each MEP has placeholders for the message types involved in its pattern. </p><p>Since operations were already discussed in <specref ref="basics-interface"/>, this section will merely comment on additional capabilities that were not previously explained.</p>
! <div5>
<head>The messageLabel Attribute</head>
<p>
***************
*** 1064,1069 ****
direction.
</p>
! </div4>
! <div4>
<head>The element Attribute</head>
<p>
--- 1080,1085 ----
direction.
</p>
! </div5>
! <div5>
<head>The element Attribute</head>
<p>
***************
*** 1125,1133 ****
</p>
! </div4>
! <div4><head>Multiple infault or outfault Elements</head><p>When <code>infault</code> and/or <code>outfault</code> occur multiple times within an <code>operation</code>, they define alternative fault messages. </p></div4></div3>
<!-- ************************MEPs*************************** -->
! <div3 id="more-interfaces-meps">
<head>Understanding Message Exchange Patterns (MEPs)</head>
<p>WSDL 2.0 message exchange patterns (MEPs) are used to define 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 is defined, which includes specifying which MEP to use for that operation. 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>
--- 1141,1149 ----
</p>
! </div5>
! <div5><head>Multiple infault or outfault Elements</head><p>When <code>infault</code> and/or <code>outfault</code> occur multiple times within an <code>operation</code>, they define alternative fault messages. </p></div5></div4>
<!-- ************************MEPs*************************** -->
! <div4 id="more-interfaces-meps">
<head>Understanding Message Exchange Patterns (MEPs)</head>
<p>WSDL 2.0 message exchange patterns (MEPs) are used to define 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 is defined, which includes specifying which MEP to use for that operation. 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>
***************
*** 1164,1173 ****
<p>Although the eight MEPs defined in WSDL 2.0 Part 2 <bibref ref="WSDL-PART2"/> are intended to cover most use cases, WSDL 2.0 has designed this set to be extensible. This is why MEPs are identified by URIs rather than a fixed set of tokens.</p>
! <p>For more about defining new MEPs, see <specref ref="adv-MEP"/>. </p></div3></div2>
! </div1>
<!-- **********************************Binding************************** -->
<!-- **********************************Binding************************** -->
! <div1 id="more-bindings">
<head>More on Bindings</head>
--- 1180,1191 ----
<p>Although the eight MEPs defined in WSDL 2.0 Part 2 <bibref ref="WSDL-PART2"/> are intended to cover most use cases, WSDL 2.0 has designed this set to be extensible. This is why MEPs are identified by URIs rather than a fixed set of tokens.</p>
! <p>For more about defining new MEPs, see <specref ref="adv-MEP"/>. </p></div4></div3>
! </div2>
!
!
<!-- **********************************Binding************************** -->
<!-- **********************************Binding************************** -->
! <div2 id="more-bindings">
<head>More on Bindings</head>
***************
*** 1175,1179 ****
<bibref ref="WSDL-PART2"/>.</p>
! <div2 id="more-bindings-wsdl">
<head>Syntax Summary for Bindings</head>
<p>Since bindings are specified using extensions to the WSDL 2.0 language (i.e., binding extensions are not in the WSDL 2.0 namespace), the XML for expressing a binding will consist of a mixture of elements and attributes from WSDL 2.0 namespace and from the binding extension's namespace, using WSDL 2.0's open content model. </p><p>Here is a syntax summary for <code>binding</code>, simplified by omitting optional <code>documentation</code>, <code>feature</code> and <code>property</code> elements. Bear in mind that this syntax summary only shows the elements and attributes defined within the WSDL 2.0 namespace. When an actual binding is defined, elements and attributes from the namespace of the desired binding extension will also be intermingled as required by that particular binding extension.</p>
--- 1193,1197 ----
<bibref ref="WSDL-PART2"/>.</p>
! <div3 id="more-bindings-wsdl">
<head>Syntax Summary for Bindings</head>
<p>Since bindings are specified using extensions to the WSDL 2.0 language (i.e., binding extensions are not in the WSDL 2.0 namespace), the XML for expressing a binding will consist of a mixture of elements and attributes from WSDL 2.0 namespace and from the binding extension's namespace, using WSDL 2.0's open content model. </p><p>Here is a syntax summary for <code>binding</code>, simplified by omitting optional <code>documentation</code>, <code>feature</code> and <code>property</code> elements. Bear in mind that this syntax summary only shows the elements and attributes defined within the WSDL 2.0 namespace. When an actual binding is defined, elements and attributes from the namespace of the desired binding extension will also be intermingled as required by that particular binding extension.</p>
***************
*** 1200,1207 ****
<p>The <code>binding</code> syntax parallels the syntax of <code>interface</code>: each interface construct has a binding counterpart. Despite this syntactic similarity, they are indeed different constructs, since they are in different symbol spaces and are designed for different purposes. </p>
! </div2>
! <div2 id="more-bindings-reusable"><head>Reusable Bindings</head><p>A binding can either be reusable (applicable to any
interface) or non-reusable (specified for a particular interface). Non-reusable bindings may be specified at the granularity of the interface (assuming the binding extension provides suitable defaulting rules), or on a per-operation basis if needed. A non-reusable binding was demonstrated in <specref ref="basics-binding"/>.</p><p>To define a reusable binding, the <code>binding</code> element simply omits the <code>interface</code> attribute and omits specifying any
! operation-specific and fault-specific binding details. Endpoints can later refer to a reusable binding in the same manner as for a non-reusable binding. Thus, a reusable binding becomes associated with a particular interface when it is referenced from an endpoint, because an endpoint is part of a service, and the service specifies a particular interface that it implements. Since a reusable binding does not specify an interface, reusable bindings cannot specify operation-specific details. Therefore, reusable bindings can only be defined using binding extensions that have suitable defaulting rules, such that the binding information only needs to be explicitly supplied at the interface level.</p></div2><div2 id="more-bindings-faults">
<head>Binding Faults</head>
<p>A binding <code>fault</code> associates a concrete message format with an abstract fault
--- 1218,1227 ----
<p>The <code>binding</code> syntax parallels the syntax of <code>interface</code>: each interface construct has a binding counterpart. Despite this syntactic similarity, they are indeed different constructs, since they are in different symbol spaces and are designed for different purposes. </p>
! </div3>
! <div3 id="more-bindings-reusable"><head>Reusable Bindings</head><p>A binding can either be reusable (applicable to any
interface) or non-reusable (specified for a particular interface). Non-reusable bindings may be specified at the granularity of the interface (assuming the binding extension provides suitable defaulting rules), or on a per-operation basis if needed. A non-reusable binding was demonstrated in <specref ref="basics-binding"/>.</p><p>To define a reusable binding, the <code>binding</code> element simply omits the <code>interface</code> attribute and omits specifying any
! operation-specific and fault-specific binding details. Endpoints can later refer to a reusable binding in the same manner as for a non-reusable binding. Thus, a reusable binding becomes associated with a particular interface when it is referenced from an endpoint, because an endpoint is part of a service, and the service specifies a particular interface that it implements. Since a reusable binding does not specify an interface, reusable bindings cannot specify operation-specific details. Therefore, reusable bindings can only be defined using binding extensions that have suitable defaulting rules, such that the binding information only needs to be explicitly supplied at the interface level.</p></div3>
!
! <div3 id="more-bindings-faults">
<head>Binding Faults</head>
<p>A binding <code>fault</code> associates a concrete message format with an abstract fault
***************
*** 1212,1217 ****
<att>fault</att>. It identifies the abstract interface <code>fault</code> for which binding information is being specified. Be aware that the value of <att>ref</att> attribute of all the <code>faults</code> under a <code>binding</code>
must be unique. That is, one cannot define multiple bindings for the same interface fault within a given <code>binding</code>.</p>
! </div2>
! <div2 id="bindingOperations">
<head id="more-bindings-operations">Binding Operations</head>
<p>A binding <code>operation</code> describes a concrete binding of an interface
--- 1232,1237 ----
<att>fault</att>. It identifies the abstract interface <code>fault</code> for which binding information is being specified. Be aware that the value of <att>ref</att> attribute of all the <code>faults</code> under a <code>binding</code>
must be unique. That is, one cannot define multiple bindings for the same interface fault within a given <code>binding</code>.</p>
! </div3>
! <div3 id="bindingOperations">
<head id="more-bindings-operations">Binding Operations</head>
<p>A binding <code>operation</code> describes a concrete binding of an interface
***************
*** 1219,1230 ****
operation is uniquely identified by the WSDL 2.0 target namespace of the
interface and the name of the operation within that interface, via the required <att>ref</att> attribute of binding <code>operation</code>. As with faults, for each <code>operation</code> within a <code>binding</code>, the value of the <att>ref</att> attribute must be unique.</p>
!
! </div2>
!
!
!
!
! <div2 id="more-bindings-soap">
<head>The SOAP Binding Extension</head>
--- 1239,1245 ----
operation is uniquely identified by the WSDL 2.0 target namespace of the
interface and the name of the operation within that interface, via the required <att>ref</att> attribute of binding <code>operation</code>. As with faults, for each <code>operation</code> within a <code>binding</code>, the value of the <att>ref</att> attribute must be unique.</p>
! </div3>
! <div3 id="more-bindings-soap">
<head>The SOAP Binding Extension</head>
***************
*** 1298,1302 ****
! <div3 id="more-bindings-soap-example-explanation"><head>Explanation of Example</head><p>Most lines in this example is the same as previously explained in <specref ref="basics-binding"/>, so we'll only point out lines that are demonstrating something new for SOAP 1.1 binding.<glist><gitem><label><code><description ... xmlns:soap11="http://schemas.xmlsoap.org/soap/envelope/"></code></label><def><p>This is the namespace for terms defined within the SOAP 1.1 specification <bibref ref="SOAP11"/>.</p></def></gitem><gitem><label><code><binding...wsoap:version="1.1"</code></label><def><p>This line indicates that this binding uses SOAP 1.1, rather than SOAP 1.2.</p></def></gitem><gitem><label><code>wsoap:protocol="http://www.w3.org/2005/05/soap11/bindings/HTTP"></code></label><def><p>This line specifies that HTTP should be used as the underlying transmission protocol. See also <specref ref="adv-get-vs-post"/>.</p></def></gitem>
<gitem><label><code><operation ref="tns:opCheckAvailability"/></code></label><def><p>Note that <code>wsoap:mep</code> is not appliable to SOAP 1.1 binding. </p></def></gitem>
--- 1313,1317 ----
! <div4 id="more-bindings-soap-example-explanation"><head>Explanation of Example</head><p>Most lines in this example is the same as previously explained in <specref ref="basics-binding"/>, so we'll only point out lines that are demonstrating something new for SOAP 1.1 binding.<glist><gitem><label><code><description ... xmlns:soap11="http://schemas.xmlsoap.org/soap/envelope/"></code></label><def><p>This is the namespace for terms defined within the SOAP 1.1 specification <bibref ref="SOAP11"/>.</p></def></gitem><gitem><label><code><binding...wsoap:version="1.1"</code></label><def><p>This line indicates that this binding uses SOAP 1.1, rather than SOAP 1.2.</p></def></gitem><gitem><label><code>wsoap:protocol="http://www.w3.org/2005/05/soap11/bindings/HTTP"></code></label><def><p>This line specifies that HTTP should be used as the underlying transmission protocol. See also <specref ref="adv-get-vs-post"/>.</p></def></gitem>
<gitem><label><code><operation ref="tns:opCheckAvailability"/></code></label><def><p>Note that <code>wsoap:mep</code> is not appliable to SOAP 1.1 binding. </p></def></gitem>
***************
*** 1304,1309 ****
</glist></p>
! </div3></div2>
! <div2 id="more-bindings-http">
<head>The HTTP Binding Extension</head>
<p>In addition to the WSDL 2.0 SOAP binding extension described above, WSDL 2.0 Part 2 <bibref ref="WSDL-PART2"/> defines a binding extension for HTTP 1.1 <bibref ref="RFC2616"/> and HTTPS <bibref ref="RFC2818"/>, so that these protocols can be used natively to send and receive messages, without first encoding them in SOAP.</p><p>The HTTP binding extension provides many features to control:<ulist><item><p> Which HTTP operation will be used. (GET, PUT, POST, DELETE, and other HTTP operations are supported.)</p></item><item><p>Input, output and fault serialization</p></item><item><p>Transfer codings</p></item><item><p>Authentication requirements</p></item><item><p>Cookies</p></item><item><p>HTTP over TLS (https)</p></item></ulist></p><p>As with the WSDL 2.0 SOAP binding extension, the HTTP binding extension also provides defaulting rules to permit binding information to be specified at the interface level and used by default for each operation in the affected interface, however, defaulting rules are nt provided for binding faults.</p><p>Here is an example of using the HTTP binding extension to check hotel room
--- 1319,1325 ----
</glist></p>
! </div4></div3>
!
! <div3 id="more-bindings-http">
<head>The HTTP Binding Extension</head>
<p>In addition to the WSDL 2.0 SOAP binding extension described above, WSDL 2.0 Part 2 <bibref ref="WSDL-PART2"/> defines a binding extension for HTTP 1.1 <bibref ref="RFC2616"/> and HTTPS <bibref ref="RFC2818"/>, so that these protocols can be used natively to send and receive messages, without first encoding them in SOAP.</p><p>The HTTP binding extension provides many features to control:<ulist><item><p> Which HTTP operation will be used. (GET, PUT, POST, DELETE, and other HTTP operations are supported.)</p></item><item><p>Input, output and fault serialization</p></item><item><p>Transfer codings</p></item><item><p>Authentication requirements</p></item><item><p>Cookies</p></item><item><p>HTTP over TLS (https)</p></item></ulist></p><p>As with the WSDL 2.0 SOAP binding extension, the HTTP binding extension also provides defaulting rules to permit binding information to be specified at the interface level and used by default for each operation in the affected interface, however, defaulting rules are nt provided for binding faults.</p><p>Here is an example of using the HTTP binding extension to check hotel room
***************
*** 1338,1342 ****
</description>]]></eg>
</example>
! <div3><head>Explanation of
Example</head><ednote><name>dbooth</name><date>2005-04-15</date><edtext>ToDo: Check this section. I'm not sure I got it all right, particularly regarding whttp:location. Is the first sample request URI correct? Shouldn't instance data for tCheckAvailability be in the path component? What happens if a non-leaf element type is specified, such as tCheckAvailability?</edtext></ednote>
--- 1354,1358 ----
</description>]]></eg>
</example>
! <div4><head>Explanation of
Example</head><ednote><name>dbooth</name><date>2005-04-15</date><edtext>ToDo: Check this section. I'm not sure I got it all right, particularly regarding whttp:location. Is the first sample request URI correct? Shouldn't instance data for tCheckAvailability be in the path component? What happens if a non-leaf element type is specified, such as tCheckAvailability?</edtext></ednote>
***************
*** 1372,1377 ****
</example><p>
! This would instead serialize to a request URI such as: <code>http://greath.example.com/2004/bycheckInDate/5-5-5</code>. The rest of the message content would go to the HTTP message body.</p></div3></div2>
! <div2 id="adv-get-vs-post"><head>HTTP GET Versus POST: Which to Use?</head>
<p> When a binding using HTTP is specified for an operation, the WSDL 2.0 author must decide which HTTP method is appropriate to use -- usually a choice between GET and POST. In the context of the Web as a whole (rather than specifically Web services), the W3C Technical Architecture Group (TAG) has addressed the question of when it is appropriate to use GET, versus when to use POST, in a finding entitled <emph>URIs, Addressability, and the use of HTTP GET and POST</emph> (<bibref ref="TAG-whenToUseGET"/>). From the abstract:</p><p><quote><emph>. . . designers should adopt [GET] for safe operations such as simple queries. POST is appropriate for other types of applications where a user request has the potential to change the state of the resource (or of related resources). The finding explains how to choose between HTTP GET and POST for an application taking into account architectural, security, and practical considerations.</emph></quote></p><p>Recall that the concept of a safe operation was disussed in <specref ref="more-interfaces-op-attr"/>. (Briefly, a safe operation is one that does not cause the invoker to incur new obligations.) Although the <code>wsdlx:safe</code> attribute of an interface operation indicates that the abstract operation is safe, it does not automatically cause GET to be used at the HTTP level when the binding is specified. The choice of GET or POST is determined at the binding level: </p>
--- 1388,1393 ----
</example><p>
! This would instead serialize to a request URI such as: <code>http://greath.example.com/2004/bycheckInDate/5-5-5</code>. The rest of the message content would go to the HTTP message body.</p></div4></div3>
! <div3 id="adv-get-vs-post"><head>HTTP GET Versus POST: Which to Use?</head>
<p> When a binding using HTTP is specified for an operation, the WSDL 2.0 author must decide which HTTP method is appropriate to use -- usually a choice between GET and POST. In the context of the Web as a whole (rather than specifically Web services), the W3C Technical Architecture Group (TAG) has addressed the question of when it is appropriate to use GET, versus when to use POST, in a finding entitled <emph>URIs, Addressability, and the use of HTTP GET and POST</emph> (<bibref ref="TAG-whenToUseGET"/>). From the abstract:</p><p><quote><emph>. . . designers should adopt [GET] for safe operations such as simple queries. POST is appropriate for other types of applications where a user request has the potential to change the state of the resource (or of related resources). The finding explains how to choose between HTTP GET and POST for an application taking into account architectural, security, and practical considerations.</emph></quote></p><p>Recall that the concept of a safe operation was disussed in <specref ref="more-interfaces-op-attr"/>. (Briefly, a safe operation is one that does not cause the invoker to incur new obligations.) Although the <code>wsdlx:safe</code> attribute of an interface operation indicates that the abstract operation is safe, it does not automatically cause GET to be used at the HTTP level when the binding is specified. The choice of GET or POST is determined at the binding level: </p>
***************
*** 1407,1413 ****
! </div2></div1>
!
--- 1423,1429 ----
! </div3></div2>
! </div1>
***************
*** 1415,1426 ****
<!-- **********************************AdvancedTopics***************** -->
<div1 id="advanced-topic_ii">
! <head>Advanced Topics</head>
<div2 id="adv-import-and-authoring">
<head>Importing WSDL</head>
-
-
-
-
<p>
In some circumstances WSDL authors may want to split up a Web service description into two or more documents.
--- 1431,1438 ----
<!-- **********************************AdvancedTopics***************** -->
<div1 id="advanced-topic_ii">
! <head>Advanced Topics I: Importing Mechanisms</head>
<div2 id="adv-import-and-authoring">
<head>Importing WSDL</head>
<p>
In some circumstances WSDL authors may want to split up a Web service description into two or more documents.
***************
*** 2000,2003 ****
--- 2012,2020 ----
</description>]]></eg></example></div4></div3></div2>
+ </div1>
+
+ <div1 id="advanced-topic_iii">
+ <head>Advanced Topics II: Extensibility and Predefined Extensions</head>
+
<div2 id="adv-extensibility">
<head>Extensibility</head>
***************
*** 2484,2490 ****
</p>
! </div2>
<div2 id="adv-versioning">
<head>Web Service Versioning</head>
--- 2501,2594 ----
</p>
! </div2>
! </div1>
!
! <div1 id="advanced-topic_iv">
! <head>Advanced Topics III: Miscellaneous</head>
!
! <p>This section covers various topics that may fall outside the scope of WSDL 2.0, but shall provide useful background and best practice guidances that may be useful when authoring a WSDL 2.0 document or
! implementing the WSDL 2.0 specification.</p>
!
! <div2 id="adv-message-dispatch">
! <head>Enabling Easy Message Dispatch</head>
!
! <p>It is desirable for a message recipient to have the capability to uniquely identify a message in order to handle it correctly. The capability of identifying a message is typically used for dispatching purposes within an implementation of a web service. Therefore, WSDL authors are recommended to take disambiguating of messages that are defined in a description into consideration when they develop descriptions of their services. </p>
!
! <p>The context that a Web service may be deployed plays an important role in choosing an appropriate way to disambiguate and identify messages. In a typical deployment, an endpoint address may host a single service that is described by a WSDL service element. In this case, when XSD is used, assigning unique qualified names of global element declarations as inputs within the interface that describes the service would be sufficient to disambiguate the messages that are received. However, when endpoint address hosts multiple services, in essence supports several WSDL descriptions, the desire to disambiguate messages should considered within the context of all the deployed services, not only within a single interface. </p>
!
! <p>As explained in <specref ref= "more-interfaces-op-attr"/>, when XSD is used as the type system, a few special tokens can be used for the <code>element</code> attributes. Uniquely identifying a message may become very difficult when:
!
! <ulist>
! <item>
! <p>
! any of these input elements within an interface has a value
! of “#any”; or
! </p>
! </item>
! <item>
! <p>
! more than one of these input elements (see below) has a
! value of “#none”; or
! </p>
! </item>
! <item>
! <p>
! the qualified names of the global element declarations that
! are specified as input elements are NOT unique when
! considered together.
! </p>
! </item>
! </ulist>
! </p>
!
! <p>
! If any of the three cases above arise, then one of
! the following two alternatives can be used within
! the context of a single WSDL service by WSDL
! authors:
! </p>
! <ulist>
! <item>
! <p>
! <emph>Feature.</emph>
! The service or the interface element
! contains a Feature element declaration,
! having a required attribute with a value of
! true. The feature unambiguously identifies
! the mechanism that a message sender is
! required to support in order to enable the
! message recipient to unambiguously determine
! the message received.
! </p>
! </item>
! <item>
! <p>
! <emph>Extension.</emph>
! The interface element contains an extension
! element (i.e., an element that is not in the
! http://www.w3.org/2005/05/wsdl namespace),
! having a wsdl:required attribute with a
! value of "true". The extension element
! unambiguously identifies the mechanism that
! a message sender is required to support in
! order to enable the message recipient to
! unambiguously determine the message
! received.
! </p>
! </item>
! </ulist>
!
! <p>In addition, WS-Addressing [WS-Addressing] specification already provides a disambiguation mechanism. It defines a required [action] property whose value is always present in a message delivery. The value of the action property can be used to disambiguate the message by the receiver and there is a well defined way to associate actions to messages in WS-Addressing specifications. Further, WS-Addressing also provides an appropriate default action value that identifies each message uniquely. </p>
!
! <!-- old text for this section, replaced by contribution from Umit
! <p>Suppose a WSDL 2.0 document has two input-output operations 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 2.0 toolkits that are looking only at the message schema, rather than the actual messages. (For example, the toolkit may be operating at design time, without access to the runtime messages.) This is the problem of <emph>dispatch</emph>. How can a WSDL 2.0 document be written to ensure easy message dispatch? Strategies include:</p>
! <ulist><item><p><b>Use unique top-level elements</b>. As a best practice, ensure that the top-level elements declared in the message schemas 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></item>
+ <item><p><b>Include a required extension</b> that enables a particular dispatching convention. This approach makes the dispatching convention explicit, although it may not be supported by every WSDL 2.0 toolkit. However, as explained in <specref ref="adv-optional-versus-required"/>, toolkits that do not natively support the extension could seek manual input, thus permitting a client developer to supply an appropriate module that implements the necessary extension. This strategy has thus permits future WSDL 2.0 toolkits to support and process the extension automatically, while also ensuring that the extension will be handled properly by toolkits that are not yet able to process it automatically.</p></item></ulist>
+ <p>To ensure that client and service implementations can easily determine the interface operation under which a received message was sent (even though not every client or service may need to make such a determination), it is considered good practice to follow one of the above strategies when authoring WSDL 2.0 documents.</p>
+ -->
+ </div2>
+
<div2 id="adv-versioning">
<head>Web Service Versioning</head>
***************
*** 2782,2865 ****
- <div2 id="adv-message-dispatch">
- <head>Enabling Easy Message Dispatch</head>
-
- <p>It is desirable for a message recipient to have the capability to uniquely identify a message in order to handle it correctly. The capability of identifying a message is typically used for dispatching purposes within an implementation of a web service. Therefore, WSDL authors are recommended to take disambiguating of messages that are defined in a description into consideration when they develop descriptions of their services. </p>
-
- <p>The context that a Web service may be deployed plays an important role in choosing an appropriate way to disambiguate and identify messages. In a typical deployment, an endpoint address may host a single service that is described by a WSDL service element. In this case, when XSD is used, assigning unique qualified names of global element declarations as inputs within the interface that describes the service would be sufficient to disambiguate the messages that are received. However, when endpoint address hosts multiple services, in essence supports several WSDL descriptions, the desire to disambiguate messages should considered within the context of all the deployed services, not only within a single interface. </p>
-
- <p>As explained in <specref ref= "more-interfaces-op-attr"/>, when XSD is used as the type system, a few special tokens can be used for the <code>element</code> attributes. Uniquely identifying a message may become very difficult when:
-
- <ulist>
- <item>
- <p>
- any of these input elements within an interface has a value
- of “#any”; or
- </p>
- </item>
- <item>
- <p>
- more than one of these input elements (see below) has a
- value of “#none”; or
- </p>
- </item>
- <item>
- <p>
- the qualified names of the global element declarations that
- are specified as input elements are NOT unique when
- considered together.
- </p>
- </item>
- </ulist>
- </p>
-
- <p>
- If any of the three cases above arise, then one of
- the following two alternatives can be used within
- the context of a single WSDL service by WSDL
- authors:
- </p>
- <ulist>
- <item>
- <p>
- <emph>Feature.</emph>
- The service or the interface element
- contains a Feature element declaration,
- having a required attribute with a value of
- true. The feature unambiguously identifies
- the mechanism that a message sender is
- required to support in order to enable the
- message recipient to unambiguously determine
- the message received.
- </p>
- </item>
- <item>
- <p>
- <emph>Extension.</emph>
- The interface element contains an extension
- element (i.e., an element that is not in the
- http://www.w3.org/2005/05/wsdl namespace),
- having a wsdl:required attribute with a
- value of "true". The extension element
- unambiguously identifies the mechanism that
- a message sender is required to support in
- order to enable the message recipient to
- unambiguously determine the message
- received.
- </p>
- </item>
- </ulist>
-
- <p>In addition, WS-Addressing [WS-Addressing] specification already provides a disambiguation mechanism. It defines a required [action] property whose value is always present in a message delivery. The value of the action property can be used to disambiguate the message by the receiver and there is a well defined way to associate actions to messages in WS-Addressing specifications. Further, WS-Addressing also provides an appropriate default action value that identifies each message uniquely. </p>
-
- <!-- old text for this section, replaced by contribution from Umit
- <p>Suppose a WSDL 2.0 document has two input-output operations 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 2.0 toolkits that are looking only at the message schema, rather than the actual messages. (For example, the toolkit may be operating at design time, without access to the runtime messages.) This is the problem of <emph>dispatch</emph>. How can a WSDL 2.0 document be written to ensure easy message dispatch? Strategies include:</p>
- <ulist><item><p><b>Use unique top-level elements</b>. As a best practice, ensure that the top-level elements declared in the message schemas 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></item>
-
- <item><p><b>Include a required extension</b> that enables a particular dispatching convention. This approach makes the dispatching convention explicit, although it may not be supported by every WSDL 2.0 toolkit. However, as explained in <specref ref="adv-optional-versus-required"/>, toolkits that do not natively support the extension could seek manual input, thus permitting a client developer to supply an appropriate module that implements the necessary extension. This strategy has thus permits future WSDL 2.0 toolkits to support and process the extension automatically, while also ensuring that the extension will be handled properly by toolkits that are not yet able to process it automatically.</p></item></ulist>
- <p>To ensure that client and service implementations can easily determine the interface operation under which a received message was sent (even though not every client or service may need to make such a determination), it is considered good practice to follow one of the above strategies when authoring WSDL 2.0 documents.</p>
- -->
-
- </div2>
<div2 id="adv-service-references">
<head>Describing Web Service Messages That Refer to Other Web Services</head>
--- 2886,2889 ----
***************
*** 3616,3621 ****
RDF statements using appropriate properties, such as <code>operation</code>
and <code>operationStyle</code>.</p></item></olist></div3></div2>
! <!-- **********************************NotesOnURIs***************** --><div2 id="adv-notes-on-uris"><head>Notes on URIs</head><p>This section provides background that may be useful when authoring a WSDL 2.0 document or
! implementing the WSDL 2.0 specification.</p><div3 id="adv-namespaces-and-schema-locations"><head>XML Namespaces and Schema Locations</head><p>It is a common misperception to equate either the target namespace of an XML Schema or the value of the
<att>xmlns</att> attribute in XML instances with the location
of the corresponding schema. Even though namespaces are URIs, and URIs may be locations, and it may be possible to
--- 3640,3648 ----
RDF statements using appropriate properties, such as <code>operation</code>
and <code>operationStyle</code>.</p></item></olist></div3></div2>
!
! <!-- **********************************NotesOnURIs***************** -->
! <div2 id="adv-notes-on-uris"><head>Notes on URIs</head>
!
! <div3 id="adv-namespaces-and-schema-locations"><head>XML Namespaces and Schema Locations</head><p>It is a common misperception to equate either the target namespace of an XML Schema or the value of the
<att>xmlns</att> attribute in XML instances with the location
of the corresponding schema. Even though namespaces are URIs, and URIs may be locations, and it may be possible to
Index: wsdl20-primer.html
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.html,v
retrieving revision 1.79
retrieving revision 1.80
diff -C2 -d -r1.79 -r1.80
*** wsdl20-primer.html 24 Jun 2005 22:13:54 -0000 1.79
--- wsdl20-primer.html 24 Jun 2005 23:33:59 -0000 1.80
***************
*** 95,102 ****
no official standing.</strong></p><p></p></div>
<hr><div class="toc">
! <h2><a name="shortcontents">Short Table of Contents</a></h2><p class="toc">1. <a href="#Introduction">Introduction</a><br>2. <a href="#basics">WSDL 2.0 Basics</a><br>3. <a href="#wsdl-xml-representation">WSDL 2.0 Infoset, Schema and Component Model</a><br>4. <a href="#more-types">More on Message Types</a><br>5. <a href="#more-interfaces">More on Interfaces</a><br>6. <a href="#more-bindings">More on Bindings</a><br>7. <a href="#advanced-topic_ii">Advanced Topics</a><br>8. <a href="#References">References</a><br>A. <a href="#acknowledgments">Acknowledgements</a> (Non-Normative)<br></p></div><hr><div class="toc">
! <h2><a name="contents">Table of Contents</a></h2><p class="toc">1. <a href="#Introduction">Introduction</a><br> 1.1 <a href="#Prerequisites">Prerequisites</a><br> 1.2 <a href="#PrimerStructure">Structure of this Primer</a><br> 1.3 <a href="#notation">Notational Conventions</a><br>2. <a href="#basics">WSDL 2.0 Basics</a><br> 2.1 <a href="#basics-greath-scenario">Example Scenario: The GreatH Hotel Reservation Service</a><br> 2.2 <a href="#basics-getting-started">Getting Started: Defining a WSDL 2.0 Target Namespace</a><br> 2.2.1 <a href="#example-empty-shell-explanation">Explanation of Example</a><br> 2.3 <a href="#basics-types">Defining Message Types</a><br> 2.3.1 <a href="#example-initial-types-explanation">Explanation of Example</a><br> 2.4 <a href="#bascs-interface">Defining an Interface</a><br> 2.4.1 <a href="#example-initial-interface-explanation">Explanation of Example</a><br> 2.5 <a href="#basics-binding">Defining a Binding</a><br> 2.5.1 <a href="#example-initial-binding-explanation">Explanation of Example</a><br> 2.6 <a href="#basics-service">Defining a Service</a><br> 2.6.1 <a href="#example-initial-service-explanation">Explanation of Example</a><br> 2.7 <a href="#basics-documentation">Documenting the Service</a><br> 2.7.1 <a href="#example-initial-documentation-explanation">Explanation of Example</a><br>3. <a href="#wsdl-xml-representation">WSDL 2.0 Infoset, Schema and Component Model</a><br> 3.1 <a href="#wsdl-infoset-diagram">WSDL 2.0 Infoset</a><br> &nbs;3.2 <a href="#wsdl-schema">WSDL 2.0 Schema</a><br> 3.2.1 <a href="#element-order">WSDL2.0 Element Ordering</a><br> 3.3 <a href="#component-model">WSDL 2.0 Component Model</a><br> 3.3.1 <a href="#import-component">WSDL 2.0 Import and Include</a><br>4. <a href="#more-types">More on Message Types</a><br> 4.1 <a href="#more-types-schema-inline">Inlining XML Schema</a><br> 4.2 <a href="#more-types-schema-import">Importing XML Schema</a><br> 4.3 <a href="#more-types-import-include-summary">Summary of Import and Include Mechanisms</a><br>5. <a href="#more-interfaces">More on Interfaces</a><br> 5.1 <a href="#more-interfaces-interfaces">Interface Syntax </a><br> 5.2 <a href="#more-interfaces-inheritance">Interface Inheritance</a><br> 5.3 <a href="#more-interfaces-fults">Interface Faults</a><br> 5.4 <a href="#more-interfaces-operations">Interface Operations</a><br> 5.4.1 <a href="#more-interfaces-op-attr">Operation Attributes</a><br> 5.4.2 <a href="#N67924">Operation Message References</a><br> 5.4.2.1 <a href="#N67953">The messageLabel Attribute</a><br> 5.4.2.2 <a href="#N67977">The element Attribute</a><br> 5.4.2.3 <a href="#N68058">Multiple infault or outfault Elements</a><br> 5.4.3 <a href="#more-interfaces-meps">Understanding Message Exchange Patterns (MEPs)</a><br>6. <a href="#more-bindings">More on Bindings</a><br> 6.1 <a href="#more-bindings-wsdl">Syntax Summary for Bidings</a><br> 6.2 <a href="#more-bindings-reusable">Reusable Bindings</a><br> 6.3 <a href="#more-bindings-faults">Binding Faults</a><br> 6.4 <a href="#bindingOperations">Binding Operations</a><br> 6.5 <a href="#more-bindings-soap">The SOAP Binding Extension</a><br> 6.5.1 <a href="#more-bindings-soap-example-explanation">Explanation of Example</a><br> 6.6 <a href="#more-bindings-http">The HTTP Binding Extension</a><br> 6.6.1 <a href="#N68516">Explanation of
! Example</a><br> 6.7 <a href="#adv-get-vs-post">HTTP GET Versus POST: Which to Use?</a><br>7. <a href="#advanced-topic_ii">Advanced Topics</a><br> 7.1 <a href="#adv-import-and-authoring">Importing WSDL</a><br> 7.2 <a href="#adv-multiple-inline-schemas">Importing Schemas</a><br> 7.2.1 <a href="#N68858">Schemas in Imported Documents</a><br> 7.2.2 <a href="#N68997">Multiple Inline Schemas in One Document</a><br> 7.2.3 <a href="#adv-schema-location">The schemaLocation Attribute</a><br> 7.2.3.1 <a href="#N69093">Using the id Attribute to Identify Inline
! Schemas</a><br> 7.3 <a href="#adv-extensibility">Extensibility</a><br> 7.3.1 <a href="#adv-optional-versus-required">Optional Versus Required Extensions</a><br> 7.4 <a href="#adv-FP">Features and Properties</a><br> 7.4.1 <a href="#adv-FP-soap-modules">SOAP Modules</a><br> 7.4.2 <a href="#adv-FP-abstract-features">Abstract Features</a><br> 7.4.3 <a href="#adv-fp-properties">Properties</a><br> 7.5 <a href="#adv-MEP">Defining New MEPs</a><br> 7.5.1 <a href="#challenge-confirm">Confirmed Challenge</a><br> 7.6 <a href="#adv-RPCstyle">RPC Style</a><br> 7.7 <a href="#adv-MTOM">MTOM and Attachments Support</a><br> 7.8 <a href="#adv-versionin">Web Service Versioning</a><br> 7.8.1 <a href="#adv-versioning-compatible-evolution">Compatible Evolution</a><br> 7.8.2 <a href="#adv-versioning-big-bang">Big Bang</a><br> 7.8.3 <a href="#ad-versioing-migration">Evolving a Service</a><br> 7.8.4 <a href="#adv-versioning-combined">Combined Approaches</a><br> 7.8.5 <a href="#adv-versioning-examples">Examples of Versioning and Extending a Service</a><br> 7.8.5.1 <a href="#N69984">Additional Optional Elements Added in Content</a><br> 7.8.5.2 <a href="#N70007">Additional Optional Elements Added to a Header</a><br> 7.8.5.3 a href="#N70030">Additional Mandatory Elements in Content</a><br> 7.8.5.4 <a href="#N70053">Additional Optional Operation Added to Interface</a><br> 7.8.5.5 <a href="#N70065">Additional Mandatory Operation Added to Interface</a><br> 7.8.5.6 <a href="#N70091">Indicating Incompatibility by Changing the Endpoint URI</a><br> 7.8.5.7 <a href="#N70100">Indicating Incompatibility by Changing the SOAP Action</a><br> 7.8.5.8 <a href="#N70123">Indicating Incompatibility by Changing the Element Content</a><br> 7.9 <a href="#adv-message-dispatch">Enabling Easy Message Dispatch</a><br> 7.10 <a href="#adv-service-references">Decribing Web Service Messages That Refer to Other Web Services</a><br> 7.10.1 <a href="#reservationDetails">The Reservation Details Web Service</a><br> 7.10.2 <a href="#reservationList">The Reservation List Web Service</a><br> 7.10.3 <a href="#reservationDetails_HTTP">Reservation Details Web Service Using HTTP Transfer</a><br> 7.10.4 <a href="#reservationList_HTTP_GET">Reservation List Web Service Using HTTP GET</a><br> 7.11 <a href="#adv-multiple-docs-describing-same-service">Multiple Interfaces for the Same Service</a><br> 7.12 <a href="#adv-rdf-mapping">Mapping to RDF and Semantic Web</a><br> 7.12.1 <a href="#adv-rdf-rep-wsdl">RDF Representation of WSDL 2.0</a><br> 7.13 <a href="#adv-notes-on-uris">Notes onURIs</a><br> 7.13.1 <a href="#adv-namespaces-and-schema-locations">XML Namespaces and Schema Locations</a><br> 7.13.2 <a href="#adv-relative-uris">Relative URIs</a><br> 7.13.3 <a href="#adv-generating-uris">Generating Temporary URIs</a><br>8. <a href="#References">References</a><br> 8.1 <a href="#Normative-References">Normative References</a><br> 8.2 <a href="#Informative-References">Informative References</a><br></p>
<h3><a name="appendix" id="appendix">Appendix</a></h3><p class="toc">A. <a href="#acknowledgments">Acknowledgements</a> (Non-Normative)<br></p></div><hr><div class="body">
--- 95,102 ----
no official standing.</strong></p><p></p></div>
[...2249 lines suppressed...]
! <h2><a name="References"></a>6. References</h2>
<p>@@ To do: Enable the reference to the RDF mapping when it's done. @@</p>
<div class="div2">
! <h3><a name="Normative-References"></a>6.1 Normative References</h3>
<dl>
<dt class="label"><a name="RFC2119"></a>[IETF RFC 2119] </dt><dd>
***************
*** 3884,3888 ****
<div class="div2">
! <h3><a name="Informative-References"></a>8.2 Informative References</h3>
<dl>
<dt class="label"><a name="RFC2045"></a>[IETF RFC 2045] </dt><dd>
--- 3914,3918 ----
<div class="div2">
! <h3><a name="Informative-References"></a>6.2 Informative References</h3>
<dl>
<dt class="label"><a name="RFC2045"></a>[IETF RFC 2045] </dt><dd>
Received on Friday, 24 June 2005 23:34:21 UTC