- From: David Booth <dbooth@dev.w3.org>
- Date: Mon, 20 Dec 2004 16:55:33 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20
In directory hutz:/tmp/cvs-serv26870
Modified Files:
wsdl20-primer.xml
Log Message:
pub rules fixes
Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.26
retrieving revision 1.27
diff -C2 -d -r1.26 -r1.27
*** wsdl20-primer.xml 20 Dec 2004 08:33:34 -0000 1.26
--- wsdl20-primer.xml 20 Dec 2004 16:55:31 -0000 1.27
***************
*** 110,114 ****
at http://greath.example.com/2004/reservation-documentation.html
</documentation>
!
<types>
<xs:schema
--- 110,114 ----
at http://greath.example.com/2004/reservation-documentation.html
</documentation>
!
<types>
<xs:schema
***************
*** 167,176 ****
<endpoint name="reservationEndpoint"
binding="tns:reservationSOAPBinding"
! address ="http://greath.example.com/reservation"/>
</service>
! </description>
! ]]></eg>
</example></div2><div2 id="basics-getting-started"><head>Getting Started: Defining a WSDL Target Namespace</head><p>Before writing our WSDL 2.0 document, we need to decide on a <emph>WSDL target namespace</emph> URI for it. The WSDL target namespace is analogous to an XML Schema target namespace: interface, binding and service names that we define in our WSDL document will be associated with the WSDL target namespace, and thus will be distinguishable from similar names in a different WSDL target namespace. (This will become important if using WSDL 2.0's import or interface inheritance mechanisms.) </p><p>The value of the WSDL target namespace MUST be an absolute URI. Furthermore, it SHOULD be dereferenceable to a WSDL document that describes the Web service that the WSDL target namespace is used to describe. For example, the GreatH owners SHOULD make the WSDL document available from this URI. (And if a WSDL description is split into multiple documents, then the WSDL target namespace should reslve to a master document that includes all the WSDL documents needed for that service description.) However, there is no absolute requirement for this URI to be dereferenceable; thus a WSDL processor must not depend on it being dereferenceable. </p><p>This recommendation may sound circular, but bear in mind that the client might have obtained the WSDL document from anywhere -- not necessarily an authoritative source. But by dereferencing the WSDL target namespace URI, a user SHOULD be able to obtain an authoritative version. Since GreatH will be the owner of the service, the WSDL target namespace URI should refer to a location on the GreatH Web site or otherwise within its control.</p><p>Once we have decided on a WSDL target namespace URI, we can begin our WSDL 2.0 document as the following empty shell.</p><example id="example-empty-shell">
<head>An Initial Empty WSDL Document</head>
--- 167,175 ----
<endpoint name="reservationEndpoint"
binding="tns:reservationSOAPBinding"
! address ="http://greath.example.com/2004/reservation"/>
</service>
! </description>]]></eg>
</example></div2><div2 id="basics-getting-started"><head>Getting Started: Defining a WSDL Target Namespace</head><p>Before writing our WSDL 2.0 document, we need to decide on a <emph>WSDL target namespace</emph> URI for it. The WSDL target namespace is analogous to an XML Schema target namespace: interface, binding and service names that we define in our WSDL document will be associated with the WSDL target namespace, and thus will be distinguishable from similar names in a different WSDL target namespace. (This will become important if using WSDL 2.0's import or interface inheritance mechanisms.) </p><p>The value of the WSDL target namespace MUST be an absolute URI. Furthermore, it SHOULD be dereferenceable to a WSDL document that describes the Web service that the WSDL target namespace is used to describe. For example, the GreatH owners SHOULD make the WSDL document available from this URI. (And if a WSDL description is split into multiple documents, then the WSDL target namespace should reslve to a master document that includes all the WSDL documents needed for that service description.) However, there is no absolute requirement for this URI to be dereferenceable; thus a WSDL processor must not depend on it being dereferenceable. </p><p>This recommendation may sound circular, but bear in mind that the client might have obtained the WSDL document from anywhere -- not necessarily an authoritative source. But by dereferencing the WSDL target namespace URI, a user SHOULD be able to obtain an authoritative version. Since GreatH will be the owner of the service, the WSDL target namespace URI should refer to a location on the GreatH Web site or otherwise within its control.</p><p>Once we have decided on a WSDL target namespace URI, we can begin our WSDL 2.0 document as the following empty shell.</p><example id="example-empty-shell">
<head>An Initial Empty WSDL Document</head>
***************
*** 178,188 ****
<description
xmlns="http://www.w3.org/2004/08/wsdl"
! target namespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
. . . >
- . . .
</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.wsdl"</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. ather, 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.wsdl"</code></label><def><p>This is an actual XML namespace declaration for use in our GreatH service description. Note that this is the same URI that was specified above as the value of the <att>targetNamespace</att> attribute. This will allow us later to use the <code>tns:</code> prefix in <xspecref href="@@xml-schema#qname@@">qnames</xspecref>, to refer to the WSDL target namespace of the GreatH service. </p></def></gitem></glist></p><p> Now we can start describing the GreatH service. </p></div3></div2><div2 id="basics-types"><head>Defining Message Types</head><p>We know that the GreatH service will be sending and receiving messages, so a good starting point in describing the service is to define the message types that the service will use. We'll use XML Schema to do so, because WSDL 2.0 requiresall 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-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"
--- 177,187 ----
<description
xmlns="http://www.w3.org/2004/08/wsdl"
! targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
. . . >
+ . . .
</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.wsdl"</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. ather, 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.wsdl"</code></label><def><p>This is an actual XML namespace declaration for use in our GreatH service description. Note that this is the same URI that was specified above 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 servic is to define the message types that the service will use. We'll use XML Schema to do so, because WSDL 2.0 requires all conformant WSDL processors to support XML Schema at a minimum. However, WSDL 2.0 does not prohibit the use of some other schema definition language.</p><p>WSDL 2.0 allows message types to be defined directly within the 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-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"
***************
*** 195,199 ****
xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
. . . >
!
<types>
<xs:schema
--- 194,200 ----
xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
. . . >
!
! , , ,
!
<types>
<xs:schema
***************
*** 219,223 ****
. . .
</description>]]></eg>
! </example><div3 id="example-initial-types-explanation"><head>Explanation of Example</head><glist><gitem><label><code>xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"</code></label><def><p>We've added another namespace declaration. The <code>ghns</code> namespace prefix will allow us (later, when defining an interface) to reference the 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.xsd"</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>checkAvailability</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 <xspecref href="@@part2#in-out@@">in-out</xspecref> pattern indicates that if the client sends a message <emph>in</emph> to the service, the service will either send a reply message back <emph>out</emph> to the client (in the normal case) or it will send a fault message back to the client (in the case of an error).</p><p>For the GreatH service, we will (initially) define an interface containing a single operation, <code>opCheckAvailability</code>, using the <code>checkAvailability</code> and <code>checkAvailabilityResponse</code> message types that we defined in the <el>types</el> section. We'll use the <xspecref href="@@part2#i-out@@">in-out</xspecref> pattern for this operation, because this is the most natural way to represent a simple request-response interaction. We could have instead defined two separate operations using the <xspecref href="@@part2#in-only@@">in-only</xspecref> and <xspecref href="@@part2#out-only@@">out-only</xspecref> patterns (for example), but that would just complicate matters for the client, because we would then have to separately indicate to the client developer that the two operations should be used together as a request-response pair.</p><p>In addition to the normal input and output messages, we also need to specify the fault message that we wish to use in the event of an error. WSDL 2.0 permits fault messages to be declared within the <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><exampe 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.xsd"</code></label><def><p>We've added another namespace declaration. The <code>ghns</code> namespace prefix will allow us (later, when defining an interface) to reference the 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.xsd"</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>checkAvailability</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>
***************
*** 229,233 ****
xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
. . . >
!
<types>
<xs:schema
--- 230,235 ----
xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
. . . >
!
! . . .
<types>
<xs:schema
***************
*** 238,242 ****
<xs:element name="checkAvailability" type="tCheckAvailability"/>
. . .
!
<xs:element name="checkAvailabilityResponse" type="xs:double"/>
--- 240,244 ----
<xs:element name="checkAvailability" type="tCheckAvailability"/>
. . .
!
<xs:element name="checkAvailabilityResponse" type="xs:double"/>
***************
*** 261,267 ****
</interface>
. . .
</description>]]></eg></example><div3 id="example-initial-interface-explanation"><head>Explanation of Example</head><glist><gitem><label><code><interface name = "reservationInterface" ></code></label><def><p>Interfaces are declared directly inside the <el>description</el> element. In this example, we are declaring only one interface, but in general a WSDL document may declare more than one interface (each one for use with a different service). Thus, each interface must be given a name that is unique within the set of interfaces defined in this 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="@@part2#in-out@@">in-out</xspecref> pattern defined in <xspecref href="@@part2@@">WSDL 2.0 Part 2</xspecref>. WSDL 2.0 uses URIs to identify message exchange patterns in order to ensure that they are uambiguously identified, while also permitting future new patterns to be defined by anyone. (However, just because someone defines a new pattern and creates a URI to identify it, that does <emph>not</emph> mean that other WSDL processors will automatically recognize or understand that pattern. As with any other extension, it can be used among processors that do recognize and understand it.)</p></def></gitem><gitem><label><code><input messageLabel="In"</code></label><def><p>The <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/oroutput messages. Thus we must also indicate which potential input message in the pattern this particular input message represents. This is the purpose of the <code>messageLabel</code> attribute. Since the WSDL 2.0 <xspecref href="@@part2#in-out@@">in-out</xspecref> pattern that we've chosen to use only has one input message, it is a no-brainer in this case: we simply fill in the message label "In" that was defined in <xspecref href="@@Part2@@">WSDL 2.0 Part 2</xspecref> for the <xspecref href="@@part2#in-out@@">in-out</xspecref> pattern. However, in theory, new patterns could be defined that involve multiple input messages, and the different input messages in the pattern would be distinguished by having different labels.</p></def></gitem><gitem><label><code>element="ghns:checkAvailability" /></code></label><def><p>This specifies the message type for this input message, as defined previously in the <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 by specifying the message that will either trigger this fault or that this fault will replace, depending on the pattern. (Some patterns use a <xspecref href="@@part2#message-triggers-fault@@">message-triggers-faut rule</xspecref>; others use a <xspecref href="@@part2#fault-replaces-message@@">fault-replaces-message</xspecref> rule.) </p></def></gitem></glist><p>Now that we've defined the abstract interface for the GreatH service, we're ready to define a binding for it.</p><ednote><name>dbooth</name><edtext>[This note is only relevant to the editors.] Hmm, I just realized that in the source XML for this primer, in some cases we've been using <el> to indicate an element name, and in other cases we've been using <code>. At present, the xmlspec XSLT script seems to translate them both into <code> elements in the generated HTML, but we should probably make them consistent, in case that changes. </edtext></ednote></div3></div2>
--- 263,270 ----
</interface>
+
. . .
</description>]]></eg></example><div3 id="example-initial-interface-explanation"><head>Explanation of Example</head><glist><gitem><label><code><interface name = "reservationInterface" ></code></label><def><p>Interfaces are declared directly inside the <el>description</el> element. In this example, we are declaring only one interface, but in general a WSDL document may declare more than one interface (each one for use with a different service). Thus, each interface must be given a name that is unique within the set of interfaces defined in this 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>
***************
*** 276,282 ****
xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"
xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
!
<types>
! . . .
</types>
--- 279,286 ----
xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"
xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
! . . .
!
<types>
! . . .
</types>
***************
*** 305,311 ****
</binding>
. . .
</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="@@part2#in-out@@">in-out</xspecref>) that was specified when the <code>opCheckAvailability</code> operation was defined. </p></def></gitem><gitem><label><code><fault ref="tns:invalidDataFault"</code></label><def><p>As with a binding operation, this is not declaring a new fault. Rather, it is referencing a fault (<code>invalidDataFault</code>) that was previously defined in the <code>opCheckAvailability</code> interface, in order to specify binding details for it.</p></def></gitem><gitem><label><code>wsoap:code="soap:Sendr"/></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 previously defined binding in order to indicatethe 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" ?>
--- 309,316 ----
</binding>
+
. . .
</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" ?>
***************
*** 313,318 ****
xmlns="http://www.w3.org/2004/08/wsdl"
targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
! xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl" . . . >
!
<types>
. . .
--- 318,327 ----
xmlns="http://www.w3.org/2004/08/wsdl"
targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
! xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
! xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
! xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"
! xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
! . . .
!
<types>
. . .
***************
*** 320,328 ****
<interface name = "reservationInterface" >
! . . .
</interface>
<binding name="reservationSOAPBinding"
! interface="tns:reservationInterface" . . . >
. . .
</binding>
--- 329,338 ----
<interface name = "reservationInterface" >
! . . .
</interface>
<binding name="reservationSOAPBinding"
! interface="tns:reservationInterface"
! . . . >
. . .
</binding>
***************
*** 335,341 ****
address ="http://greath.example.com/2004/reservation"/>
! </service>
!
! </description>]]></eg>
</example><div3 id="example-initial-service-explanation"><head>Explanation of Example</head><glist><gitem><label><code><service name="reservationService"</code></label><def><p>This defines a name for this service, which must be unique among service names in the WSDL 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>
--- 345,349 ----
address ="http://greath.example.com/2004/reservation"/>
! </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>
***************
*** 350,360 ****
at http://greath.example.com/2004/reservation-documentation.html
</documentation>
!
<types>
! . . .
</types>
! . . .
!
</description>]]></eg>
</example><div3 id="example-initial-documentation-explanation"><head>Explanation of Example</head><glist><gitem><label><code><documentation></code></label><def><p> This element is optional, but a good idea to include. It can contain arbitrary mixed content. </p></def></gitem><gitem><label><code>at http://greath.example.com/2004/reservation-documentation.html</code></label><def><p>The most important thing to include is a pointer to any additional documentation that a client developer would need in order to use the service. </p></def></gitem></glist><p>This completes our presentation of the GreatH example. Let's summarize the syntax we've seen. </p></div3></div2><div2 id="basics-syntax"><head>XML Syntax Summary</head><p>In the core language specification, WSDL 2.0 constructs are defined as a set of abstract components, along with a mapping to an XML infoset representation for these components. For easier consumption, the primer uses the XML representation of WSDL components. The following onventions are followed for the syntax: </p>
--- 358,367 ----
at http://greath.example.com/2004/reservation-documentation.html
</documentation>
!
<types>
! . . .
</types>
! . . .
</description>]]></eg>
</example><div3 id="example-initial-documentation-explanation"><head>Explanation of Example</head><glist><gitem><label><code><documentation></code></label><def><p> This element is optional, but a good idea to include. It can contain arbitrary mixed content. </p></def></gitem><gitem><label><code>at http://greath.example.com/2004/reservation-documentation.html</code></label><def><p>The most important thing to include is a pointer to any additional documentation that a client developer would need in order to use the service. </p></def></gitem></glist><p>This completes our presentation of the GreatH example. Let's summarize the syntax we've seen. </p></div3></div2><div2 id="basics-syntax"><head>XML Syntax Summary</head><p>In the core language specification, WSDL 2.0 constructs are defined as a set of abstract components, along with a mapping to an XML infoset representation for these components. For easier consumption, the primer uses the XML representation of WSDL components. The following onventions are followed for the syntax: </p>
***************
*** 537,541 ****
<div3 id="more-types-schema-import">
<head>Importing XML Schema</head>
! <p>Let's examine the XML Schema <el>import</el> first. Note the schema import mechanism described here is defined in XML Schema Language with some additional restrictions. It is different from the WSDL import/include as explained in <specref ref="adv-import-and-authoring"/>. The schema components defined in the imported schema are available for reference by QName (see section @@@@ ). Note that only components defined in the schema itself and components included by it via <el>xs:include</el> are available to WSDL. Specifically, components that the schema imports via <el>xs:import</el> are NOT available to WSDL. <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>
--- 544,548 ----
<div3 id="more-types-schema-import">
<head>Importing XML Schema</head>
! <p>Let's examine the XML Schema <el>import</el> first. Note the schema import mechanism described here is defined in XML Schema Language with some additional restrictions. It is different from the WSDL import/include as explained in <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 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. <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>
***************
*** 556,560 ****
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,
--- 563,567 ----
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,
***************
*** 596,625 ****
<example id="example-schema-import">
<head>Importing Message Definitions into WSDL 2.0</head>
! <ednote><edtext>Need to update this example.</edtext></ednote><eg xml:space="preserve">
!
! <description
! targetNamespace= "http://www.greath.com/2004/05/wsdl/resSvc.wsdl"
! xmlns:ghns = "http://www.greath.com/2004/05/schemas/resSvc.xsd"
! xmlns = "http://www.w3.org/@@@@/@@/wsdl"
! xmlns:xs="http://www.w3.org/2001/XMLSchema">
!
! <documentation>
! Description: The definition of the reservation Web service of GreatH hotel.
! Author: Joe Somebody
! Date: 05/17/2004
! </documentation>
! <<b>types</b>>
! <documentation>
! Messages definitions of the reservation Web service of GreatH hotel.
! </documentation>
! <xs:import namespace="http://www.greath.com/2004/05/schemas/resSvc.xsd"
! schemaLocation= "http://www.greath.com/2004/05/schemas/resSvc.xsd"/>
!
! </<b>types</b>>
! </description>
! </eg>
</example>
--- 603,626 ----
<example id="example-schema-import">
<head>Importing Message Definitions into WSDL 2.0</head>
! <example><head>Importing Message Definitions</head><eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
! <description
! xmlns="http://www.w3.org/2004/08/wsdl"
! targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
! xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
! xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
! . . . >
! . . .
! <types>
! <documentation>
! Messages definitions of the reservation Web service of GreatH hotel.
! </documentation>
! <xs:import namespace="http://greath.example.com/2004/schemas/resSvc.xsd"
! schemaLocation= "http://greath.example.com/2004/schemas/resSvc.xsd"/>
! </types>
! . . .
! </description>]]></eg></example>
</example>
***************
*** 629,633 ****
<!-- ************************interface*************************** -->
! <p>We previously mentioned that a WSDL 2.0 <el>interface</el> is basically a set of <el>operation</el>s. However, there are some additional capabilities that we have not yet covered. First, let's review the syntax for <el>interface</el>.</p><div2 id="more-interfaces-interfaces">
<head>Interface Syntax </head>
<ednote><name>dbooth</name><edtext>To do: Simplify this syntax summary.</edtext></ednote><p>Below is the XML syntax summary of the <el>interface</el> element:</p>
--- 630,634 ----
<!-- ************************interface*************************** -->
! <p>We previously mentioned that a WSDL 2.0 <el>interface</el> is basically a set of <el>operation</el>s. However, there are some additional capabilities that we have not yet covered. First, let's review the syntax for <el>interface</el>. </p><div2 id="more-interfaces-interfaces">
<head>Interface Syntax </head>
<ednote><name>dbooth</name><edtext>To do: Simplify this syntax summary.</edtext></ednote><p>Below is the XML syntax summary of the <el>interface</el> element:</p>
***************
*** 722,726 ****
<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">
--- 723,727 ----
<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">
***************
*** 729,735 ****
<description
! targetNamespace= "http://www.greath.com/2004/05/wsdl/resSvc.wsdl"
! xmlns:ghns = "http://www.greath.com/2004/05/schemas/resSvc.xsd"
! xmlns = "http://www.w3.org/@@@@/@@/wsdl"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
--- 730,736 ----
<description
! targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
! xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
! xmlns = "http://www.w3.org/2004/08/wsdl"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
***************
*** 742,747 ****
<types>
! <xs:import namespace="http://www.greath.com/2004/05/schemas/resSvc.xsd"
! schemaLocation= "http://www.greath.com/2004/05/schemas/resSvc.xsd"/>
</types>
--- 743,748 ----
<types>
! <xs:import namespace="http://greath.example.com/2004/schemas/resSvc.xsd"
! schemaLocation= "http://greath.example.com/2004/schemas/resSvc.xsd"/>
</types>
***************
*** 775,779 ****
<date>20040520</date>
<edtext>
! Need clarification - fault must be name uniquely across interfaces?
</edtext>
</ednote>
--- 776,780 ----
<date>20040520</date>
<edtext>
! Need clarification - fault must be named uniquely across interfaces?
</edtext>
</ednote>
***************
*** 818,824 ****
<eg xml:space="preserve">
<description
! targetNamespace= "http://www.greath.com/2004/05/wsdl/resSvc.wsdl"
! xmlns:ghns = "http://www.greath.com/2004/05/schemas/resSvc.xsd"
! xmlns = "http://www.w3.org/@@@@/@@/wsdl"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
--- 819,825 ----
<eg xml:space="preserve">
<description
! targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
! xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
! xmlns = "http://www.w3.org/2004/08/wsdl"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
***************
*** 831,836 ****
<types>
! <xs:import namespace="http://www.greath.com/2004/05/schemas/resSvc.xsd"
! schemaLocation= "http://www.greath.com/2004/05/schemas/resSvc.xsd"/>
</types>
--- 832,837 ----
<types>
! <xs:import namespace="http://greath.example.com/2004/schemas/resSvc.xsd"
! schemaLocation= "http://greath.example.com/2004/schemas/resSvc.xsd"/>
</types>
***************
*** 971,975 ****
listing each operation of the interface and
defining bindings for them. Thus, it is an error for a binding to not define bindings for all the operations of the corresponding interface.</p>
! <p>The binding constructs can be grouped into two categories: those in the WSDL namespace of "http://www.w3.org/@@@@/@@/wsdl" and those not in WSDL namespace. WSDL 2.0 part 1 defines a set of binding constructs within the WSDL namespace that can be used to host binding detail definitions. Constructs for defining binding details are defined within their own namespaces which must be different from the WSDL namespace. ll these binding detail constructs are defined outside WSDL namespace, and are typically used as extensions of the hosting WSDL binding constructs. In the following sections, we will introduce the hosting WSDL binding constructs first, and then move on the the binding extensions.
</p><div2 id="more-bindings-wsdl">
<head>Binding Constructs in WSDL Namespace</head>
--- 972,976 ----
listing each operation of the interface and
defining bindings for them. Thus, it is an error for a binding to not define bindings for all the operations of the corresponding interface.</p>
! <p>The binding constructs can be grouped into two categories: those in the WSDL namespace of "http://www.w3.org/2004/08/wsdl" and those not in WSDL namespace. WSDL 2.0 part 1 defines a set of binding constructs within the WSDL namespace that can be used to host binding detail definitions. Constructs for defining binding details are defined within their own namespaces which must be different from the WSDL namespace. ll these binding detail constructs are defined outside WSDL namespace, and are typically used as extensions of the hosting WSDL binding constructs. In the following sections, we will introduce the hosting WSDL binding constructs first, and then move on the the binding extensions.
</p><div2 id="more-bindings-wsdl">
<head>Binding Constructs in WSDL Namespace</head>
***************
*** 1040,1044 ****
<date>20040527</date>
<edtext>
! Need clarification - wording about qname uniqueness in part 1 section 2.10.1 and 2.11.1 need to change. it's not correct to say "A particular
operation of an interface is uniquely identified by the WSDL target namespace of the interface and the name of the operation within that interface"
</edtext>
--- 1041,1045 ----
<date>20040527</date>
<edtext>
! Need clarification - wording about QName uniqueness in part 1 section 2.10.1 and 2.11.1 need to change. it's not correct to say "A particular
operation of an interface is uniquely identified by the WSDL target namespace of the interface and the name of the operation within that interface"
</edtext>
***************
*** 1054,1060 ****
<description
! targetNamespace= "http://www.greath.com/2004/05/wsdl/resSvc.wsdl"
! xmlns:ghns = "http://www.greath.com/2004/05/schemas/resSvc.xsd"
! xmlns = "http://www.w3.org/@@@@/@@/wsdl"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
--- 1055,1061 ----
<description
! targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
! xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
! xmlns = "http://www.w3.org/2004/08/wsdl"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
***************
*** 1069,1075 ****
<eg xml:space="preserve">
<description
! targetNamespace= "http://www.greath.com/2004/05/wsdl/resSvc.wsdl"
! xmlns:ghns = "http://www.greath.com/2004/05/schemas/resSvc.xsd"
! xmlns = "http://www.w3.org/@@@@/@@/wsdl"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
--- 1070,1076 ----
<eg xml:space="preserve">
<description
! targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
! xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
! xmlns = "http://www.w3.org/2004/08/wsdl"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
***************
*** 1219,1227 ****
<div1 id="References">
<head>References</head>
! <p>@@ Update reference to RDF mapping @@</p><p>@@ Delete self-reference to primer @@</p><ednote>
! <name>KevinL</name>
! <date>20040626</date>
! <edtext>copied from part 1 spec as place holder, needs cleanup</edtext>
! </ednote>
<div2 id="Normative-References">
<head>Normative References</head>
--- 1220,1224 ----
<div1 id="References">
<head>References</head>
! <p>@@ To do: Enable the reference to the RDF mapping when it's done. @@</p>
<div2 id="Normative-References">
<head>Normative References</head>
***************
*** 1379,1383 ****
http://www.w3.org/TR/2004/REC-webarch-20041215/ .
</bibl>
! <bibl id="wsarch" key="Web Architecture" href="http://www.w3.org/TR/2004/REC-webarch-20041215/">
<titleref>Web Services Architecture</titleref>, David Booth,
Hugo Haas,
--- 1376,1380 ----
http://www.w3.org/TR/2004/REC-webarch-20041215/ .
</bibl>
! <bibl id="wsarch" key="WS Architecture" href="http://www.w3.org/TR/2004/REC-webarch-20041215/">
<titleref>Web Services Architecture</titleref>, David Booth,
Hugo Haas,
Received on Monday, 20 December 2004 16:55:34 UTC