- From: David Booth via cvs-syncmail <cvsmail@w3.org>
- Date: Fri, 25 Feb 2005 20:05:54 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20
In directory hutz:/tmp/cvs-serv28240
Modified Files:
wsdl20-primer.xml
Log Message:
Converted <el>'s to <code>.
Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.30
retrieving revision 1.31
diff -C2 -d -r1.30 -r1.31
*** wsdl20-primer.xml 18 Feb 2005 21:37:37 -0000 1.30
--- wsdl20-primer.xml 25 Feb 2005 20:05:52 -0000 1.31
***************
*** 67,71 ****
! <p>Section 2 presents a hypothetical use case involving a hotel reservation service. It then proceeds step-by-step through the development of a simple example WSDL 2.0 document that describes this service:<ulist><item><p>The <el>types</el> element describes the kinds of messages that the service will send and receive. </p></item><item><p>The <el>interface</el> element describes <emph>what</emph> abstract functionality the Web service provides. </p></item><item><p>The <el>binding</el> element describes <emph>how</emph> to access the service. </p></item><item><p>The <el>service</el> element describes <emph>where</emph> to access the service.</p></item></ulist></p>
<p>Section 3 gives more information on defining message types.</p><p>Section 4 gives more information on interfaces.</p><p>Section 5 gives more information on bindings.</p><p>Section 6 gives more information on defining services.</p>
--- 67,71 ----
! <p>Section 2 presents a hypothetical use case involving a hotel reservation service. It then proceeds step-by-step through the development of a simple example WSDL 2.0 document that describes this service:<ulist><item><p>The <code>types</code> element describes the kinds of messages that the service will send and receive. </p></item><item><p>The <code>interface</code> element describes <emph>what</emph> abstract functionality the Web service provides. </p></item><item><p>The <code>binding</code> element describes <emph>how</emph> to access the service. </p></item><item><p>The <code>service</code> element describes <emph>where</emph> to access the service.</p></item></ulist></p>
<p>Section 3 gives more information on defining message types.</p><p>Section 4 gives more information on interfaces.</p><p>Section 5 gives more information on bindings.</p><p>Section 6 gives more information on defining services.</p>
***************
*** 183,187 ****
. . .
</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 <el>description</el> 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 <el>description</el> 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. Rathe, 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 is to deine 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 <el>types</el> element, which is a child of the <el>description</el> element. (Later we'll see how we can provide the type definitions in a separate document, using XML Schema's <el>import</el> mechanism.) The following schema defines checkAvailability, checkAvailabilityResponse and invalidDataError message types that we'll need. </p><p>In WSDL 2.0, all normal and fault message types must be defined as single <emph>elements</emph> at the topmost level (though of course each element may have any amount of substructure inside it). Thus, a message type must not directly consist of a sequence of elements or other complex type. </p><example id="example-iitial-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"
--- 183,187 ----
. . .
</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"
***************
*** 220,224 ****
. . .
</description>]]></eg>
! </example><div3 id="example-initial-types-explanation"><head>Explanation of Example</head><glist><gitem><label><code>xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc"</code></label><def><p>We've added another namespace declaration. The <code>ghns</code> namespace prefix will allow us (later, when defining an interface) to reference the XML Schema target namespace that we define for our message types. Thus, the URI we specify must be the same as the URI that we define as the target namespace of our XML Schema types (below) -- <emph>not</emph> the target namespace of the WSDL document itself.</p></def></gitem><gitem><label><code>targetNamespace="http://greath.example.com/2004/schemas/resSvc"</code></label><def><p>This is the XML Schema target namespace that we've created for use by the GreatH reservation service. The <code>checkAvailability</code>, <code>checkAvailabilityResponse</code> and <code>invalidDataError</code> element names will be associated with this XML Schema target namespae.</p></def></gitem><gitem><label><code>checkAvailability</code>, <code>checkAvailabilityResponse</code> and <code>invalidDataError</code></label><def><p>These are the message types that we'll use. Note that these are defined to be XML <emph>elements</emph>, as explained above.</p></def></gitem></glist><p>Although we have defined several types, we have not yet indicated which ones are to be used as message types for a Web service. We'll do that in the next section. </p></div3></div2><div2 id="basics-interface"><head>Defining an Interface</head><p>WSDL 2.0 enables one to separate the description of a Web service's abstract functionality from the concrete details of how and where that functionality is offered. This separation facilitates different levels of reusability and distribution of work in the lifecycle of a Web service and the WSDL document that describes it. </p><p>A WSDL 2.0 <el>interface</el> defines the abstract interface of a Web service as a set of abstract <emph>operations</emph>, each opration representing a simple interaction between the client and the service. Each operation specifies the types of messages that the service can send or receive as part of that operation. Each operation also specifies a message exchange <emph>pattern</emph> that indicates the sequence in which the associated messages are to be transmitted between the parties. For example, the <emph>in-out</emph> pattern (see <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSDL-PART2"/> section 2.2.3 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">In-Out</xspecref>) indicates that if the client sends a message <emph>in</emph> to the service, the service will either send a reply message back <emph>out</emph> to the client (in the normal case) or it will send a fault message back to the client (in the case of an error).</p><p>For the GreatH service, we will (initially) define an interface containing a single operation, <code>opCheckAvailability</code>, using the <code>checkAvailaility</code> and <code>checkAvailabilityResponse</code> message types that we defined in the <el>types</el> section. We'll use the <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref> pattern for this operation, because this is the most natural way to represent a simple request-response interaction. We could have instead (for example) defined two separate operations using the <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-only</xspecref> and <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#out-only">out-only</xspecref> patterns (see <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSDL-PART2"/> section 2.2.1 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-only">In-Only</xspecref> and section 2.2.5 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#out-only">Out-Only</xspecref>), but that would just complicate matters for the client, becausewe would then have to separately indicate to the client developer that the two operations should be used together as a request-response pair.</p><p>In addition to the normal input and output messages, we also need to specify the fault message that we wish to use in the event of an error. WSDL 2.0 permits fault messages to be declared within the <el>interface</el> element in order to facilitate reuse of faults across operations. If a fault occurs, it terminates whatever message sequence was indicated by the message exchange pattern of the operation. </p><p>Let's add these to our WSDL document.</p><example id="example-initial-interface">
<head>GreatH Interface Definition</head>
--- 220,224 ----
. . .
</description>]]></eg>
! </example><div3 id="example-initial-types-explanation"><head>Explanation of Example</head><glist><gitem><label><code>xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc"</code></label><def><p>We've added another namespace declaration. The <code>ghns</code> namespace prefix will allow us (later, when defining an interface) to reference the XML Schema target namespace that we define for our message types. Thus, the URI we specify must be the same as the URI that we define as the target namespace of our XML Schema types (below) -- <emph>not</emph> the target namespace of the WSDL document itself.</p></def></gitem><gitem><label><code>targetNamespace="http://greath.example.com/2004/schemas/resSvc"</code></label><def><p>This is the XML Schema target namespace that we've created for use by the GreatH reservation service. The <code>checkAvailability</code>, <code>checkAvailabilityResponse</code> and <code>invalidDataError</code> element names will be associated with this XML Schema target namespae.</p></def></gitem><gitem><label><code>checkAvailability</code>, <code>checkAvailabilityResponse</code> and <code>invalidDataError</code></label><def><p>These are the message types that we'll use. Note that these are defined to be XML <emph>elements</emph>, as explained above.</p></def></gitem></glist><p>Although we have defined several types, we have not yet indicated which ones are to be used as message types for a Web service. We'll do that in the next section. </p></div3></div2><div2 id="basics-interface"><head>Defining an Interface</head><p>WSDL 2.0 enables one to separate the description of a Web service's abstract functionality from the concrete details of how and where that functionality is offered. This separation facilitates different levels of reusability and distribution of work in the lifecycle of a Web service and the WSDL document that describes it. </p><p>A WSDL 2.0 <code>interface</code> defines the abstract interface of a Web service as a set of abstract <emph>operations</emph>, eac operation representing a simple interaction between the client and the service. Each operation specifies the types of messages that the service can send or receive as part of that operation. Each operation also specifies a message exchange <emph>pattern</emph> that indicates the sequence in which the associated messages are to be transmitted between the parties. For example, the <emph>in-out</emph> pattern (see <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSDL-PART2"/> section 2.2.3 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">In-Out</xspecref>) indicates that if the client sends a message <emph>in</emph> to the service, the service will either send a reply message back <emph>out</emph> to the client (in the normal case) or it will send a fault message back to the client (in the case of an error).</p><p>For the GreatH service, we will (initially) define an interface containing a single operation, <code>opCheckAvailability</code>, using the <code>checkAvilability</code> and <code>checkAvailabilityResponse</code> message types that we defined in the <code>types</code> section. We'll use the <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref> pattern for this operation, because this is the most natural way to represent a simple request-response interaction. We could have instead (for example) defined two separate operations using the <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-only</xspecref> and <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#out-only">out-only</xspecref> patterns (see <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSDL-PART2"/> section 2.2.1 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-only">In-Only</xspecref> and section 2.2.5 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#out-only">Out-Only</xspecref>), but that would just complicate matters for the client,because we would then have to separately indicate to the client developer that the two operations should be used together as a request-response pair.</p><p>In addition to the normal input and output messages, we also need to specify the fault message that we wish to use in the event of an error. WSDL 2.0 permits fault messages to be declared within the <code>interface</code> element in order to facilitate reuse of faults across operations. If a fault occurs, it terminates whatever message sequence was indicated by the message exchange pattern of the operation. </p><p>Let's add these to our WSDL document.</p><example id="example-initial-interface">
<head>GreatH Interface Definition</head>
***************
*** 265,273 ****
. . .
! </description>]]></eg></example><div3 id="example-initial-interface-explanation"><head>Explanation of Example</head><glist><gitem><label><code><interface name = "reservationInterface" ></code></label><def><p>Interfaces are declared directly inside the <el>description</el> element. In this example, we are declaring only one interface, but in general a WSDL document may declare more than one interface (each one for use with a different service). Thus, each interface must be given a name that is unique within the set of interfaces defined in this 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 <el>types</el> 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>This lne 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 <el>input</el> element specifies an input message. Even though we have already specified which message exchange pattern the operation will use, a message exchange pattern represents a template for a message sequence, and in general it may consist of multiple input and/o 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:checkAvailability" /></code></label><def><p>This specifies the message type for this input message, as defined previously in the <el>types</el> 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 indirectly byspecifying 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 realized that i the source XML for this primer, in some cases we've been using <el> to indicate an element name, and in other cases we've been using <code>. At present, the xmlspec XSLT script seems to translate them both into <code> elements in the generated HTML, but we should probably make them consistent, in case that changes. </edtext></ednote></div3></div2>
! <div2 id="basics-binding"><head>Defining a Binding</head><p>Although we have specified <emph>what</emph> abstract messages can be exchanged with the GreatH Web service, we have not yet specified <emph>how</emph> those messages can be exchanged. This is the purpose of a <emph>binding</emph>. A binding specifies concrete message format and transmission protocol details for an interface, and must supply such details for every operation and fault in the interface. </p><p>In the general case, binding details for each operation and fault are specified using <el>operation</el> and <el>fault</el> elements inside a <el>binding</el> element, as shown in the example below. However, in some cases it is possible to use defaulting rules to supply the information. The WSDL 2.0 SOAP binding, for example, defines some defaulting rules for operations. (See <emph>Web Services Description Language (WSDL) Version 2.0 Part 3: Bindings</emph> <bibref ref="WSDL-PART3"/>, section 2.3 <xspecref href="http://www.w3.org/TR2004/WD-wsdl20-bindings-20040803/#soap-defaults">Default Binding Rules</xspecref>.) </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" ?>
--- 265,273 ----
. . .
! </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 (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></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>
! <div2 id="basics-binding"><head>Defining a Binding</head><p>Although we have specified <emph>what</emph> abstract messages can be exchanged with the GreatH Web service, we have not yet specified <emph>how</emph> those messages can be exchanged. This is the purpose of a <emph>binding</emph>. A binding specifies concrete message format and transmission protocol details for an interface, and must supply such details for every operation and fault in the interface. </p><p>In the general case, binding details for each operation and fault are specified using <code>operation</code> and <code>fault</code> elements inside a <code>binding</code> element, as shown in the example below. However, in some cases it is possible to use defaulting rules to supply the information. The WSDL 2.0 SOAP binding, for example, defines some defaulting rules for operations. (See <emph>Web Services Description Language (WSDL) Version 2.0 Part 3: Bindings</emph> <bibref ref="WSDL-PART3"/>, section 2.3 <xspecref href="http://ww.w3.org/TR/2004/WD-wsdl20-bindings-20040803/#soap-defaults">Default Binding Rules</xspecref>.) </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" ?>
***************
*** 312,316 ****
. . .
</description>]]></eg>
! </example><div3 id="example-initial-binding-explanation"><head>Explanation of Example</head><glist><gitem><label><code>xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"</code></label><def><p>We've added two more namespace declarations. This one is the namespace for the SOAP 1.2 binding construct that is defined in WSDL 2.0 Part 3 <bibref ref="SOAP12-PART1"/>. Elements and attributes prefixed with <code>wsoap:</code> are constructs defined there. </p></def></gitem><gitem><label><code>xmlns:soap="http://www.w3.org/2003/05/soap-envelope"</code></label><def><p>This namespace is defined by the SOAP 1.2 specification itself. The SOAP 1.2 specification defines certain terms within this namespace to unambiguously identify particular concepts. Thus, we will use the <code>soap:</code> prefix when we need to refer to one of those terms.</p></def></gitem><gitem><label><code><binding name="reservationSOAPBinding"</code></label><def><p>Bindings are declared directly inside the <el>description</el> eleent. 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 mechanism canbe 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> operation in order to specify binding details for it. This element can be omitted if defaulting rules are instead used to supply the necessary information. (See the SOAP binding in <emph>WSDL 2.0 Bindings</emph> bibref ref="WSDL-PART3"/> section 2.3 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-bindings-20040803/#soap-defaults">Default Binding Rules</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></item><gitem><label><code>wsoap:code="soap:Sender"/></code></label><def><p>This attribute is also specific to WSDL 2.0's SOAP binding. This specifies the SOAP 1.2 fault code that will cause this fault message to be sent. <ednote><edtext> Need to verify that this explanation is correct. See http://lists.w3.org/Archives/Public/public-ws-desc-comments/2004Dec/0003.html </edtext></ednote> 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 <el>service</el> element. </p><p>A WSDL 2.0 <emph>service</emph> specifies a single interface that the service will support, and a list of <emph>endpoint</emph> locations where that service can be accessed. Each endpoint must also reference a reviously 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 ref="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" ?>
--- 312,316 ----
. . .
</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 mechanismcan 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> operation in order to specify binding details for it. This element can be omitted if defaulting rules are instead used to supply the necessary information. (See the SOAP binding in <emph>WSDL 2.0 Bindings</emh> <bibref ref="WSDL-PART3"/> section 2.3 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-bindings-20040803/#soap-defaults">Default Binding Rules</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></de></gitem><gitem><label><code>wsoap:code="soap:Sender"/></code></label><def><p>This attribute is also specific to WSDL 2.0's SOAP binding. This specifies the SOAP 1.2 fault code that will cause this fault message to be sent. <ednote><edtext> Need to verify that this explanation is correct. See http://lists.w3.org/Archives/Public/public-ws-desc-comments/2004Dec/0003.html </edtext></ednote> 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 refeence 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 ref="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" ?>
***************
*** 346,350 ****
</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 <el>documentation</el> 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" ?>
--- 346,350 ----
</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" ?>
***************
*** 517,521 ****
! <p>In addition, <el>feature</el> and <el>property</el> elements are allowed inside most WSDL elements. Also, an optional <el>documentation</el> element is allowed inside any WSDL element as a container for human readable and/or machine processable documentation. The content of <el>documentation</el> is arbitrary characters and elements
("mixed" content in XML Schema). </p></div3></div2></div1>
<!-- ******************MessageTypes********************************** -->
--- 517,521 ----
! <p>In addition, <code>feature</code> and <code>property</code> elements are allowed inside most WSDL elements. Also, an optional <code>documentation</code> element is allowed inside 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></div3></div2></div1>
<!-- ******************MessageTypes********************************** -->
***************
*** 525,529 ****
! <p>As we saw previously, WSDL 2.0 provides a <el>types</el> element for enclosing messages definitions in a WSDL document. There are two ways to enclose messages definitions within the <el>types</el> element: use <el>xs:import</el> mechanism provided by XML Schema, or embed the schemas within <el>xs:schema</el> elements. It's perfectly reasonable to use both ways in one WSDL. The following is a summary of the XML syntax for the <el>types</el> element:</p>
<eg xml:space="preserve"><description>
<<b>types</b>>
--- 525,529 ----
! <p>As we saw previously, WSDL 2.0 provides a <code>types</code> element for enclosing messages definitions in a WSDL document. There are two ways to enclose messages definitions within the <code>types</code> element: use <code>xs:import</code> mechanism provided by XML Schema, or embed the schemas within <code>xs:schema</code> elements. It's perfectly reasonable to use both ways in one WSDL. The following is a summary of the XML syntax for the <code>types</code> element:</p>
<eg xml:space="preserve"><description>
<<b>types</b>>
***************
*** 536,542 ****
</description>
</eg>
! <p>A WSDL description MUST NOT refer to XML Schema components in a given namespace unless an <el>xs:import</el> and/or <el>xs:schema</el> statement
! for that namespace is present. In other words, using the <el>xs:import</el> and/or
! <el>xs:schema</el> constructs is a necessary condition for making XML Schema
components available to a WSDL description. </p>
<p>The use of type system other than XML Schema is permitted by the extension elements in the above syntax. (See <emph>WSDL 2.0 Core Language</emph> <bibref ref="WSDL-PART1"/> appendix E <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-20040803/#other-schemalang">Examples of Specifications of Extension Elements for Alternative Schema Language Support</xspecref>.)
--- 536,542 ----
</description>
</eg>
! <p>A WSDL description MUST NOT refer to XML Schema components in a given namespace unless an <code>xs:import</code> and/or <code>xs:schema</code> statement
! for that namespace is present. In other words, using the <code>xs:import</code> and/or
! <code>xs:schema</code> constructs is a necessary condition for making XML Schema
components available to a WSDL description. </p>
<p>The use of type system other than XML Schema is permitted by the extension elements in the above syntax. (See <emph>WSDL 2.0 Core Language</emph> <bibref ref="WSDL-PART1"/> appendix E <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-20040803/#other-schemalang">Examples of Specifications of Extension Elements for Alternative Schema Language Support</xspecref>.)
***************
*** 544,553 ****
<div3 id="more-types-schema-import">
<head>Importing XML Schema</head>
! <p>Let's examine the XML Schema <el>import</el> first. Note the schema import mechanism described here is defined in the XML Schema language with some additional restrictions. It is different from the WSDL import/include as explained in <specref ref="adv-import-and-authoring"/>. The schema components defined in the imported schema are available for reference by QName. Note that only components defined in the schema itself and components the schema includes via <el>xs:include</el> are available to WSDL. Specifically, components that the schema imports via <el>xs:import</el> are NOT available to WSDL. <ednote><name>dbooth</name><edtext>Check this. An issue was recently raised about import not being transitive.</edtext></ednote></p>
! <p>A <el>types</el> element can contain zero or more <el>import</el>s which may have one or two attributes as follows:</p>
<ulist>
<item>
<p>A REQUIRED <att>namespace</att> attribute of type <emph>xs:anyURI</emph>.</p>
! <p>The <att>namespace</att> attribute defines the namespace of the element declarations imported from the referenced schema. As mandated in Section 3 of the Part 1 specification, the referenced schema MUST contain an XML Schema <att>targetNamespace</att> attribute on its <el>xs:schema</el> element and the values of these two attributes MUST be identical. It is an error to import a schema that does not have an XML Schema target namespace. Such schemas must first be included (using <el>xs:include</el>) in a schema that contains a <att>targetNamespace</att> attribute; on its <el>xs:schema</el> element, which can then be either imported or inlined in the WSDL document.</p>
</item>
<item>
--- 544,553 ----
<div3 id="more-types-schema-import">
<head>Importing XML Schema</head>
! <p>Let's examine the XML Schema <code>import</code> first. Note the schema import mechanism described here is defined in the XML Schema language with some additional restrictions. It is different from the WSDL import/include as explained in <specref ref="adv-import-and-authoring"/>. The schema components defined in the imported schema are available for reference by QName. Note that only components defined in the schema itself and components the schema includes via <code>xs:include</code> are available to WSDL. Specifically, components that the schema imports via <code>xs:import</code> are NOT available to WSDL. <ednote><name>dbooth</name><edtext>Check this. An issue was recently raised about import not being transitive.</edtext></ednote></p>
! <p>A <code>types</code> element can contain zero or more <code>import</code>s which may have one or two attributes as follows:</p>
<ulist>
<item>
<p>A REQUIRED <att>namespace</att> attribute of type <emph>xs:anyURI</emph>.</p>
! <p>The <att>namespace</att> attribute defines the namespace of the element declarations imported from the referenced schema. As mandated in Section 3 of the Part 1 specification, the referenced schema MUST contain an XML Schema <att>targetNamespace</att> attribute on its <code>xs:schema</code> element and the values of these two attributes MUST be identical. It is an error to import a schema that does not have an XML Schema target namespace. Such schemas must first be included (using <code>xs:include</code>) in a schema that contains a <att>targetNamespace</att> attribute; on its <code>xs:schema</code> element, which can then be either imported or inlined in the WSDL document.</p>
</item>
<item>
***************
*** 560,579 ****
<div3 id="more-types-schema-embed">
<head>Embedding XML Schema</head>
! <p>When an XML schema is embedded directly in a WSDL document, it uses the existing top-level <el>xs:schema</el> element defined by XML Schema <bibref ref="XMLSchemaP1"/> to do so. This is comparable to simply cutting and pasting an
! existing, stand-alone schema to a location inside the <el>types</el> element.</p>
<p>The schema components defined in the embedded schema are available to
WSDL for reference by QName (see @@@@). Note
that only components defined in the schema itself and components
! included by it via <el>xs:include</el> are available to WSDL. Specifically,
! components that the schema imports via <el>xs:import</el> are NOT
available to WSDL.</p>
<p> Similarly, components defined in an embedded XML schema are NOT automatically
! made available to a WSDL description that imported (using <el>wsdl:import</el>)
the description that embeds the schema (see section @@@@ for more details). For this reason, it is recommended that XML schema documents intended
! to be shared across several WSDL descriptions be placed in separate documents and imported using <el>xs:import</el>, rather than embedded inside a WSDL document.</p>
! <p>Inside an embedded XML schema, the <el>xs:import</el> and <el>xs:include</el>
elements MAY be used to refer to other XML schemas embedded in the same
WSDL description, provided that an appropriate value is specified for
! their <el>schemaLocation</el> attributes. The semantics of such elements are
governed solely by the XML Schema specification <bibref ref="XMLSchemaP1"/>.</p>
<ednote>
--- 560,579 ----
<div3 id="more-types-schema-embed">
<head>Embedding XML Schema</head>
! <p>When an XML schema is embedded directly in a WSDL document, it uses the existing top-level <code>xs:schema</code> element defined by XML Schema <bibref ref="XMLSchemaP1"/> to do so. This is comparable to simply cutting and pasting an
! existing, stand-alone schema to a location inside the <code>types</code> element.</p>
<p>The schema components defined in the embedded schema are available to
WSDL for reference by QName (see @@@@). Note
that only components defined in the schema itself and components
! included by it via <code>xs:include</code> are available to WSDL. Specifically,
! components that the schema imports via <code>xs:import</code> are NOT
available to WSDL.</p>
<p> Similarly, components defined in an embedded XML schema are NOT automatically
! made available to a WSDL description that imported (using <code>wsdl:import</code>)
the description that embeds the schema (see section @@@@ for more details). For this reason, it is recommended that XML schema documents intended
! to be shared across several WSDL descriptions be placed in separate documents and imported using <code>xs:import</code>, rather than embedded inside a WSDL document.</p>
! <p>Inside an embedded XML schema, the <code>xs:import</code> and <code>xs:include</code>
elements MAY be used to refer to other XML schemas embedded in the same
WSDL description, provided that an appropriate value is specified for
! their <code>schemaLocation</code> attributes. The semantics of such elements are
governed solely by the XML Schema specification <bibref ref="XMLSchemaP1"/>.</p>
<ednote>
***************
*** 586,601 ****
</edtext>
</ednote>
! <p>A <el>types</el> element can contain zero or more <el>schema</el> elements, which may have the following attributes:</p>
<ulist>
<item>
<p>A REQUIRED <att>targetNamespace</att> attribute of type <emph>xs:anyURI</emph>.</p>
! <p>It defines the XML Schema target namespace of the element declarations embedded in its owner <el>xs:schema</el>. Note that WSDL modifies the
! XML Schema definition of XML Schema <el>xs:schema</el> to make the <att>targetNamespace</att> attribute required. </p>
</item>
<item>
! <p>Additional OPTIONAL attributes as specified for the <el>xs:schema</el> element by the XML Schema specification.</p>
</item>
<item>
! <p>Zero or more child elements as specified for <el>xs:schema</el> by the XML Schema specification.</p>
</item>
</ulist>
--- 586,601 ----
</edtext>
</ednote>
! <p>A <code>types</code> element can contain zero or more <code>schema</code> elements, which may have the following attributes:</p>
<ulist>
<item>
<p>A REQUIRED <att>targetNamespace</att> attribute of type <emph>xs:anyURI</emph>.</p>
! <p>It defines the XML Schema target namespace of the element declarations embedded in its owner <code>xs:schema</code>. Note that WSDL modifies the
! XML Schema definition of XML Schema <code>xs:schema</code> to make the <att>targetNamespace</att> attribute required. </p>
</item>
<item>
! <p>Additional OPTIONAL attributes as specified for the <code>xs:schema</code> element by the XML Schema specification.</p>
</item>
<item>
! <p>Zero or more child elements as specified for <code>xs:schema</code> by the XML Schema specification.</p>
</item>
</ulist>
***************
*** 630,636 ****
<!-- ************************interface*************************** -->
! <p>We previously mentioned that a WSDL 2.0 interface is basically a set of operations. However, there are some additional capabilities that we have not yet covered. First, let's review the syntax for the <el>interface</el> element. </p><div2 id="more-interfaces-interfaces">
<head>Interface Syntax </head>
! <ednote><name>dbooth</name><edtext>To do: Simplify this syntax summary.</edtext></ednote><p>Below is the XML syntax summary of the <el>interface</el> element:</p>
<eg xml:space="preserve">
<description targetNamespace="<emph>xs:anyURI</emph>" >
--- 630,636 ----
<!-- ************************interface*************************** -->
! <p>We previously mentioned that a WSDL 2.0 interface is basically a set of operations. However, there are some additional capabilities that we have not yet covered. First, let's review the syntax for the <code>interface</code> element. </p><div2 id="more-interfaces-interfaces">
<head>Interface Syntax </head>
! <ednote><name>dbooth</name><edtext>To do: Simplify this syntax summary.</edtext></ednote><p>Below is the XML syntax summary of the <code>interface</code> element:</p>
<eg xml:space="preserve">
<description targetNamespace="<emph>xs:anyURI</emph>" >
***************
*** 704,712 ****
</eg>
! <p>One WSDL <el>description</el> element may contain zero or more <el>interface</el> elements as its direct children. Zero <el>interface</el> elements are permitted since a <el>description</el> element may only contain binding and/or endpoint definitions to be aggegrated into a master WSDL description via import/include mechanisms. </p>
! <p>Let's have a look at the attributes of <el>interface</el> first. It has one required <att>name</att> attribute. Within the same WSDL target namespace (which might be in different WSDL documents; see section @@@@), each interface must have a unique name. The <el>interface</el> element has two optional attributes:<att>extends</att> and <att>styleDefault</att>. <att>extends</att> will be explained in the next section. We will explain what a <att>style</att> later. For now, keep in mind that the optional <att>styleDefault</att> attribute of <el>interface</el> can be used to define a default value for the <att>style</att> attribute of all operations under this interface, if any of the operations do not specify a value for its <att>style</att>. </p>
<div3 id="more-interfaces-inheritance">
<head>Interface Inheritance</head>
! <p>The optional <att>extends</att> attribute allows an interface to extend one or more other interfaces. In such cases the interface contains the operations of the interfaces it extends, along with any operations it defines. Two things about extending interfaces deserve some attention. </p><p>First, recursive extension of interfaces is prohibited. The interfaces that a given interface extends MUST NOT themselves extend that interface either directly or indirectly. </p><p>Second, there may be cases where, due to an interface extending one or more other interfaces, operations from different interface may have a name collision. More precisely, within the same namespace, two or more interface operations end up having the same name. In such cases, WSDL 2.0 requires that the component models of those Interface Operation components MUST be equivalent (Component Equivalence is defined in Part 1 section 2.15 Equivalence of Components. For operations, basically equivalence means the two operations in quesion have same set of attributes and descendents). If the collisional operations are equivalent then they are considered to collapse into a single operation. It is an error if they have the same name in the same WSDL target namespace but are not equivalent. In other words, if two interfaces have name collisional operations, then those two interfaces cannot both form part of the derivation chain of a derived interface unless those operations are exactly the same. For the above reason, it is considered good practic to ensure that all operations within the same namespace are named uniquely whenever possible. Furthermore, since faults, features and properties can also be defined as children of the <el>interface</el> element (as descrbed later), the same name-collision resolution rules apply to those constructs.</p>
<ednote>
--- 704,712 ----
</eg>
! <p>One WSDL <code>description</code> element may contain zero or more <code>interface</code> elements as its direct children. Zero <code>interface</code> elements are permitted since a <code>description</code> element may only contain binding and/or endpoint definitions to be aggegrated into a master WSDL description via import/include mechanisms. </p>
! <p>Let's have a look at the attributes of <code>interface</code> first. It has one required <att>name</att> attribute. Within the same WSDL target namespace (which might be in different WSDL documents; see section @@@@), each interface must have a unique name. The <code>interface</code> element has two optional attributes:<att>extends</att> and <att>styleDefault</att>. <att>extends</att> will be explained in the next section. We will explain what a <att>style</att> later. For now, keep in mind that the optional <att>styleDefault</att> attribute of <code>interface</code> can be used to define a default value for the <att>style</att> attribute of all operations under this interface, if any of the operations do not specify a value for its <att>style</att>. </p>
<div3 id="more-interfaces-inheritance">
<head>Interface Inheritance</head>
! <p>The optional <att>extends</att> attribute allows an interface to extend one or more other interfaces. In such cases the interface contains the operations of the interfaces it extends, along with any operations it defines. Two things about extending interfaces deserve some attention. </p><p>First, recursive extension of interfaces is prohibited. The interfaces that a given interface extends MUST NOT themselves extend that interface either directly or indirectly. </p><p>Second, there may be cases where, due to an interface extending one or more other interfaces, operations from different interface may have a name collision. More precisely, within the same namespace, two or more interface operations end up having the same name. In such cases, WSDL 2.0 requires that the component models of those Interface Operation components MUST be equivalent (Component Equivalence is defined in Part 1 section 2.15 Equivalence of Components. For operations, basically equivalence means the two operations in quesion have same set of attributes and descendents). If the collisional operations are equivalent then they are considered to collapse into a single operation. It is an error if they have the same name in the same WSDL target namespace but are not equivalent. In other words, if two interfaces have name collisional operations, then those two interfaces cannot both form part of the derivation chain of a derived interface unless those operations are exactly the same. For the above reason, it is considered good practic to ensure that all operations within the same namespace are named uniquely whenever possible. Furthermore, since faults, features and properties can also be defined as children of the <code>interface</code> element (as descrbed later), the same name-collision resolution rules apply to those constructs.</p>
<ednote>
***************
*** 718,727 ****
</ednote>
! <p>Now let's have a look at the children of <el>interface</el>. An <el>interface</el> can contain zero or more <el>fault</el>, zero or more <el>operation</el>, zero or more <el>feature</el>, and zero or more <el>property</el>. <el>feature</el> and <el>property</el> will be examined in section @@@@. We will explain the <el>fault</el> and <el>operation</el> constructs in the following sections. </p>
</div3>
<div3 id="more-interfaces-faults">
<head>Reusable Faults</head>
! <p>The <el>fault</el> element can be used to declare faults that may occur during execution of operations of an interface. Declaring <el>fault</el>s directly under <el>interface</el> and referencing these faults in operations where they apply allow one to easily indicate that some faults can occur in multiple operations. </p>
! <p>The <el>fault</el> element has a required <att>name</att> attribute. Within a same namespace, all faults must be named uniquely. The optional <att>element</att> attribute can be used to indicate the content or playload of the fault message. Its value should be the QName of the XML schema global element declaration which defines the fault message. Please note when other type systems are used to define a fault message, additional attributes may need to be defined via WSDL's attribute extension mechanism to allow associating such a message definition with the fault.</p>
<p>Here is an example of reusing faults.</p>
<ednote><name>dbooth</name><edtext>To do: Update this example</edtext></ednote><example id="example-faults">
--- 718,727 ----
</ednote>
! <p>Now let's have a look at the children of <code>interface</code>. An <code>interface</code> can contain zero or more <code>fault</code>, zero or more <code>operation</code>, zero or more <code>feature</code>, and zero or more <code>property</code>. <code>feature</code> and <code>property</code> will be examined in section @@@@. We will explain the <code>fault</code> and <code>operation</code> constructs in the following sections. </p>
</div3>
<div3 id="more-interfaces-faults">
<head>Reusable Faults</head>
! <p>The <code>fault</code> element can be used to declare faults that may occur during execution of operations of an interface. Declaring <code>fault</code>s directly under <code>interface</code> and referencing these faults in operations where they apply allow one to easily indicate that some faults can occur in multiple operations. </p>
! <p>The <code>fault</code> element has a required <att>name</att> attribute. Within a same namespace, all faults must be named uniquely. The optional <att>element</att> attribute can be used to indicate the content or playload of the fault message. Its value should be the QName of the XML schema global element declaration which defines the fault message. Please note when other type systems are used to define a fault message, additional attributes may need to be defined via WSDL's attribute extension mechanism to allow associating such a message definition with the fault.</p>
<p>Here is an example of reusing faults.</p>
<ednote><name>dbooth</name><edtext>To do: Update this example</edtext></ednote><example id="example-faults">
***************
*** 782,799 ****
<div3 id="more-interfaces-operations">
<head>Interface Operations</head>
! <p>Now we are ready to take a close look at the <el>operation</el> element. As explained earlier, message types are defined in a type system, and the sequencing and cardinality of the messages involved in a particular interaction are governed by the message exchange pattern (MEP). The <el>operation</el> element is the glue that brings all the pieces together for an abstract interaction. </p>
! <p>WSDL 2.0 defines two required and two optional attributes for an <el>operation</el>:</p>
<ulist>
<item>
<p>A required <att>name</att> attribute</p>
! <p>Operation names must be unique within an interface. Beware that <el>operations</el>are local to an <el>interface</el>,so two <el>interface</el> elements sharing the same WSDL target namespace but with different interface names MAY contain <el>operations</el> that have the same name. Thus, <el>operations</el> cannot be referenced by QName since the <att>name</att> and WSDL target namespace are not sufficient to uniquely identify an <el>operation</el>. In order to uniquely identify an <el>operation</el>, one must first identify the <el>interface</el> by QName and then identify the <el>operation</el> within that <el>interface</el> by a further QName. As explained in section @@@, this fact has compound impact when an interface extends other interfaces. It is considered good practice to name operations uniquely within same namespace whenever possible.</p>
</item>
<item>
<p>A required <att>pattern</att> attribute</p>
! <p>it identifies the MEP a given <el>operation</el> uses. Its value must be an absolute URI.</p>
</item>
<item>
<p>An optional <att>style</att> attribute</p>
! <p>it's an absolute URI identifying the rules that were used to construct the message type definitions used by the <el>operation</el>. Note that the attribute MAY not present, but if it is present, then the rules implied by that value MUST be followed or it is an error. For example, WSDL 2.0 defines a set of rules for constructing so called RPC style messages (See section@@@@). If this attribute is set to "http://www.w3.org/2004/03/wsdl/style/rpc", then all the rules defined for the RPC style must be followed. We will have a closer look at RPC style in section@@@. </p>
<ednote>
<name>KevinL</name>
--- 782,799 ----
<div3 id="more-interfaces-operations">
<head>Interface Operations</head>
! <p>Now we are ready to take a close look at the <code>operation</code> element. As explained earlier, message types are defined in a type system, and the sequencing and cardinality of the messages involved in a particular interaction are governed by the message exchange pattern (MEP). The <code>operation</code> element is the glue that brings all the pieces together for an abstract interaction. </p>
! <p>WSDL 2.0 defines two required and two optional attributes for an <code>operation</code>:</p>
<ulist>
<item>
<p>A required <att>name</att> attribute</p>
! <p>Operation names must be unique within an interface. Beware that <code>operations</code>are local to an <code>interface</code>,so two <code>interface</code> elements sharing the same WSDL target namespace but with different interface names MAY contain <code>operations</code> that have the same name. Thus, <code>operations</code> cannot be referenced by QName since the <att>name</att> and WSDL target namespace are not sufficient to uniquely identify an <code>operation</code>. In order to uniquely identify an <code>operation</code>, one must first identify the <code>interface</code> by QName and then identify the <code>operation</code> within that <code>interface</code> by a further QName. As explained in section @@@, this fact has compound impact when an interface extends other interfaces. It is considered good practice to name operations uniquely within same namespace whenever possible.</p>
</item>
<item>
<p>A required <att>pattern</att> attribute</p>
! <p>it identifies the MEP a given <code>operation</code> uses. Its value must be an absolute URI.</p>
</item>
<item>
<p>An optional <att>style</att> attribute</p>
! <p>it's an absolute URI identifying the rules that were used to construct the message type definitions used by the <code>operation</code>. Note that the attribute MAY not present, but if it is present, then the rules implied by that value MUST be followed or it is an error. For example, WSDL 2.0 defines a set of rules for constructing so called RPC style messages (See section@@@@). If this attribute is set to "http://www.w3.org/2004/03/wsdl/style/rpc", then all the rules defined for the RPC style must be followed. We will have a closer look at RPC style in section@@@. </p>
<ednote>
<name>KevinL</name>
***************
*** 812,817 ****
</item>
</ulist>
! <p>An <el>operation</el> references a set of ordinary and fault messages it accepts or sends via zero or more <el>input</el>, <el>output</el>,<el>infault</el>, and <el>outfault</el> element. Which of these constructs to use is governed by the MEP in use. As we have seen in section@@@@, an MEP defines a set of placeholder messages that participate in the pattern and assigns them unique names within the pattern. The <el>input</el> and <el>output</el> element are used to associate an actual mesage type with that message placeholder in the MEP. Such association is done via two attributes:<att>messageLabel</att> and <att>element</att>. The <att>messageLabel</att> attribute is used to identify the role this message plays in the MEP. Its value must match the name of the MEP place holder message. Note that the <att>messageLabel</att> is optional, since it's not necessary to explicitly set the messageLabel when the MEP in use has only one message with a given direction. The <att>element</att> attribute can b used to identify the messages content (aka payload) when the content model is defined in XML Schema (see section @@@@ for using other type systems). The content model is a token with one of the values <emph>#any</emph>, <emph>#none</emph>, or <emph>#element</emph>. A value of <emph>#any</emph> indicates that the message content is any single element. A value of <emph>#none</emph> indicates there is no message content. It means that the payload will be empty. When the value is set to a QName, it indicates that the message consists of a single element described by the referenced global element declaration reference by QName. In addition, the direction implied by the <b>in</b>put, and <b>out</b>put must also match the direction of the placeholder message identified by <att>messageLabel</att>. </p>
! <p>We have already talked about how to associate a message type with a reusable interface <el>fault</el>. We have also covered the fault generation rules a MEP may use. Here under <el>operation</el>, the <el>infault</el> and <el>outfault</el> elements can be used to associate an interface <el>fault</el> with a specific message in the MEP used by an <el>operation</el>. Such association is done via a few attributes: the now familiar <att>messageLabel</att> attribute, the direction implied by the <b>in</b>fault and <b>out</b>fault, and a required <att>ref</att> attrbiute which points to the QName of an interface <el>fault</el>. When <el>infault</el> and/or <el>outfault</el> occur multiple times within an <el>operation</el>, they define alternative fault message. </p>
<ednote><name>dbooth</name><edtext>To do: Update this example. Also: which features should it illustrate?</edtext></ednote><example id="example-operations">
--- 812,817 ----
</item>
</ulist>
! <p>An <code>operation</code> references a set of ordinary and fault messages it accepts or sends via zero or more <code>input</code>, <code>output</code>,<code>infault</code>, and <code>outfault</code> element. Which of these constructs to use is governed by the MEP in use. As we have seen in section@@@@, an MEP defines a set of placeholder messages that participate in the pattern and assigns them unique names within the pattern. The <code>input</code> and <code>output</code> element are used to associate an actual mesage type with that message placeholder in the MEP. Such association is done via two attributes:<att>messageLabel</att> and <att>element</att>. The <att>messageLabel</att> attribute is used to identify the role this message plays in the MEP. Its value must match the name of the MEP place holder message. Note that the <att>messageLabel</att> is optional, since it's not necessary to explicitly set the messageLabel when the MEP in use has only one message with a given direction. The <att>eement</att> attribute can be used to identify the messages content (aka payload) when the content model is defined in XML Schema (see section @@@@ for using other type systems). The content model is a token with one of the values <emph>#any</emph>, <emph>#none</emph>, or <emph>#element</emph>. A value of <emph>#any</emph> indicates that the message content is any single element. A value of <emph>#none</emph> indicates there is no message content. It means that the payload will be empty. When the value is set to a QName, it indicates that the message consists of a single element described by the referenced global element declaration reference by QName. In addition, the direction implied by the <b>in</b>put, and <b>out</b>put must also match the direction of the placeholder message identified by <att>messageLabel</att>. </p>
! <p>We have already talked about how to associate a message type with a reusable interface <code>fault</code>. We have also covered the fault generation rules a MEP may use. Here under <code>operation</code>, the <code>infault</code> and <code>outfault</code> elements can be used to associate an interface <code>fault</code> with a specific message in the MEP used by an <code>operation</code>. Such association is done via a few attributes: the now familiar <att>messageLabel</att> attribute, the direction implied by the <b>in</b>fault and <b>out</b>fault, and a required <att>ref</att> attrbiute which points to the QName of an interface <code>fault</code>. When <code>infault</code> and/or <code>outfault</code> occur multiple times within an <code>operation</code>, they define alternative fault message. </p>
<ednote><name>dbooth</name><edtext>To do: Update this example. Also: which features should it illustrate?</edtext></ednote><example id="example-operations">
***************
*** 873,877 ****
</example>
<p>Note that in the above example, the <emph>invalidDataFault</emph> is re-used by both operations. In the <emph>makeReservation</emph> operation, two alternative outgoing faults are defined which means either a invalidDataFault or a invalidCreditCardFault may be returned as a replacement of the outgoing message.</p>
! <p>An <el>operation</el> can also contain zero or more <el>feature</el> and <el>property</el> elements. We defer the explanation for <el>feature</el> and <el>property</el> to section @@@@. </p>
</div3>
</div2>
--- 873,877 ----
</example>
<p>Note that in the above example, the <emph>invalidDataFault</emph> is re-used by both operations. In the <emph>makeReservation</emph> operation, two alternative outgoing faults are defined which means either a invalidDataFault or a invalidCreditCardFault may be returned as a replacement of the outgoing message.</p>
! <p>An <code>operation</code> can also contain zero or more <code>feature</code> and <code>property</code> elements. We defer the explanation for <code>feature</code> and <code>property</code> to section @@@@. </p>
</div3>
</div2>
***************
*** 954,969 ****
<head>More on Bindings</head>
! <p>A <el>binding</el> can be defined for different levels of reusability. It can be used to describe binding information in a re-usable manner for any
interface or specifically for a given interface. Furthermore,
binding information MAY be specified on a per-operation basis if needed.
! If a <el>binding</el> specifies any operation-specific
! binding details or any fault binding details, then it MUST specify an interface the binding information applies to, so as to indicate which interface the operations come from. </p><p>To define a reusable binding, a <el>binding</el> should omit any
operation-specific binding details and any fault binding details
! MAY omit specifying an interface. <el>bindings</el> that do not
specify an interface MAY be used to specify
operation-independent binding details for Service components
! with different interfaces. That is, such <el>bindings</el> are
reusable across one or more interfaces.</p>
! <p>A <el>binding</el> tied to a particular interface
MUST define bindings for all the operations of that
interface. The bindings may occur via defaulting rules
--- 954,969 ----
<head>More on Bindings</head>
! <p>A <code>binding</code> can be defined for different levels of reusability. It can be used to describe binding information in a re-usable manner for any
interface or specifically for a given interface. Furthermore,
binding information MAY be specified on a per-operation basis if needed.
! If a <code>binding</code> specifies any operation-specific
! binding details or any fault binding details, then it MUST specify an interface the binding information applies to, so as to indicate which interface the operations come from. </p><p>To define a reusable binding, a <code>binding</code> should omit any
operation-specific binding details and any fault binding details
! MAY omit specifying an interface. <code>bindings</code> that do not
specify an interface MAY be used to specify
operation-independent binding details for Service components
! with different interfaces. That is, such <code>bindings</code> are
reusable across one or more interfaces.</p>
! <p>A <code>binding</code> tied to a particular interface
MUST define bindings for all the operations of that
interface. The bindings may occur via defaulting rules
***************
*** 1016,1040 ****
</edtext>
</ednote>
! <ednote><name>dbooth</name><edtext>Trim some of this? Redundant?</edtext></ednote><p>One WSDL <el>description</el> element may contain zero or more <el>binding</el> elements as its direct children.</p>
! <p>The <el>binding</el> element has a required <att>name</att> attribute. Within the same WSDL target namespace , each binding must have a unique name. The optional <att>interface</att> attribute refers, by QName, to an <el>interface</el>. See the previous section for how the <att>interface</att>attribute can be used to achieve different levels of reusability of the <el>binding</el>. </p>
! <p>Careful readers may have already noticed that the <el>binding</el> syntax is to some extent symmetric with the syntax of <el>interface</el>, in other words, each interface construct has a binding counterpart. Simliar to <el>interface</el>,a <el>binding</el> element can contain zero or more <el>fault</el>, zero or more <el>operation</el>, zero or more <el>feature</el>, and zero or more <el>property</el>. Be aware that despite of the syntax similarity, they are indeed different constructs since they are in different symbol spaces and are designed for different purpose. The <el>feature</el> and <el>property</el> element will be examined in section @@@@. We will explain the binding <el>fault</el> and <el>operation</el> constructs in the following sections. </p>
<div3 id="more-bindings-faults">
<head>Binding Faults</head>
! <p>A binding <el>fault</el> describes a concrete binding of an abstract fault
within an interface to a particular concrete message format. More precisely, it describes how faults that occur within a message exchange of an operation will be formatted since the fault does not occur by itself - it occurs as part of a message
! exchange as defined by an interface <el>operation</el> and its binding
! counterpart the binding <el>operation</el>. </p>
! <p>A binding <el>fault</el> has one required <att>ref</att> attribute which is a reference, by QName, to an <el>interface</el>
! <att>fault</att>. It identifies the abstract interface <el>fault</el> for which binding information is being specified. Be aware that the value of <att>ref</att> attribute of all the <el>faults</el> under a <el>binding</el>
! MUST be unique. That is, one cannot define multiple bindings for the same interface fault within a given <el>binding</el>.</p>
</div3>
<div3 id="bindingOperations">
<head id="more-bindings-operations">Binding Operations</head>
! <p>A binding <el>operation</el> describes a concrete binding of a particular
operation of an interface to a particular concrete message format.A particular
operation of an interface is uniquely identified by the WSDL target namespace of the
! interface and the name of the operation within that interface, via the required <att>ref</att> attribute of binding <el>operation</el>. For each <el>operation</el> within a <el>binding</el>, the value of <att>ref</att> attribute MUST be unique. That is,
one cannot define multiple bindings for the same interface operation within a given
! <el>binding</el>.</p>
<ednote>
<name>KevinL</name>
--- 1016,1040 ----
</edtext>
</ednote>
! <ednote><name>dbooth</name><edtext>Trim some of this? Redundant?</edtext></ednote><p>One WSDL <code>description</code> element may contain zero or more <code>binding</code> elements as its direct children.</p>
! <p>The <code>binding</code> element has a required <att>name</att> attribute. Within the same WSDL target namespace , each binding must have a unique name. The optional <att>interface</att> attribute refers, by QName, to an <code>interface</code>. See the previous section for how the <att>interface</att>attribute can be used to achieve different levels of reusability of the <code>binding</code>. </p>
! <p>Careful readers may have already noticed that the <code>binding</code> syntax is to some extent symmetric with the syntax of <code>interface</code>, in other words, each interface construct has a binding counterpart. Simliar to <code>interface</code>,a <code>binding</code> element can contain zero or more <code>fault</code>, zero or more <code>operation</code>, zero or more <code>feature</code>, and zero or more <code>property</code>. Be aware that despite of the syntax similarity, they are indeed different constructs since they are in different symbol spaces and are designed for different purpose. The <code>feature</code> and <code>property</code> element will be examined in section @@@@. We will explain the binding <code>fault</code> and <code>operation</code> constructs in the following sections. </p>
<div3 id="more-bindings-faults">
<head>Binding Faults</head>
! <p>A binding <code>fault</code> describes a concrete binding of an abstract fault
within an interface to a particular concrete message format. More precisely, it describes how faults that occur within a message exchange of an operation will be formatted since the fault does not occur by itself - it occurs as part of a message
! exchange as defined by an interface <code>operation</code> and its binding
! counterpart the binding <code>operation</code>. </p>
! <p>A binding <code>fault</code> has one required <att>ref</att> attribute which is a reference, by QName, to an <code>interface</code>
! <att>fault</att>. It identifies the abstract interface <code>fault</code> for which binding information is being specified. Be aware that the value of <att>ref</att> attribute of all the <code>faults</code> under a <code>binding</code>
! MUST be unique. That is, one cannot define multiple bindings for the same interface fault within a given <code>binding</code>.</p>
</div3>
<div3 id="bindingOperations">
<head id="more-bindings-operations">Binding Operations</head>
! <p>A binding <code>operation</code> describes a concrete binding of a particular
operation of an interface to a particular concrete message format.A particular
operation of an interface is uniquely identified by the WSDL target namespace of the
! interface and the name of the operation within that interface, via the required <att>ref</att> attribute of binding <code>operation</code>. For each <code>operation</code> within a <code>binding</code>, the value of <att>ref</att> attribute MUST be unique. That is,
one cannot define multiple bindings for the same interface operation within a given
! <code>binding</code>.</p>
<ednote>
<name>KevinL</name>
***************
*** 1045,1049 ****
</edtext>
</ednote>
! <p>Corresponding to its interface <el>operation</el> counterpart, binding <el>operation</el> may also have zero or more <el>input</el>,<el>output</el>, <el>infault</el>, and/or <el>outfault</el>. The presence or absence of these message and/or fault reference constructs within a particular binding <el>operation</el> is governed by the interface <el>operation</el> counterpart.</p>
</div3>
</div2>
--- 1045,1049 ----
</edtext>
</ednote>
! <p>Corresponding to its interface <code>operation</code> counterpart, binding <code>operation</code> may also have zero or more <code>input</code>,<code>output</code>, <code>infault</code>, and/or <code>outfault</code>. The presence or absence of these message and/or fault reference constructs within a particular binding <code>operation</code> is governed by the interface <code>operation</code> counterpart.</p>
</div3>
</div2>
***************
*** 1084,1088 ****
<div1 id="more-service">
<head>More on Service Endpoints </head>
! <ednote><name>dbooth</name><edtext>This section now seems largely redundant. Perhaps we should reduce or eliminate it.</edtext></ednote><p>As described previously, the <el>service</el> construct specifies a set of alternate endpoints at which a service is available. Zero or more <el>services</el> can be defined within a <el>description</el> element. However, each service is limited to a single interface. The XML syntax of <el>service</el> is summarized below:</p>
<eg xml:space="preserve">
<description targetNamespace="<emph>xs:anyURI</emph>" >
--- 1084,1088 ----
<div1 id="more-service">
<head>More on Service Endpoints </head>
! <ednote><name>dbooth</name><edtext>This section now seems largely redundant. Perhaps we should reduce or eliminate it.</edtext></ednote><p>As described previously, the <code>service</code> construct specifies a set of alternate endpoints at which a service is available. Zero or more <code>services</code> can be defined within a <code>description</code> element. However, each service is limited to a single interface. The XML syntax of <code>service</code> is summarized below:</p>
<eg xml:space="preserve">
<description targetNamespace="<emph>xs:anyURI</emph>" >
***************
*** 1098,1106 ****
</description>
</eg>
! <p>A <el>service</el> has a required <att>name</att> attribute (also see section @@@@ for service reference). Each <el>service</el> within a same namespace must be named uniquely. A <el>service</el> can only implement one single interface, and it must specify the single interface it implements via the <att>interface</att> attribute. </p>
! <p>A <el>service</el> may contain one or more alternate <el>endpoints</el>. An <el>endpoint</el> defines the particulars of a specific endpoint at which a given service is available.</p>
! <p>An <el>endpoint</el> has two required attributes: <att>name</att> and <att>binding</att>. All <el>endpoints</el> within a <el>service</el> must be named uniquely via the <att>name</att> attribute. The required <att>binding</att> attribute refers to, via QName, a <el>binding</el> definition. Note that if the refered <el>binding</el> specifies a particular interface, that interface MUST be the same as the one implmented by the parent <el>service</el>. </p>
! <p>Like the WSDL binding constructs explained in section @@@@, the WSDL <el>endpoint</el> construct is also like an anchor for hosting extension elements that are used to provide information specific to a
! particular endpoint in a server. The semantics of such extensions are defined by the specification for those extensions. Such specifications are expected to annotate the WSDL <el>endpoint</el> construct with additional properties and specify the mapping between those properties and the XML representation. For example, The SOAP and HTTP binding extensions defined in WSDL 2.0 part 3 also provides extensions to be used under a service <el>endpoint</el>. </p>
</div1>
--- 1098,1106 ----
</description>
</eg>
! <p>A <code>service</code> has a required <att>name</att> attribute (also see section @@@@ for service reference). Each <code>service</code> within a same namespace must be named uniquely. A <code>service</code> can only implement one single interface, and it must specify the single interface it implements via the <att>interface</att> attribute. </p>
! <p>A <code>service</code> may contain one or more alternate <code>endpoints</code>. An <code>endpoint</code> defines the particulars of a specific endpoint at which a given service is available.</p>
! <p>An <code>endpoint</code> has two required attributes: <att>name</att> and <att>binding</att>. All <code>endpoints</code> within a <code>service</code> must be named uniquely via the <att>name</att> attribute. The required <att>binding</att> attribute refers to, via QName, a <code>binding</code> definition. Note that if the refered <code>binding</code> specifies a particular interface, that interface MUST be the same as the one implmented by the parent <code>service</code>. </p>
! <p>Like the WSDL binding constructs explained in section @@@@, the WSDL <code>endpoint</code> construct is also like an anchor for hosting extension elements that are used to provide information specific to a
! particular endpoint in a server. The semantics of such extensions are defined by the specification for those extensions. Such specifications are expected to annotate the WSDL <code>endpoint</code> construct with additional properties and specify the mapping between those properties and the XML representation. For example, The SOAP and HTTP binding extensions defined in WSDL 2.0 part 3 also provides extensions to be used under a service <code>endpoint</code>. </p>
</div1>
Received on Friday, 25 February 2005 20:05:55 UTC