- From: David Booth via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 13 Apr 2005 04:40:47 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20
In directory hutz:/tmp/cvs-serv22650
Modified Files:
wsdl20-primer.xml wsdl20-primer.html
Log Message:
Finished editing/updating section 3 (except for minor ToDos).
Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.44
retrieving revision 1.45
diff -C2 -d -r1.44 -r1.45
*** wsdl20-primer.xml 1 Apr 2005 18:06:48 -0000 1.44
--- wsdl20-primer.xml 13 Apr 2005 04:40:45 -0000 1.45
***************
*** 120,126 ****
<head>WSDL 2.0 Basics</head>
! <p>This section introduces the basic concepts used in WSDL 2.0 through the description of a hypothetical hotel reservation service. We start with a simple scenario, and later add more requirements to illustrate how more advanced WSDL2.0 features may be used. </p>
! <!-- ************************ GreatH *************************** --><div2 id="basics-greath-scenario"><head>Example Scenario: The GreatH Hotel Reservation Service</head><p>Hotel GreatH is located in a remote island. It has been relying on fax and phone to provide room reservations. Even though the facilities and prices at GreatH are better than what its competitor offers, GreatH notices that its competitor is getting more customers than GreatH. After research, GreatH realizes that this is because the competitor offers a Web service that permits travel agent reservation systems to reserve rooms directly over the Internet. GreatH then hires us to build a reservation Web service with the following functionality: <ulist><item><p><emph>CheckAvailability</emph>. To check availability, the client must specify a check-in date, a check-out date, and room type. 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 not. If any input dat 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</emph> operation. </p><pThe 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[
--- 120,126 ----
<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[
***************
*** 202,206 ****
</description>]]></eg>
! </example></div2><div2 id="basics-getting-started"><head>Getting Started: Defining a WSDL Target Namespace</head><p>Before writing our WSDL 2.0 document, we need to decide on a <emph>WSDL target namespace</emph> URI for it. The WSDL target namespace is analogous to an XML Schema target namespace: interface, binding and service names that we define in our WSDL document will be associated with the WSDL target namespace, and thus will be distinguishable from similar names in a different WSDL target namespace. (This will become important if using WSDL 2.0's import or interface inheritance mechanisms.) </p><p>The value of the WSDL target namespace MUST be an absolute URI. Furthermore, it SHOULD be dereferenceable to a WSDL document that describes the Web service that the WSDL target namespace is used to describe. For example, the GreatH owners SHOULD make the WSDL document available from this URI. (And if a WSDL description is split into multiple documents, then the WSDL target namespace should reslve to a master document that includes all the WSDL documents needed for that service description.) However, there is no absolute requirement for this URI to be dereferenceable; thus a WSDL processor must not depend on it being dereferenceable. </p><p>This recommendation may sound circular, but bear in mind that the client might have obtained the WSDL document from anywhere -- not necessarily an authoritative source. But by dereferencing the WSDL target namespace URI, a user SHOULD be able to obtain an authoritative version. Since GreatH will be the owner of the service, the WSDL 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 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 Document</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
--- 202,206 ----
</description>]]></eg>
! </example></div2><div2 id="basics-getting-started"><head>Getting Started: Defining a WSDL Target Namespace</head><p>Before writing our WSDL 2.0 document, we need to decide on a <emph>WSDL target namespace</emph> URI for it. The WSDL target namespace is analogous to an XML Schema target namespace: interface, binding and service names that we define in our WSDL document will be associated with the WSDL target namespace, and thus will be distinguishable from similar names in a different WSDL target namespace. (This will become important if using WSDL 2.0's import or interface inheritance mechanisms.) </p><p>The value of the WSDL target namespace MUST be an absolute URI. Furthermore, it SHOULD be dereferenceable to a WSDL document that describes the Web service that the WSDL target namespace is used to describe. For example, the GreatH owners SHOULD make the WSDL document available from this URI. (And if a WSDL description is split into multiple documents, then the WSDL target namespace should reslve to a master document that includes all the WSDL documents needed for that service description.) However, there is no absolute requirement for this URI to be dereferenceable, so a WSDL processor must not depend on it being dereferenceable. </p><p>This recommendation may sound circular, but bear in mind that the client might have obtained the WSDL document from anywhere -- not necessarily an authoritative source. But by dereferencing the WSDL target namespace URI, a user SHOULD be able to obtain an authoritative version. Since GreatH will be the owner of the service, the WSDL 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 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 Document</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
***************
*** 213,220 ****
. . .
</description>]]></eg>
! </example><div3 id="example-empty-shell-explanation"><head>Explanation of Example</head><p><glist><gitem><label><code><description</code></label><def><p>Every WSDL 2.0 document has a <code>description</code> element as its top-most element. This merely acts as a container for the rest of the WSDL 2.0 document, and is used to declare namespaces that will be used throughout the document.</p></def></gitem><gitem><label><code>xmlns="http://www.w3.org/2004/08/wsdl"</code></label><def><p>This is the XML namespace for WSDL 2.0 itself. Because we have not defined a prefix for it, any unprefixed elements or attributes are expected to be WSDL 2.0 elements or attributes (such as the <code>description</code> element).</p></def></gitem><gitem><label><code>targetNamespace= "http://greath.example.com/2004/wsdl/resSvc"</code></label><def><p>This defines the WSDL 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 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</xspecref>.)</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 s to define the message types that the service will use. We'll use XML Schema to do so, because WSDL 2.0 requires all conformant WSDL processors to support XML Schema at a minimum. However, WSDL 2.0 does not prohibit the use of some other schema definition language.</p><p>WSDL 2.0 allows message types to be defined directly within the WSDL document, inside the <code>types</code> element, which is a child of the <code>description</code> element. (Later we'll see how we can provide the type definitions in a separate document, using XML Schema's <code>import</code> mechanism.) The following schema defines checkAvailability, checkAvailabilityResponse and invalidDataError message types that we'll need. </p><p>In WSDL 2.0, all normal and fault message types must be defined as single <emph>elements</emph> at the topmost level (though of course each element may have any amount of substructure inside it). Thus, a message type must not directly consist of a sequence of elements or other complex type. </p><eample id="example-initial-types">
<head>GreatH Message Types</head>
! <ednote><name>dbooth</name><edtext>Not sure the namespace declarations and prefixes in this schema declaration are correct. In particular, need to check: xmlns:xs="http://www.w3.org/2001/XMLSchema"
! xmlns="http://greath.example.com/2004/schemas/resSvc"</edtext></ednote><eg><![CDATA[
<?xml version="1.0" encoding="utf-8" ?>
<description
--- 213,219 ----
. . .
</description>]]></eg>
! </example><div3 id="example-empty-shell-explanation"><head>Explanation of Example</head><p><glist><gitem><label><code><description</code></label><def><p>Every WSDL 2.0 document has a <code>description</code> element as its top-most element. This merely acts as a container for the rest of the WSDL 2.0 document, and is used to declare namespaces that will be used throughout the document.</p></def></gitem><gitem><label><code>xmlns="http://www.w3.org/2004/08/wsdl"</code></label><def><p>This is the XML namespace for WSDL 2.0 itself. Because we have not defined a prefix for it, any unprefixed elements or attributes are expected to be WSDL 2.0 elements or attributes (such as the <code>description</code> element).</p></def></gitem><gitem><label><code>targetNamespace= "http://greath.example.com/2004/wsdl/resSvc"</code></label><def><p>This defines the WSDL 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 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</xspecref>.)</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 s to define the message types that the service will use. We'll use XML Schema to do so, because WSDL 2.0 WSDL 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 document, inside the <code>types</code> element, which is a child of the <code>description</code> element. (Later we'll see how we can provide the type definitions in a separate document, using XML Schema's <code>import</code> mechanism.) The following schema defines checkAvailability, checkAvailabilityResponse and invalidDataError message types that we'll need. </p><p>In WSDL 2.0, all normal and fault message types must be defined as single <emph>elements</emph> at the topmost level (though of course each element may have any amount of substructure inside it). Thus, a message type must not directly consist of a sequence of elements or other complex type. </p><example id="exmple-initial-types">
<head>GreatH Message Types</head>
! <eg><![CDATA[
<?xml version="1.0" encoding="utf-8" ?>
<description
***************
*** 296,300 ****
. . .
</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 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 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 unique within an interface.</p></def></gitem><gitem><label><code>element = "ghns:invalidDataError"/></code></label><def><p>The <code>element</code> attribute specifies the schema type of the fault message, as previously defined in the <code>types</code> section. </p></def></gitem><gitem><label><code><operation name="opCheckAvailability"</code></label><def><p>The <code>name</code> attribute defines a name for this operation, so that it can be referenced later when bindings are defined. Operation names must also be unique within an interface. (WSDL 2.0 uses separate symbol spaces for operation and fault names, so operation name "foo" is distinct from fault name "foo".)</p></def></gitem><gitem><label><code>pattern="http://www.w3.org/2004/03/wsdl/in-out" ></code></label><def><p>Ths line specifies that this operation will use the <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref> pattern as described above. WSDL 2.0 uses URIs to identify message exchange patterns in order to ensure that they are uambiguously identified, while also permitting future new patterns to be defined by anyone. (However, just because someone defines a new pattern and creates a URI to identify it, that does <emph>not</emph> mean that other WSDL processors will automatically recognize or understand that pattern. As with any other extension, it can be used among processors that do recognize and understand it.)</p></def></gitem><gitem><label><code><input messageLabel="In"</code></label><def><p>The <code>input</code> element specifies an input message. Even though we have already specified which message exchange pattern the operation will use, a message exchange pattern represents a template for a message sequence, and in general it may consist of multiple inpt 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="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref> pattern 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="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">In-Out</xspecref> for the <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref> pattern. However, in theory, new patterns could be defined that involve multiple input messages, and the different input messages in the pattern would be distinguished by having different labels.</p></def></gitem><gitem><label><code>element="ghns:checkAvailabiliy" /></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></label><def><p>This associates an output fault with this operation. Faults are declared a little differently than normal messages. The <code>ref</code> attribute refers to the name of a previously defined fault in this interface -- not a message schema type directly. Since message exchange patterns could in general involve a sequence of several messages, a fault could potentially occur at various points within the message sequence. Because one may wish to associate a different fault with each permitted point in the sequence, the messageLabel is used to indicate the desired point for this particular fault. It does so idirectly 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="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-trigger">message-triggers-fault rule</xspecref>; others use a <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-replacement">fault-replaces-message</xspecref> rule. See <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSDL-PART2"/> section 2.1.2 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-trigger">Message Triggers Fault</xspecref> and section 2.1.1 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#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><ednote><name>dbooth</name><edtext>[This note is only relevant to the editors.] Hmm, I just reaized that in the source XML for this primer, in some cases we've been using <el> to indicate an element name, and in other cases we've been using <code>. At present, the xmlspec XSLT script seems to translate them both into <code> elements in the generated HTML, but we should probably make them consistent, in case that changes. </edtext></ednote></div3></div2>
--- 295,299 ----
. . .
</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 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 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><gitem><label><code>pattern="http://www.w3.org/2004/03/wsdl/in-out" ></code></label><def><pThis line specifies that this operation will use the <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref> pattern as described above. WSDL 2.0 uses URIs to identify message exchange patterns in order to ensure that the identifiers are globally unambiguous, while also permitting future new patterns to be defined by anyone. (However, just because someone defines a new pattern and creates a URI to identify it, that does <emph>not</emph> mean that other WSDL processors will automatically recognize or understand that pattern. As with any other extension, it can be used among processors that <i>do</i> recognize and understand it.)</p></def></gitem><gitem><label><code><input messageLabel="In"</code></label><def><p>The <code>input</code> element specifies an input message. Even though we have already specified which message exchange pattern the operation will use, a message exchange pattern represents a template for a message sequence, and in theory could consis 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="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref> pattern 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="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">In-Out</xspecref> for the <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#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 having different labels.</p></def></gitem><gitem><label><code>element="ghns:checkvailability" /></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></label><def><p>This associates an output fault with this operation. Faults are declared a little differently than normal messages. The <code>ref</code> attribute refers to the name of a previously defined fault in this interface -- not a message schema type directly. Since message exchange patterns could in general involve a sequence of several messages, a fault could potentially occur at various points within the message sequence. Because one may wish to associate a different fault with each permitted point in the sequence, the messageLabel is used to indicate the desired point for this particular fault. Itdoes 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="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-trigger">message-triggers-fault rule</xspecref>; others use a <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-replacement">fault-replaces-message</xspecref> rule. See <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSDL-PART2"/> section 2.1.2 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-trigger">Message Triggers Fault</xspecref> and section 2.1.1 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#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>
***************
*** 336,340 ****
.)
</p>
! <p>In order to accommodate new kinds of message formats and transmission protocols, bindings are defined using extensions to the WSDL 2.0 language, via WSDL 2.0's open content model. WSDL 2.0 Part 3 defines binding constructs for SOAP 1.2 <bibref ref="SOAP12-PART1"/> and HTTP 1.1 <bibref ref="RFC2616"/> as predefined extensions, so that SOAP 1.2 or HTTP 1.1 bindings can be easily defined in WSDL documents. However, other specifications could define new binding constructs that could also be used to define bindings. (As with any extension, other WSDL processors would have to know about the new constructs in order to make use of them.) </p><p>For the GreatH service, we will use SOAP 1.2 as our concrete message format and HTTP as our underlying transmission protocol, as shown below. </p><example id="example-initial-binding">
<head>GreatH Binding Definition</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
--- 335,339 ----
.)
</p>
! <p>In order to accommodate new kinds of message formats and transmission protocols, bindings are defined using extensions to the WSDL 2.0 language, via WSDL 2.0's open content model. (See <specref ref="adv-extensibility"/> for more on extensibility.) WSDL 2.0 Part 3 defines binding constructs for SOAP 1.2 <bibref ref="SOAP12-PART1"/> and HTTP 1.1 <bibref ref="RFC2616"/> as predefined extensions, so that SOAP 1.2 or HTTP 1.1 bindings can be easily defined in WSDL documents. However, other specifications could define new binding constructs that could also be used to define bindings. (As with any extension, other WSDL processors would have to know about the new constructs in order to make use of them.) </p><p>For the GreatH service, we will use SOAP 1.2 as our concrete message format and HTTP as our underlying transmission protocol, as shown below. </p><example id="example-initial-binding">
<head>GreatH Binding Definition</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
***************
*** 379,385 ****
. . .
</description>]]></eg>
! </example><div3 id="example-initial-binding-explanation"><head>Explanation of Example</head><glist><gitem><label><code>xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"</code></label><def><p>We've added two more namespace declarations. This one is the namespace for the SOAP 1.2 binding construct that is defined in WSDL 2.0 Part 3 <bibref ref="SOAP12-PART1"/>. Elements and attributes prefixed with <code>wsoap:</code> are constructs defined there. </p></def></gitem><gitem><label><code>xmlns:soap="http://www.w3.org/2003/05/soap-envelope"</code></label><def><p>This namespace is defined by the SOAP 1.2 specification itself. The SOAP 1.2 specification defines certain terms within this namespace to unambiguously identify particular concepts. Thus, we will use the <code>soap:</code> prefix when we need to refer to one of those terms.</p></def></gitem><gitem><label><code><binding name="reservationSOAPBinding"</code></label><def><p>Bindings are declared directly inside the <code>description</code>element. The <att>name</att> attribute defines a name for this binding. Each name must be unique among all bindings in this WSDL 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 target namespace for this WSDL 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 import mechanis can be used to combine components that are defined in different WSDL target namespaces.</p></def></gitem><gitem><label><code>type="http://www.w3.org/2004/08/wsdl/soap12"</code></label><def><p>This specifies the type of concrete message format to use, in this case SOAP 1.2.</p></def></gitem><gitem><label><code>wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP"</code></label><def><p>This attribute is specific to WSDL 2.0's SOAP binding (thus it uses the <code>wsoap:</code> prefix). It specifies the underlying transmission protocol that should be used, in this case HTTP. </p></def></gitem><gitem><label><code><operation ref="tns:opCheckAvailability"</code></label><def>
<p>
! This not defining a new operation. Rather, it is referencing the
previously defined
<code>opCheckAvailability</code>
--- 378,384 ----
. . .
</description>]]></eg>
! </example><div3 id="example-initial-binding-explanation"><head>Explanation of Example</head><glist><gitem><label><code>xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"</code></label><def><p>We've added two more namespace declarations. This one is the namespace for the SOAP 1.2 binding construct that is defined in WSDL 2.0 Part 3 <bibref ref="SOAP12-PART1"/>. Elements and attributes prefixed with <code>wsoap:</code> are constructs defined there. </p></def></gitem><gitem><label><code>xmlns:soap="http://www.w3.org/2003/05/soap-envelope"</code></label><def><p>This namespace is defined by the SOAP 1.2 specification itself. The SOAP 1.2 specification defines certain terms within this namespace to unambiguously identify particular concepts. Thus, we will use the <code>soap:</code> prefix when we need to refer to one of those terms.</p></def></gitem><gitem><label><code><binding name="reservationSOAPBinding"</code></label><def><p>Bindings are declared directly inside the <code>description</code>element. The <att>name</att> attribute defines a name for this binding. Each name must be unique among all bindings in this WSDL 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 target namespace for this WSDL 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 import mechanim can be used to combine components that are defined in different WSDL target namespaces.</p></def></gitem><gitem><label><code>type="http://www.w3.org/2004/08/wsdl/soap12"</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 (thus it uses the <code>wsoap:</code> prefix). It specifies the underlying transmission protocol that should be used, in this case HTTP. </p></def></gitem><gitem><label><code><operation ref="tns:opCheckAvailability"</code></label><def>
<p>
! This not defining a new operation; rather, it is referencing the
previously defined
<code>opCheckAvailability</code>
***************
*** 394,398 ****
</xspecref>.)
</p>
! </def></gitem><gitem><label><code>wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response"></code></label><def><p>This attribute is also specific to WSDL 2.0's SOAP binding. It specifies the SOAP message exchange pattern that will be used to implement the abstract WSDL 2.0 message exchange pattern (<xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref>) that was specified when the <code>opCheckAvailability</code> operation was defined. </p></def></gitem><gitem><label><code><fault ref="tns:invalidDataFault"</code></label><def><p>As with a binding operation, this is not declaring a new fault. Rather, it is referencing a fault (<code>invalidDataFault</code>) that was previously defined in the <code>opCheckAvailability</code> interface, in order to specify binding details for it.</p></def></gitem><gitem><label><code>wsoap:code="soap:Sender"/></code></label><def><p>This attribute is also specific to WSDL 2.0's SOAP binding. This specifies te SOAP 1.2 fault code that will cause this fault message to be sent. If desired, an list of subcodes can also be specified 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 in order to indicate the binding details that are to be used at that endpoint. A service is only permitted to have one interface. (However, WSDL 2.0 does not prohibit one from declaring multiple services that use different interfaces but happen to use the same endpoint address. See <specref rf="adv-multiple-docs-describing-same-service"/>.) </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" ?>
--- 393,397 ----
</xspecref>.)
</p>
! </def></gitem><gitem><label><code>wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response"></code></label><def><p>This attribute is also specific to WSDL 2.0's SOAP binding. It specifies the SOAP message exchange pattern that will be used to implement the abstract WSDL 2.0 message exchange pattern (<xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref>) that was specified when the <code>opCheckAvailability</code> operation was defined. </p></def></gitem><gitem><label><code><fault ref="tns:invalidDataFault"</code></label><def><p>As with a binding operation, this is not declaring a new fault; rather, it is referencing a fault (<code>invalidDataFault</code>) that was previously defined in the <code>opCheckAvailability</code> interface, in order to specify binding details for it.</p></def></gitem><gitem><label><code>wsoap:code="soap:Sender"/></code></label><def><p>This attribute is also specific to WSDL 2.0's SOAP binding. This specifies th SOAP 1.2 fault code that will cause this fault message to be sent. If desired, a list of subcodes can also be specified 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" ?>
***************
*** 428,432 ****
</service>]]></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 target namespace. The name attribute is required in order to facilitate the use of URIs to indentify components in WSDL 2.0 documents. (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 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 unique wthin 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 documention will need to explain other application-level requirements for its use. For example, such documentation should explain the purpos 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 author to include some human-readable documentation inside a WSDL document. It is a convenient place to reference any additional 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 (as can be seen in the syntax summary presented later), though in this example we have only demonstrated its use at the beginning.</p><example id="example-initial-documentation">
<head>Documenting the GreatH Service</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
--- 427,431 ----
</service>]]></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 target namespace. The name attribute is required. It allows URIs to be created that indentify 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 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 unique withn 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 documention will need to explain other application-level requirements for its use. For example, such documentation should explain the purpose ad 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 author to include some human-readable documentation inside a WSDL 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" ?>
***************
*** 452,462 ****
</div1>
! <div1 id="wsdl-xml-representation"><head>WSDL 2.0 XML Representation</head>
! <p>In the core language specification, WSDL 2.0 constructs are defined as a set of abstract components, along with a mapping to an XML infoset representation for these components. For easier consumption, the primer uses the XML representation of WSDL components.</p>
! <div2 id="wsdl-infoset-diagram"><head>WSDL2.0 Infoset Model Overview</head>
! <p>The following diagram gives an overview of a WSDL2.0 XML Infoset.
<graphic source="images/WSDL20InfosetModel.png" alt="WSDL 2.0 Infoset Diagram"/>
--- 451,461 ----
</div1>
! <div1 id="wsdl-xml-representation"><head>WSDL 2.0 XML Infoset and Component Model</head>
! <p>In conventional computer science theory, a language consists of a (possibly infinite) set of sentences, and each sentence is a string of literal symbols or characters. The language specification must therefore define two things: the set of permissible sentences, and 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 can be created from morethan one physical document, a WSDL 2.0 document does not necessarily correspond to a single physical 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. </p><p>Unfortunately, the terms "element information item" and "attribute information item" are rather lengthy. 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 Model Overview</head>
! <p>The following diagram gives an overview of the XML Infoset for a WSDL 2.0 document.
<graphic source="images/WSDL20InfosetModel.png" alt="WSDL 2.0 Infoset Diagram"/>
***************
*** 464,563 ****
</p>
- <p>A WSDL Infoset contains representations for a collection of WSDL components which share a common target namespace. Note that WSDL definitions may be represented by one or more WSDL Infosets, that is one or more <el>description</el> elements which all share a common target namespace. When a WSDL Infoset contains one or more <el>import</el> elements, the WSDL definition corresponds to a collection with components drawn from multiple target namespaces.</p>
- </div2>
-
- <div2 id="wsdl-xml-syntax"><head>WSDL2.0 XML Syntax Summary</head>
! <p>The XML syntax of the infoset model is summarized below. The following conventions are followed for the syntax: </p>
! <ulist>
! <item>
! <p>The syntax appears as an XML instance, but the values indicate the data types instead of values.</p>
! </item>
! <item>
! <p>Characters are appended to elements and attributes as follows: "?" (0 or 1), "*" (0 or more), "+" (1 or more).</p>
! </item>
! <item>
! <p>Elements names ending in "..." (such as <element…/> or <element…>) indicate that elements/attributes irrelevant to the context are being omitted.</p>
! </item>
! </ulist>
!
! <!-- ednote><name>dbooth</name><edtext>To do: check the above elipses (...), as they weren't rendering properly at one point.</edtext></ednote -->
!
! <!--div3 id="basics-syntax-brief"><head>Brief Syntax Summary</head><ednote><edtext>To do: Insert short summary here</edtext></ednote></div3>
!
!
!
!
! </div3>
!
! <div3 id="basics-syntax-longer">
! <head>Longer Syntax Summary</head -->
!
!
! <eg xml:space="preserve">
! <description targetNamespace="<emph>xs:anyURI</emph>" >
!
! <import namespace="<emph>xs:anyURI</emph>" location="<emph>xs:anyURI</emph>"?/>*
!
! <include location="<emph>xs:anyURI</emph>"/>*
!
! <types/>
!
! <interface name="<emph>xs:NCName</emph>" extends="<emph>list of xs:QName</emph>"? styleDefault="<emph>list of xs:anyURI</emph>"? >
!
! <fault name="<emph>xs:NCName</emph>" element="<emph>xs:QName</emph>"?/>*
!
! <operation name="<emph>xs:NCName</emph>" pattern="<emph>xs:anyURI</emph>" style="<emph>list of xs:anyURI</emph>"? safe="<emph>xs:boolean</emph>"? >
!
! <input messageLabel="<emph>xs:NCName</emph>"? element="<emph>union of xs:QName, xs:Token</emph>"? />*
!
! <output messageLabel="<emph>xs:NCName</emph>"? element="<emph>union of xs:QName, xs:Token</emph>"? />*
!
! <infault ref="<emph>xs:QName</emph>" messageLabel="<emph>xs:NCName</emph>"? />*
!
! <outfault ref="<emph>xs:QName</emph>" messageLabel="<emph>xs:NCName</emph>"? />*
!
! </operation>*
!
! </interface>*
!
! <binding name="<emph>xs:NCName</emph>" interface="<emph>xs:QName</emph>"? type="<emph>xs:anyURI</emph>" >
!
! <fault ref="<emph>xs:QName</emph>" />*
!
! <operation ref="<emph>xs:QName</emph>" >
!
! <input messageLabel="<emph>xs:NCName</emph>"? />*
!
! <output messageLabel="<emph>xs:NCName</emph>"? />*
!
! <infault ref="<emph>xs:QName</emph>" messageLabel="<emph>xs:NCName</emph>"? />*
!
! <outfault ref="<emph>xs:QName</emph>" messageLabel="<emph>xs:NCName</emph>"? />*
!
! </operation>*
!
! </binding>*
!
! <service name="<emph>xs:NCName</emph>" interface="<emph>xs:QName</emph>" >
!
! <endpoint name="<emph>xs:NCName</emph>" binding="<emph>xs:QName</emph>" address="<emph>xs:anyURI</emph>"? />*
!
! </service>*
!
! </description>
! </eg>
-
- <p>In addition, <code>feature</code> and <code>property</code> elements are allowed inside all WSDL elements except <code>import</code>, <code>include</code>, and <code>types</code>. Also, an optional <code>documentation</code> element is allowed as the first child of any WSDL element as a container for human readable and/or machine processable documentation. The content of <code>documentation</code> is arbitrary characters and elements
- ("mixed" content in XML Schema). </p>
- </div2>
! <div2 id="wsdl-element-order">
! <head>Order of WSDL Elements and Placement of Extensions</head>
! <p>The order of the WSDL2.0 elements matters. Though the WSDL2.0 schema doesn't require the elements be placed in any order, the specification (part 1 section 2.1.2) clearly states a set of constraints about how the children elements of the <code>description</code> element should be ordered. The following is a pseudo-content model of <code>description</code> </p>
<eg xml:space="preserve">
--- 463,476 ----
</p>
! </div2>
! <div2 id="wsdl-schema">
! <head>WSDL 2.0 Schema and Element Ordering</head>
! <p>The WSDL 2.0 specification supplies a normative WSDL 2.0 schema @@ToDo: Add reference@@, defined in XML Schema, which can be used as an aid in validating WSDL 2.0 documents. Although the WSDL 2.0 schema does not indicate the required ordering of elements, the WSDL 2.0 specification (Part 1 section 2.1.2) clearly states a set of constraints about how the children elements of the <code>description</code> element should be ordered. Thus, the order of the WSDL 2.0 elements matters, in spite of what the WSDL 2.0 schema says. </p><p>The following is a pseudo-content model of <code>description</code>.</p>
<eg xml:space="preserve">
***************
*** 570,579 ****
</eg>
! <p>In other words,the children elements of the <code>description</code> element should be ordered as follows:
</p>
<ulist>
<item>
<p>
! An optoinal <el>documentation</el> comes first, if presents.
</p>
</item>
--- 483,492 ----
</eg>
! <p>In other words, the children elements of the <code>description</code> element should be ordered as follows:
</p>
<ulist>
<item>
<p>
! An optional <el>documentation</el> comes first, if present.
</p>
</item>
***************
*** 644,648 ****
</div2>
! </div1>
--- 557,561 ----
</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 stipulates semantic constraints over and above conformance to this XML Infoset structure. 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. </p><p>In general, the WSDL 2.0 component model parallels the structure of the required XML Infoset illustrated above. For example, the <emph>Description</emph>, <emph>Interface</emph>, <emph>Binding</emph>, <emph>Service/emph> and <emph>Endpoint</emph> <emph>components</emph> correspond to the <code>description</code>, <code>interface</code>, <code>binding</code>, <code>service</code>, and <code>endpoint</code> element information items, respectively. Furthermore, each of these components has <emph>properties</emph> whose values are (usually) derived from the element and attribute information item children of those element information items. For example, the Service component corresponds to the <code>service</code> element information item, so the Service component has an {endpoints} property whose value is a set of Endpoint components corresponding to the <code>endpoint</code> element information item children of that <code>service</code> element information item. (Whew!)<ednote><name>dbooth</name><date>2005-04-12</date><edtext>Should we add a graphic illustrating the parallel structure of the component model and the XML Infoset?</edtext></ednote></p><p>The WSDL 2.0 component model is particularly helpful in definin the meaning of <code>import</code> and <code>include</code>. WSDL 2.0 <code>include</code> allows components from another WSDL 2.0 document having the same targetNamespace to be merged in with the components of the current WSDL 2.0 document, and is transitive (i.e., if the included document also includes a WSDL 2.0 document, then those components will also be merged, and so on). WSDL 2.0 <code>import</code> allows components from another WSDL 2.0 document having a different targetNamespace to be merged in with comonents of the current WSDL 2.0 document, and is not transitive.</p></div2></div1>
***************
*** 652,656 ****
<div2 id="more-types"><head>Defining Messages</head>
<p>WSDL 2.0 <code>types</code> element provides a mechanism for enclosing messages definitions in a WSDL document. WSDL 2.0 only defines the use W3C XML Schema Language
! <bibref ref="XMLSchemaP1"/>. Support for XML Schema <bibref ref="XMLSchemaP1"/> is required of all WSDL2.0 processors. Alternatively, other type languages can be used via extension to define messages.
</p>
--- 565,569 ----
<div2 id="more-types"><head>Defining Messages</head>
<p>WSDL 2.0 <code>types</code> element provides a mechanism for enclosing messages definitions in a WSDL document. WSDL 2.0 only defines the use W3C XML Schema Language
! <bibref ref="XMLSchemaP1"/>. Support for XML Schema <bibref ref="XMLSchemaP1"/> is required of all WSDL 2.0 processors. Alternatively, other type languages can be used via extension to define messages.
</p>
***************
*** 1004,1008 ****
<p>A total of 8 MEPs are defined in Part 2 of the WSDL 2.0 specification. Hopefully, these MEPs will cover the most common use cases, but they are not meant to be an exhaustive list of MEPs that can be used by operations. More MEPs can be defined for particular application needs by interested parties. <ednote><name>dbooth</name><edtext>Add info about how to define a new MEP?</edtext></ednote></p>
<p>For the 8 MEPs defined by WSDL 2.0, some of them are variations of others based on how faults may be generated. Three common fault generation models are specified. <glist><gitem><label>Fault Replaces Message</label><def><p>Any message after the first in the pattern MAY be replaced with a fault message, which MUST have identical cardinality and direction. The fault message MUST be delivered to the same target node as the message it replaces. </p></def></gitem><gitem><label>Message Triggers Fault</label><def><p>Any message, including the first, MAY trigger a fault message in response. Each recipient MAY generate a fault message, and MUST generate no more than one fault for each triggering message. Each fault message has direction the reverse of its triggering message. The fault message MUST be delivered to the originator of the message which triggered it. If there is no path to this node, the fault MUST be discarded. In the third case, no fault may be generated in the MEP. </p></def></gitem><gitem><abel>No Faults</label><def><p>No faults will be delivered.</p></def></gitem></glist></p>
! <p>Now let's have a look of each of the 8 MEPs. Depends on how the first message in the MEP is initiated, we can probably group the MEPs into in-bound MEPs in which case the service receives the first message in the exchange, and out-bound MEPs in which case the service sends out the first message in the exchange. Such Grouping is only for the purpose of easy reference from discussions in later sections of this primer. WSDL2.0 defines four in-bound MEPS:</p>
<ulist>
<item>
--- 917,921 ----
<p>A total of 8 MEPs are defined in Part 2 of the WSDL 2.0 specification. Hopefully, these MEPs will cover the most common use cases, but they are not meant to be an exhaustive list of MEPs that can be used by operations. More MEPs can be defined for particular application needs by interested parties. <ednote><name>dbooth</name><edtext>Add info about how to define a new MEP?</edtext></ednote></p>
<p>For the 8 MEPs defined by WSDL 2.0, some of them are variations of others based on how faults may be generated. Three common fault generation models are specified. <glist><gitem><label>Fault Replaces Message</label><def><p>Any message after the first in the pattern MAY be replaced with a fault message, which MUST have identical cardinality and direction. The fault message MUST be delivered to the same target node as the message it replaces. </p></def></gitem><gitem><label>Message Triggers Fault</label><def><p>Any message, including the first, MAY trigger a fault message in response. Each recipient MAY generate a fault message, and MUST generate no more than one fault for each triggering message. Each fault message has direction the reverse of its triggering message. The fault message MUST be delivered to the originator of the message which triggered it. If there is no path to this node, the fault MUST be discarded. In the third case, no fault may be generated in the MEP. </p></def></gitem><gitem><abel>No Faults</label><def><p>No faults will be delivered.</p></def></gitem></glist></p>
! <p>Now let's have a look of each of the 8 MEPs. Depends on how the first message in the MEP is initiated, we can probably group the MEPs into in-bound MEPs in which case the service receives the first message in the exchange, and out-bound MEPs in which case the service sends out the first message in the exchange. Such Grouping is only for the purpose of easy reference from discussions in later sections of this primer. WSDL 2.0 defines four in-bound MEPS:</p>
<ulist>
<item>
***************
*** 1027,1031 ****
</item>
</ulist>
! <p>WSDL2.0 also defines four out-bound MEPs which sort of mirror the in-bound MEPs with reserved direction:</p>
<ulist>
<item>
--- 940,944 ----
</item>
</ulist>
! <p>WSDL 2.0 also defines four out-bound MEPs which sort of mirror the in-bound MEPs with reserved direction:</p>
<ulist>
<item>
***************
*** 1061,1065 ****
! </div3></div2>
<!-- **********************************Binding************************** -->
<!-- **********************************Binding************************** -->
--- 974,978 ----
! <ednote><name>dbooth</name><date>20050401</date><edtext>ToDo: Add a section on defining a new MEP. (dbooth will do this if he has time.)</edtext></ednote></div3></div2>
<!-- **********************************Binding************************** -->
<!-- **********************************Binding************************** -->
***************
*** 1348,1352 ****
<div2 id="adv-extensibility">
<head>Extensibility</head>
! <p>WSDL 2.0 provides two extensibility mechanisms: an open content model, which allows XML elements and attributes from other (non-wsdl) XML namespaces to be interspersed into a WSDL document; and <xspecref href="&w3c-designation-part1;#Feature">Features</xspecref> and <xspecref href="&w3c-designation-part1;#Property">Properties</xspecref>. Both mechanisms use URIs to identify the semantics of the extensions. For extension XML elements and attributes, the namespace URI of the extension element or attribute acts as an unambiguous name for the semantics of that extension. For Features and Properties, the Feature or Property is named by a URI.</p><p>In either case, the URI that identifies the semantics of an extension SHOULD be dereferenceable to a document that describes the semantics of that extension. As of this writing, there is no generally accepted standard for what kind of document that should be. However, the <loc href="http://www.w3.org/2001/tag/">W3C TAG</loc> has been discussing the issu (see TAG issue <loc href="http://www.w3.org/2001/tag/issues.html?type=1#namespaceDocument-8">namespaceDocument-8</loc>) and is likely to provide guidance at some point.</p><div3 id="adv-optional-versus-required"><head>Optional Versus Required Extensions</head><p>Extensions can either be required or optional: An <emph>optional</emph> extension is one that the client may either engage or ignore, entirely at its discretion, and is signaled by attribute <code>wsdl:required="false"</code>; whereas a <emph>required</emph> extension is one that MUST be supported and engaged by the client in order for the interaction to succeed properly, and is signaled by attribute <code>wsdl:required="true"</code>. </p><p>The optionality signaled by <code>wsdl:required="false"</code> pertains only to the <emph>client</emph> -- not the service. The service MUST support both optional and required extensions that it advertises in its WSDL document. </p><p>A WSDL processor (acting to realize a client) need not support every coneivable required extension, but if it sees a required extension that it does not recognize or does not support, then it MUST fault. </p></div3><div3 id="adv-scope-of-wsdl-required"><head>Scoping of the wsdl:required Attribute</head><ednote><edtext>To do: Need to check the scoping rules to see if this is correct.</edtext></ednote><p>As a convenience mechanism, the <code>wsdl:required</code> attribute need not be specified on every extension element. If it is omitted from an extension element, its effective value is inherited from the smallest enclosing scope that explicitly sets its value. If there is no enclosing scope that explicitly sets its value, then its value defaults to <code>false</code>. </p><p>Because portions of a Web service description can be written in different physical documents by different people, one should be cautious about setting <code>wsdl:required="false"</code> when an outer scope, written by someone else, had set <code>wsdl:required="true"</code>.</p></div3></div2><div2 id="av-FP">
<head>Features and Properties</head>
--- 1261,1265 ----
<div2 id="adv-extensibility">
<head>Extensibility</head>
! <p>WSDL 2.0 provides two extensibility mechanisms: an open content model, which allows XML elements and attributes from other (non-WSDL 2.0) XML namespaces to be interspersed into a WSDL document; and <xspecref href="&w3c-designation-part1;#Feature">Features</xspecref> and <xspecref href="&w3c-designation-part1;#Property">Properties</xspecref>. Both mechanisms use URIs to identify the semantics of the extensions. For extension XML elements and attributes, the namespace URI of the extension element or attribute acts as an unambiguous name for the semantics of that extension. For Features and Properties, the Feature or Property is named by a URI.</p><p>In either case, the URI that identifies the semantics of an extension SHOULD be dereferenceable to a document that describes the semantics of that extension. As of this writing, there is no generally accepted standard for what kind of document that should be. However, the <loc href="http://www.w3.org/2001/tag/">W3C TAG</loc> has been discussing the ssue (see TAG issue <loc href="http://www.w3.org/2001/tag/issues.html?type=1#namespaceDocument-8">namespaceDocument-8</loc>) and is likely to provide guidance at some point.</p><div3 id="adv-optional-versus-required"><head>Optional Versus Required Extensions</head><p>Extensions can either be required or optional: An <emph>optional</emph> extension is one that the client may either engage or ignore, entirely at its discretion, and is signaled by attribute <code>wsdl:required="false"</code>; whereas a <emph>required</emph> extension is one that MUST be supported and engaged by the client in order for the interaction to succeed properly, and is signaled by attribute <code>wsdl:required="true"</code>. </p><p>The optionality signaled by <code>wsdl:required="false"</code> pertains only to the <emph>client</emph> -- not the service. The service MUST support both optional and required extensions that it advertises in its WSDL document. </p><p>A WSDL processor (acting to realize a client) need not support everyconceivable required extension, but if it sees a required extension that it does not recognize or does not support, then it MUST fault. </p></div3><div3 id="adv-scope-of-wsdl-required"><head>Scoping of the wsdl:required Attribute</head><ednote><edtext>To do: Need to check the scoping rules to see if this is correct.</edtext></ednote><p>As a convenience mechanism, the <code>wsdl:required</code> attribute need not be specified on every extension element. If it is omitted from an extension element, its effective value is inherited from the smallest enclosing scope that explicitly sets its value. If there is no enclosing scope that explicitly sets its value, then its value defaults to <code>false</code>. </p><p>Because portions of a Web service description can be written in different physical documents by different people, one should be cautious about setting <code>wsdl:required="false"</code> when an outer scope, written by someone else, had set <code>wsdl:required="true"</code>.</p></div3></div2><div2 i="adv-FP">
<head>Features and Properties</head>
Index: wsdl20-primer.html
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.html,v
retrieving revision 1.24
retrieving revision 1.25
diff -C2 -d -r1.24 -r1.25
*** wsdl20-primer.html 31 Mar 2005 16:33:11 -0000 1.24
--- wsdl20-primer.html 13 Apr 2005 04:40:45 -0000 1.25
***************
*** 193,198 ****
<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 XML
! Representation</a><br />
4. <a href="#advanced-topic-i">Advanced Topic I: More on Messages,
Interfaces, Bindings, and Services Definitions</a><br />
--- 193,198 ----
<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 XML Infoset and
! Component Model</a><br />
4. <a href="#advanced-topic-i">Advanced Topic I: More on Messages,
Interfaces, Bindings, and Services Definitions</a><br />
***************
*** 248,259 ****
href="#example-initial-documentation-explanation">Explanation of
Example</a><br />
! 3. <a href="#wsdl-xml-representation">WSDL 2.0 XML
! Representation</a><br />
!     3.1 <a href="#wsdl-infoset-diagram">WSDL2.0
! Infoset Model Overview</a><br />
!     3.2 <a href="#wsdl-xml-syntax">WSDL2.0 XML
! Syntax Summary</a><br />
!     3.3 <a href="#wsdl-element-order">Order of
! WSDL Elements and Placement of Extensions</a><br />
4. <a href="#advanced-topic-i">Advanced Topic I: More on Messages,
Interfaces, Bindings, and Services Definitions</a><br />
--- 248,259 ----
href="#example-initial-documentation-explanation">Explanation of
Example</a><br />
! 3. <a href="#wsdl-xml-representation">WSDL 2.0 XML Infoset and
! Component Model</a><br />
!     3.1 <a href="#wsdl-infoset-diagram">WSDL
! 2.0 Infoset Model Overview</a><br />
!     3.2 <a href="#wsdl-schema">WSDL 2.0 Schema
! and Element Ordering</a><br />
!     3.3 <a href="#component-model">WSDL 2.0
! Component Model</a><br />
4. <a href="#advanced-topic-i">Advanced Topic I: More on Messages,
Interfaces, Bindings, and Services Definitions</a><br />
***************
*** 343,353 ****
Schemas</a><br />
        5.13.1 <a
! href="#id5211929">Schemas in Imported Documents</a><br />
        5.13.2 <a
! href="#id5212232">Multiple Inline Schemas on One Document</a><br />
    5.14 <a href="#adv-schema-location">The
schemaLocation Attribute</a><br />
        5.14.1 <a
! href="#id5212540">Using the id Attribute to Identify Inline
Schemas</a><br />
    5.15 <a href="#adv-rdf-mapping">Mapping to
--- 343,353 ----
Schemas</a><br />
        5.13.1 <a
! href="#id5211838">Schemas in Imported Documents</a><br />
        5.13.2 <a
! href="#id5212141">Multiple Inline Schemas on One Document</a><br />
    5.14 <a href="#adv-schema-location">The
schemaLocation Attribute</a><br />
        5.14.1 <a
! href="#id5212449">Using the id Attribute to Identify Inline
Schemas</a><br />
    5.15 <a href="#adv-rdf-mapping">Mapping to
***************
*** 498,502 ****
through the description of a hypothetical hotel reservation
service. We start with a simple scenario, and later add more
! requirements to illustrate how more advanced WSDL2.0 features may
be used.</p>
--- 498,502 ----
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>
***************
*** 506,528 ****
Hotel Reservation Service</h3>
! <p>Hotel GreatH is located in a remote island. It has been relying
! on fax and phone to provide room reservations. Even though the
! facilities and prices at GreatH are better than what its competitor
! offers, GreatH notices that its competitor is getting more
! customers than GreatH. After research, GreatH realizes that this is
! because the competitor offers a Web service that permits travel
! agent reservation systems to reserve rooms directly over the
! Internet. GreatH then hires us to build a reservation Web service
! with the following functionality:</p>
<ul>
<li>
<p><em>CheckAvailability</em>. To check availability, the client
! must specify a check-in date, a check-out date, and room type room,
! and the Web service will provide the room rate if such a room is
! available. If any input data is invalid, the service should return
! an error. Thus, the service will accept a
! <code>checkAvailability</code> message and return a
! <code>checkAvailabilityResponse</code> or
<code>invalidDataFault</code> message.</p>
</li>
--- 506,528 ----
Hotel Reservation Service</h3>
! <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:</p>
<ul>
<li>
<p><em>CheckAvailability</em>. 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 not. 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>
</li>
***************
*** 664,668 ****
should resolve to a master document that includes all the WSDL
documents needed for that service description.) However, there is
! no absolute requirement for this URI to be dereferenceable; thus a
WSDL processor must not depend on it being dereferenceable.</p>
--- 664,668 ----
should resolve to a master document that includes all the WSDL
documents needed for that service description.) However, there is
! no absolute requirement for this URI to be dereferenceable, so a
WSDL processor must not depend on it being dereferenceable.</p>
***************
*** 743,747 ****
specified above as the value of the <code>targetNamespace</code>
attribute. This will allow us later to use the <code>tns:</code>
! prefix in qnames, to refer to the WSDL target namespace of the
GreatH service. (For more on QNames see [<cite><a href="#XMLNS">XML
Namespaces</a></cite>] section 3 <a
--- 743,747 ----
specified above as the value of the <code>targetNamespace</code>
attribute. This will allow us later to use the <code>tns:</code>
! prefix in QNames, to refer to the WSDL target namespace of the
GreatH service. (For more on QNames see [<cite><a href="#XMLNS">XML
Namespaces</a></cite>] section 3 <a
***************
*** 762,769 ****
messages, so a good starting point in describing the service is to
define the message types that the service will use. We'll use XML
! Schema to do so, because WSDL 2.0 requires all conformant WSDL
! processors to support XML Schema 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
--- 762,768 ----
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 WSDL 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
***************
*** 787,806 ****
GreatH Message Types</i></p>
- <table border="1" summary="Editorial note: dbooth">
- <tr>
- <td align="left" valign="top" width="50%"><b>Editorial note:
- dbooth</b></td>
- <td align="right" valign="top" width="50%"> </td>
- </tr>
-
- <tr>
- <td colspan="2" align="left" valign="top">Not sure the namespace
- declarations and prefixes in this schema declaration are correct.
- In particular, need to check:
- xmlns:xs="http://www.w3.org/2001/XMLSchema"
- xmlns="http://greath.example.com/2004/schemas/resSvc"</td>
- </tr>
- </table>
-
<div class="exampleInner">
<pre>
--- 786,789 ----
***************
*** 1019,1026 ****
<code>description</code> element. In this example, we are declaring
only one interface, but in general a WSDL document may declare more
! than one interface (each one for use with a different service).
! Thus, each interface must be given a name that is unique within the
! set of interfaces defined in this WSDL target namespace. Interface
! names are tokens that must not contain a space or colon (":").</p>
</dd>
--- 1002,1009 ----
<code>description</code> element. In this example, we are declaring
only one interface, but in general a WSDL 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 target
! namespace. Interface names are tokens that must not contain a space
! or colon (":").</p>
</dd>
***************
*** 1031,1036 ****
<p>The <code>name</code> attribute defines a name for this fault.
The name is required so that when an operation is defined, it can
! reference the desired fault by name. Fault names must unique within
! an interface.</p>
</dd>
--- 1014,1019 ----
<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>
</dd>
***************
*** 1064,1075 ****
href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">
in-out</a> pattern as described above. WSDL 2.0 uses URIs to
! identify message exchange patterns in order to ensure that they are
! uambiguously identified, while also permitting future new patterns
! to be defined by anyone. (However, just because someone defines a
! new pattern and creates a URI to identify it, that does
! <em>not</em> mean that other WSDL processors will automatically
! recognize or understand that pattern. As with any other extension,
! it can be used among processors that do recognize and understand
! it.)</p>
</dd>
--- 1047,1058 ----
href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">
in-out</a> pattern as described above. WSDL 2.0 uses URIs to
! identify message exchange patterns in order to ensure that the
! identifiers are globally unambiguous, while also permitting future
! new patterns to be defined by anyone. (However, just because
! someone defines a new pattern and creates a URI to identify it,
! that does <em>not</em> mean that other WSDL processors will
! automatically recognize or understand that pattern. As with any
! other extension, it can be used among processors that <i>do</i>
! recognize and understand it.)</p>
</dd>
***************
*** 1080,1084 ****
though we have already specified which message exchange pattern the
operation will use, a message exchange pattern represents a
! template for a message sequence, and in general it may consist of
multiple input and/or output messages. Thus we must also indicate
which potential input message in the pattern this particular input
--- 1063,1067 ----
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
***************
*** 1094,1101 ****
In-Out</a> for the <a
href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">
! in-out</a> pattern. However, in theory, new patterns could be
! defined that involve multiple input messages, and the different
! input messages in the pattern would be distinguished by having
! different labels.</p>
</dd>
--- 1077,1084 ----
In-Out</a> for the <a
href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">
! in-out</a> 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 having different
! labels.</p>
</dd>
***************
*** 1146,1168 ****
<p>Now that we've defined the abstract interface for the GreatH
service, we're ready to define a binding for it.</p>
-
- <table border="1" summary="Editorial note: dbooth">
- <tr>
- <td align="left" valign="top" width="50%"><b>Editorial note:
- dbooth</b></td>
- <td align="right" valign="top" width="50%"> </td>
- </tr>
-
- <tr>
- <td colspan="2" align="left" valign="top">[This note is only
- relevant to the editors.] Hmm, I just realized that in the source
- XML for this primer, in some cases we've been using <el> to
- indicate an element name, and in other cases we've been using
- <code>. At present, the xmlspec XSLT script seems to
- translate them both into <code> elements in the generated
- HTML, but we should probably make them consistent, in case that
- changes.</td>
- </tr>
- </table>
</div>
</div>
--- 1129,1132 ----
***************
*** 1193,1199 ****
<p>In order to accommodate new kinds of message formats and
transmission protocols, bindings are defined using extensions to
! the WSDL 2.0 language, via WSDL 2.0's open content model. WSDL 2.0
! Part 3 defines binding constructs for SOAP 1.2 [<cite><a
! href="#SOAP12-PART1">SOAP 1.2 Part 1: Messaging
Framework</a></cite>] and HTTP 1.1 [<cite><a href="#RFC2616">IETF
RFC 2616</a></cite>] as predefined extensions, so that SOAP 1.2 or
--- 1157,1164 ----
<p>In order to accommodate new kinds of message formats and
transmission protocols, bindings are defined using extensions to
! the WSDL 2.0 language, via WSDL 2.0's open content model. (See <a
! href="#adv-extensibility"><b>5.1 Extensibility</b></a> for more on
! extensibility.) WSDL 2.0 Part 3 defines binding constructs for SOAP
! 1.2 [<cite><a href="#SOAP12-PART1">SOAP 1.2 Part 1: Messaging
Framework</a></cite>] and HTTP 1.1 [<cite><a href="#RFC2616">IETF
RFC 2616</a></cite>] as predefined extensions, so that SOAP 1.2 or
***************
*** 1316,1320 ****
the <code>tns:</code> prefix, but in <a
href="#adv-import-and-authoring"><b>5.3 Import mechanism and
! authoring style</b></a>we will see how WSDL 2.0's import mechanism
can be used to combine components that are defined in different
WSDL target namespaces.</p>
--- 1281,1285 ----
the <code>tns:</code> prefix, but in <a
href="#adv-import-and-authoring"><b>5.3 Import mechanism and
! authoring style</b></a> we will see how WSDL 2.0's import mechanism
can be used to combine components that are defined in different
WSDL target namespaces.</p>
***************
*** 1325,1329 ****
<dd>
! <p>This specifies the type of concrete message format to use, in
this case SOAP 1.2.</p>
</dd>
--- 1290,1294 ----
<dd>
! <p>This specifies what kind of concrete message format to use, in
this case SOAP 1.2.</p>
</dd>
***************
*** 1342,1346 ****
<dd>
! <p>This not defining a new operation. Rather, it is referencing the
previously defined <code>opCheckAvailability</code> operation in
order to specify binding details for it. This element can be
--- 1307,1311 ----
<dd>
! <p>This not defining a new operation; rather, it is referencing the
previously defined <code>opCheckAvailability</code> operation in
order to specify binding details for it. This element can be
***************
*** 1369,1374 ****
<dd>
! <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>
--- 1334,1339 ----
<dd>
! <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>
***************
*** 1380,1384 ****
<p>This attribute is also specific to WSDL 2.0's SOAP binding. This
specifies the SOAP 1.2 fault code that will cause this fault
! message to be sent. If desired, an list of subcodes can also be
specified using the optional <code>wsoap:subcodes</code>
attribute.</p>
--- 1345,1349 ----
<p>This attribute is also specific to WSDL 2.0's SOAP binding. This
specifies the SOAP 1.2 fault code that will cause this fault
! message to be sent. If desired, a list of subcodes can also be
specified using the optional <code>wsoap:subcodes</code>
attribute.</p>
***************
*** 1399,1409 ****
the service will support, and a list of <em>endpoint</em> locations
where that service can be accessed. Each endpoint must also
! reference a previously defined binding in order to indicate the
! binding details that are to be used at that endpoint. A service is
! only permitted to have one interface. (However, WSDL 2.0 does not
! prohibit one from declaring multiple services that use different
! interfaces but happen to use the same endpoint address. See <a
href="#adv-multiple-docs-describing-same-service"><b>5.4 Multiple
! Interfaces for the Same Service</b></a>.)</p>
<p>Here is a definition for our GreatH service.</p>
--- 1364,1373 ----
the service will support, and a list of <em>endpoint</em> 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 <a
href="#adv-multiple-docs-describing-same-service"><b>5.4 Multiple
! Interfaces for the Same Service</b></a> for further discussion of
! this limitation.)</p>
<p>Here is a definition for our GreatH service.</p>
***************
*** 1465,1472 ****
<p>This defines a name for this service, which must be unique among
service names in the WSDL target namespace. The name attribute is
! required in order to facilitate the use of URIs to indentify
! components in WSDL 2.0 documents. (See <em>WSDL 2.0 Core
! Language</em> [<cite><a href="#WSDL-PART1">WSDL 2.0 Core
! Language</a></cite>] appendix C <a
href="http://www.w3.org/TR/2004/WD-wsdl20-20040803/#wsdl-uri-references">
URI References for WSDL constructs</a>.)</p>
--- 1429,1436 ----
<p>This defines a name for this service, which must be unique among
service names in the WSDL target namespace. The name attribute is
! required. It allows URIs to be created that indentify components in
! WSDL 2.0 description. (See <em>WSDL 2.0 Core Language</em>
! [<cite><a href="#WSDL-PART1">WSDL 2.0 Core Language</a></cite>]
! appendix C <a
href="http://www.w3.org/TR/2004/WD-wsdl20-20040803/#wsdl-uri-references">
URI References for WSDL constructs</a>.)</p>
***************
*** 1527,1535 ****
<p>The <code>documentation</code> element allows the WSDL author to
include some human-readable documentation inside a WSDL document.
! It is a convenient place to reference any additional 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 (as can be
! seen in the syntax summary presented later), though in this example
! we have only demonstrated its use at the beginning.</p>
<div class="exampleOuter">
--- 1491,1500 ----
<p>The <code>documentation</code> element allows the WSDL author to
include some human-readable documentation inside a WSDL 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 <a href="#wsdl-infoset-diagram"><b>3.1 WSDL 2.0 Infoset Model
! Overview</b></a>), though in this example we have only demonstrated
! its use at the beginning.</p>
<div class="exampleOuter">
***************
*** 1592,1611 ****
<div class="div1">
<h2><a id="wsdl-xml-representation"
! name="wsdl-xml-representation"></a>3. WSDL 2.0 XML
! Representation</h2>
! <p>In the core language specification, WSDL 2.0 constructs are
! defined as a set of abstract components, along with a mapping to an
! XML infoset representation for these components. For easier
! consumption, the primer uses the XML representation of WSDL
! components.</p>
<div class="div2">
<h3><a id="wsdl-infoset-diagram"
! name="wsdl-infoset-diagram"></a>3.1 WSDL2.0 Infoset Model
Overview</h3>
! <p>The following diagram gives an overview of a WSDL2.0 XML
! Infoset.</p>
<div class="figure" style="text-align: center"><br />
--- 1557,1605 ----
<div class="div1">
<h2><a id="wsdl-xml-representation"
! name="wsdl-xml-representation"></a>3. WSDL 2.0 XML Infoset and
! Component Model</h2>
! <p>In conventional computer science theory, a language consists of
! a (possibly infinite) set of sentences, and each sentence is a
! string of literal symbols or characters. The language specification
! must therefore define two things: the set of permissible sentences,
! and 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 <em>XML
! Infoset</em> [<cite><a href="#XMLInfoSet">XML Information
! Set</a></cite>]. Specifically, a <em>WSDL 2.0 document</em>
! 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 can be created from more than one physical
! document, a WSDL 2.0 document does not necessarily correspond to a
! single physical 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.</p>
!
! <p>Unfortunately, the terms "element information item" and
! "attribute information item" are rather lengthy. 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>
<div class="div2">
<h3><a id="wsdl-infoset-diagram"
! name="wsdl-infoset-diagram"></a>3.1 WSDL 2.0 Infoset Model
Overview</h3>
! <p>The following diagram gives an overview of the XML Infoset for a
! WSDL 2.0 document.</p>
<div class="figure" style="text-align: center"><br />
***************
*** 1620,1736 ****
<br />
<br />
-
-
- <p>A WSDL Infoset contains representations for a collection of WSDL
- components which share a common target namespace. Note that WSDL
- definitions may be represented by one or more WSDL Infosets, that
- is one or more <code>description</code> elements which all share a
- common target namespace. When a WSDL Infoset contains one or more
- <code>import</code> elements, the WSDL definition corresponds to a
- collection with components drawn from multiple target
- namespaces.</p>
</div>
<div class="div2">
! <h3><a id="wsdl-xml-syntax" name="wsdl-xml-syntax"></a>3.2 WSDL2.0
! XML Syntax Summary</h3>
!
! <p>The XML syntax of the infoset model is summarized below. The
! following conventions are followed for the syntax:</p>
!
! <ul>
! <li>
! <p>The syntax appears as an XML instance, but the values indicate
! the data types instead of values.</p>
! </li>
!
! <li>
! <p>Characters are appended to elements and attributes as follows:
! "?" (0 or 1), "*" (0 or more), "+" (1 or more).</p>
! </li>
!
! <li>
! <p>Elements names ending in "..." (such as <element…/> or
! <element…>) indicate that elements/attributes irrelevant to
! the context are being omitted.</p>
! </li>
! </ul>
!
! <div class="exampleInner">
! <pre>
! <description targetNamespace="<em>xs:anyURI</em>" >
!
! <import namespace="<em>xs:anyURI</em>" location="<em>xs:anyURI</em>"?/>*
!
! <include location="<em>xs:anyURI</em>"/>*
!
! <types/>
!
! <interface name="<em>xs:NCName</em>" extends="<em>list of xs:QName</em>"? styleDefault="<em>list of xs:anyURI</em>"? >
!
! <fault name="<em>xs:NCName</em>" element="<em>xs:QName</em>"?/>*
!
! <operation name="<em>xs:NCName</em>" pattern="<em>xs:anyURI</em>" style="<em>list of xs:anyURI</em>"? safe="<em>xs:boolean</em>"? >
!
! <input messageLabel="<em>xs:NCName</em>"? element="<em>union of xs:QName, xs:Token</em>"? />*
!
! <output messageLabel="<em>xs:NCName</em>"? element="<em>union of xs:QName, xs:Token</em>"? />*
!
! <infault ref="<em>xs:QName</em>" messageLabel="<em>xs:NCName</em>"? />*
!
! <outfault ref="<em>xs:QName</em>" messageLabel="<em>xs:NCName</em>"? />*
!
! </operation>*
!
! </interface>*
!
! <binding name="<em>xs:NCName</em>" interface="<em>xs:QName</em>"? type="<em>xs:anyURI</em>" >
!
! <fault ref="<em>xs:QName</em>" />*
!
! <operation ref="<em>xs:QName</em>" >
!
! <input messageLabel="<em>xs:NCName</em>"? />*
!
! <output messageLabel="<em>xs:NCName</em>"? />*
!
! <infault ref="<em>xs:QName</em>" messageLabel="<em>xs:NCName</em>"? />*
!
! <outfault ref="<em>xs:QName</em>" messageLabel="<em>xs:NCName</em>"? />*
!
! </operation>*
!
! </binding>*
!
! <service name="<em>xs:NCName</em>" interface="<em>xs:QName</em>" >
!
! <endpoint name="<em>xs:NCName</em>" binding="<em>xs:QName</em>" address="<em>xs:anyURI</em>"? />*
!
! </service>*
!
! </description>
! </pre>
! </div>
!
! <p>In addition, <code>feature</code> and <code>property</code>
! elements are allowed inside all WSDL elements except
! <code>import</code>, <code>include</code>, and <code>types</code>.
! Also, an optional <code>documentation</code> element is allowed as
! the first child of any WSDL element as a container for human
! readable and/or machine processable documentation. The content of
! <code>documentation</code> is arbitrary characters and elements
! ("mixed" content in XML Schema).</p>
! </div>
! <div class="div2">
! <h3><a id="wsdl-element-order" name="wsdl-element-order"></a>3.3
! Order of WSDL Elements and Placement of Extensions</h3>
! <p>The order of the WSDL2.0 elmenets matters. Though the WSDL2.0
! schema doesn't require the elements be placed in any order, the
! specification (part 1 section 2.1.2) clearly states a set of
! constraints about how the children elements of the
! <code>description</code> element should be ordered. The following
! is a pseudo-content model of <code>description</code></p>
<div class="exampleInner">
--- 1614,1635 ----
<br />
<br />
</div>
<div class="div2">
! <h3><a id="wsdl-schema" name="wsdl-schema"></a>3.2 WSDL 2.0 Schema
! and Element Ordering</h3>
! <p>The WSDL 2.0 specification supplies a normative WSDL 2.0 schema
! @@ToDo: Add reference@@, defined in XML Schema, which can be used
! as an aid in validating WSDL 2.0 documents. Although the WSDL 2.0
! schema does not indicate the required ordering of elements, the
! WSDL 2.0 specification (Part 1 section 2.1.2) clearly states a set
! of constraints about how the children elements of the
! <code>description</code> element should be ordered. Thus, the order
! of the WSDL 2.0 elements matters, in spite of what the WSDL 2.0
! schema says.</p>
! <p>The following is a pseudo-content model of
! <code>description</code>.</p>
<div class="exampleInner">
***************
*** 1745,1755 ****
</div>
! <p>In other words,the children elements of the
<code>description</code> element should be ordered as follows:</p>
<ul>
<li>
! <p>An optoinal <code>documentation</code> comes first, if
! presents.</p>
</li>
--- 1644,1654 ----
</div>
! <p>In other words, the children elements of the
<code>description</code> element should be ordered as follows:</p>
<ul>
<li>
! <p>An optional <code>documentation</code> comes first, if
! present.</p>
</li>
***************
*** 1806,1809 ****
--- 1705,1771 ----
be"http://www.w3.org/2004/12/wsdl".</p>
</div>
+
+ <div class="div2">
+ <h3><a id="component-model" name="component-model"></a>3.3 WSDL 2.0
+ Component Model</h3>
+
+ <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 stipulates semantic constraints over and
+ above conformance to this XML Infoset structure. 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 <em>component model</em> 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.</p>
+
+ <p>In general, the WSDL 2.0 component model parallels the structure
+ of the required XML Infoset illustrated above. For example, the
+ <em>Description</em>, <em>Interface</em>, <em>Binding</em>,
+ <em>Service</em> and <em>Endpoint</em> <em>components</em>
+ correspond to the <code>description</code>, <code>interface</code>,
+ <code>binding</code>, <code>service</code>, and
+ <code>endpoint</code> element information items, respectively.
+ Furthermore, each of these components has <em>properties</em> whose
+ values are (usually) derived from the element and attribute
+ information item children of those element information items. For
+ example, the Service component corresponds to the
+ <code>service</code> element information item, so the Service
+ component has an {endpoints} property whose value is a set of
+ Endpoint components corresponding to the <code>endpoint</code>
+ element information item children of that <code>service</code>
+ element information item. (Whew!)</p>
+
+ <table border="1" summary="Editorial note: dbooth">
+ <tr>
+ <td align="left" valign="top" width="50%"><b>Editorial note:
+ dbooth</b></td>
+ <td align="right" valign="top" width="50%">2005-04-12</td>
+ </tr>
+
+ <tr>
+ <td colspan="2" align="left" valign="top">Should we add a graphic
+ illustrating the parallel structure of the component model and the
+ XML Infoset?</td>
+ </tr>
+ </table>
+
+ <br />
+ <br />
+ <p>The WSDL 2.0 component model is particularly helpful in defining
+ the meaning of <code>import</code> and <code>include</code>. WSDL
+ 2.0 <code>include</code> allows components from another WSDL 2.0
+ document having the same targetNamespace to be merged in with the
+ components of the current WSDL 2.0 document, and is transitive
+ (i.e., if the included document also includes a WSDL 2.0 document,
+ then those components will also be merged, and so on). WSDL 2.0
+ <code>import</code> allows components from another WSDL 2.0
+ document having a different targetNamespace to be merged in with
+ comonents of the current WSDL 2.0 document, and is not
+ transitive.</p>
+ </div>
</div>
***************
*** 1822,1826 ****
href="#XMLSchemaP1">XML Schema: Structures</a></cite>]. Support for
XML Schema [<cite><a href="#XMLSchemaP1">XML Schema:
! Structures</a></cite>] is required of all WSDL2.0 processors.
Alternatively, other type languages can be used via extension to
define messages.</p>
--- 1784,1788 ----
href="#XMLSchemaP1">XML Schema: Structures</a></cite>]. Support for
XML Schema [<cite><a href="#XMLSchemaP1">XML Schema:
! Structures</a></cite>] is required of all WSDL 2.0 processors.
Alternatively, other type languages can be used via extension to
define messages.</p>
***************
*** 2595,2599 ****
service sends out the first message in the exchange. Such Grouping
is only for the purpose of easy reference from discussions in later
! sections of this primer. WSDL2.0 defines four in-bound MEPS:</p>
<ul>
--- 2557,2561 ----
service sends out the first message in the exchange. Such Grouping
is only for the purpose of easy reference from discussions in later
! sections of this primer. WSDL 2.0 defines four in-bound MEPS:</p>
<ul>
***************
*** 2636,2640 ****
</ul>
! <p>WSDL2.0 also defines four out-bound MEPs which sort of mirror
the in-bound MEPs with reserved direction:</p>
--- 2598,2602 ----
</ul>
! <p>WSDL 2.0 also defines four out-bound MEPs which sort of mirror
the in-bound MEPs with reserved direction:</p>
***************
*** 2706,2709 ****
--- 2668,2684 ----
</tr>
</table>
+
+ <table border="1" summary="Editorial note: dbooth">
+ <tr>
+ <td align="left" valign="top" width="50%"><b>Editorial note:
+ dbooth</b></td>
+ <td align="right" valign="top" width="50%">20050401</td>
+ </tr>
+
+ <tr>
+ <td colspan="2" align="left" valign="top">ToDo: Add a section on
+ defining a new MEP. (dbooth will do this if he has time.)</td>
+ </tr>
+ </table>
</div>
</div>
***************
*** 3187,3192 ****
<p>WSDL 2.0 provides two extensibility mechanisms: an open content
model, which allows XML elements and attributes from other
! (non-wsdl) XML namespaces to be interspersed into a WSDL document;
! and <a
href="http://www.w3.org/TR/2004/WD-wsdl20-20040803#Feature">Features</a>
and <a
--- 3162,3167 ----
<p>WSDL 2.0 provides two extensibility mechanisms: an open content
model, which allows XML elements and attributes from other
! (non-WSDL 2.0) XML namespaces to be interspersed into a WSDL
! document; and <a
href="http://www.w3.org/TR/2004/WD-wsdl20-20040803#Feature">Features</a>
and <a
Received on Wednesday, 13 April 2005 04:40:51 UTC