- From: Kevin Liu via cvs-syncmail <cvsmail@w3.org>
- Date: Fri, 20 May 2005 02:18:20 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20
In directory hutz:/tmp/cvs-serv30450/ws/desc/wsdl20
Modified Files:
wsdl20-primer.html wsdl20-primer.xml
Log Message:
1. Incorporated JJM comments received May 03, 2005
2. Removed section 7.1.2 per minutes 5-12-2005 AI
Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.87
retrieving revision 1.88
diff -C2 -d -r1.87 -r1.88
*** wsdl20-primer.xml 11 May 2005 03:31:58 -0000 1.87
--- wsdl20-primer.xml 20 May 2005 02:18:18 -0000 1.88
***************
*** 210,214 ****
! </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 2.0document 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 resolve to a mster document that includes all the WSDL documents needed for that service description.) However, there is no absolute requirement for this URI to be dereferenceable, so a WSDL processor must not depend on it being dereferenceable. </p><p>This recommendation may sound circular, but bear in mind that the client might have obtained the WSDL document from anywhere -- not necessarily an authoritative source. But by dereferencing the WSDL target namespace URI, a user SHOULD be able to obtain an authoritative version. Since GreatH will be the owner of the service, the WSDL target namespace URI should refer to a location on the GreatH Web site or otherwise within its control.</p><p>Once we have decided on a WSDL target namespace URI, we can begin our WSDL 2.0 document as the following empty shell.</p><example id="example-empty-shell">
<head>An Initial Empty WSDL 2.0 Document</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
--- 210,214 ----
! </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 2.0 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 resolve to a aster document that includes all the WSDL documents needed for that service description.) However, there is no absolute requirement for this URI to be dereferenceable, so a WSDL processor must not depend on it being dereferenceable. </p><p>This recommendation may sound circular, but bear in mind that the client might have obtained the WSDL document from anywhere -- not necessarily an authoritative source. But by dereferencing the WSDL target namespace URI, a user should be able to obtain an authoritative version. Since GreatH will be the owner of the service, the WSDL target namespace URI should refer to a location on the GreatH Web site or otherwise within its control.</p><p>Once we have decided on a WSDL target namespace URI, we can begin our WSDL 2.0 document as the following empty shell.</p><example id="example-empty-shell">
<head>An Initial Empty WSDL 2.0 Document</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
***************
*** 221,225 ****
. . .
</description>]]></eg>
! </example><div3 id="example-empty-shell-explanation"><head>Explanation of Example</head><p><glist><gitem><label><code><description</code></label><def><p>Every WSDL 2.0 document has a <code>description</code> element as its top-most element. This merely acts as a container for the rest of the WSDL 2.0 document, and is used to declare namespaces that will be used throughout the document.</p></def></gitem><gitem><label><code>xmlns="http://www.w3.org/2005/05/wsdl"</code></label><def><p>This is the XML namespace for WSDL 2.0 itself. Because we have not defined a prefix for it, any unprefixed elements or attributes are expected to be WSDL 2.0 elements or attributes (such as the <code>description</code> element).</p></def></gitem><gitem><label><code>targetNamespace= "http://greath.example.com/2004/wsdl/resSvc"</code></label><def><p>This defines the WSDL target namespace that we have chosen for the GreatH reservation service, as described above. Note that this is not an actual XML namespace declaration Rather, it is a WSDL 2.0 attribute whose purpose is <emph>analogous</emph> to an XML Schema target namespace.</p></def></gitem><gitem><label><code>xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc"</code></label><def><p>This is an actual XML namespace declaration for use in our GreatH service description. Note that this is the same URI that was specified above as the value of the <att>targetNamespace</att> attribute. This will allow us later to use the <code>tns:</code> prefix in QNames, to refer to the WSDL target namespace of the GreatH service. (For more on QNames see <bibref ref="XMLNS"/> section 3 <xspecref href="http://www.w3.org/TR/1999/REC-xml-names-19990114/#ns-qualnames">Qualified Names</xspecref>.)</p></def></gitem></glist></p><p> Now we can start describing the GreatH service. </p></div3></div2><div2 id="basics-types"><head>Defining Message Types</head><p>We know that the GreatH service will be sending and receiving messages, so a good starting point in describing the service s to define the message types that the service will use. We'll use XML Schema to do so, because WSDL 2.0 WSDL processors are likely to support XML Schema at a minimum. However, WSDL 2.0 does not prohibit the use of some other schema definition language.</p><p>WSDL 2.0 allows message types to be defined directly within the WSDL document, inside the <code>types</code> element, which is a child of the <code>description</code> element. (Later we'll see how we can provide the type definitions in a separate document, using XML Schema's <code>import</code> mechanism.) The following schema defines checkAvailability, checkAvailabilityResponse and invalidDataError message types that we'll need. </p><p>In WSDL 2.0, all normal and fault message types must be defined as single <emph>elements</emph> at the topmost level (though of course each element may have any amount of substructure inside it). Thus, a message type must not directly consist of a sequence of elements or other complex type. </p><example id="exmple-initial-types">
<head>GreatH Message Types</head>
<eg><![CDATA[
--- 221,225 ----
. . .
</description>]]></eg>
! </example><div3 id="example-empty-shell-explanation"><head>Explanation of Example</head><p><glist><gitem><label><code><description</code></label><def><p>Every WSDL 2.0 document has a <code>description</code> element as its top-most element. This merely acts as a container for the rest of the WSDL 2.0 document, and is used to declare namespaces that will be used throughout the document.</p></def></gitem><gitem><label><code>xmlns="http://www.w3.org/2005/05/wsdl"</code></label><def><p>This is the XML namespace for WSDL 2.0 itself. Because we have not defined a prefix for it, any unprefixed elements or attributes are expected to be WSDL 2.0 elements or attributes (such as the <code>description</code> element).</p></def></gitem><gitem><label><code>targetNamespace= "http://greath.example.com/2004/wsdl/resSvc"</code></label><def><p>This defines the WSDL target namespace that we have chosen for the GreatH reservation service, as described above. Note that this is not an actual XML namespace declaration Rather, it is a WSDL 2.0 attribute whose purpose is <emph>analogous</emph> to an XML Schema target namespace.</p></def></gitem><gitem><label><code>xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc"</code></label><def><p>This is an actual XML namespace declaration for use in our GreatH service description. Note that this is the same URI that was specified above as the value of the <att>targetNamespace</att> attribute. This will allow us later to use the <code>tns:</code> prefix in QNames, to refer to the WSDL target namespace of the GreatH service. (For more on QNames see <bibref ref="XMLNS"/> section 3 <xspecref href="http://www.w3.org/TR/1999/REC-xml-names-19990114/#ns-qualnames">Qualified Names</xspecref>.)</p></def></gitem></glist></p><p> Now we can start describing the GreatH service. </p></div3></div2><div2 id="basics-types"><head>Defining Message Types</head><p>We know that the GreatH service will be sending and receiving messages, so a good starting point in describing the service s to define the message types that the service will use. We'll use XML Schema to do so, because WSDL 2.0 WSDL processors are likely to support XML Schema at a minimum. However, WSDL 2.0 does not prohibit the use of some other schema definition language.</p><p>WSDL 2.0 allows message types to be defined directly within the WSDL document, inside the <code>types</code> element, which is a child of the <code>description</code> element. (Later we'll see how we can provide the type definitions in a separate document, using XML Schema's <code>import</code> mechanism.) The following schema defines <code>checkAvailability</code>, <code>checkAvailabilityResponse</code> and <code>invalidDataError</code> message types that we'll need. </p><p>In WSDL 2.0, all normal and fault message types must be defined as single <emph>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 oher complex type. </p><example id="example-initial-types">
<head>GreatH Message Types</head>
<eg><![CDATA[
***************
*** 299,303 ****
</code></label><def><p>The <code>name</code> attribute defines a name for this fault. The name is required so that when an operation is defined, it can reference the desired fault by name. Fault names must be unique within an interface.</p></def></gitem><gitem><label><code>element = "ghns:invalidDataError"/></code></label><def><p>The <code>element</code> attribute specifies the schema type of the fault message, as previously defined in the <code>types</code> section. </p></def></gitem><gitem><label><code><operation name="opCheckAvailability"</code></label><def><p>The <code>name</code> attribute defines a name for this operation, so that it can be referenced later when bindings are defined. Operation names must also be unique within an interface. (WSDL 2.0 uses separate symbol spaces for operation and fault names, so operation name "foo" is distinct from fault name "foo".)</p></def></gitem>
! <gitem><label><code>pattern="http://www.w3.org/2005/05/wsdl/in-out" </code></label><def><p>This line specifies that this operation will use the <xspecref href="&w3c-designation-part2;#in-out">in-out</xspecref> pattern as described above. WSDL 2.0 uses URIs to identify message exchange patterns in order to ensure that the identifiers are globally unambiguous, while also permitting future new patterns to be defined by anyone. (However, just because someone defines a new pattern and creates a URI to identify it, that does <emph>not</emph> mean that other WSDL processors will automatically recognize or understand that pattern. As with any other extension, it can be used among processors that <emph>do</emph> recognize and understand it.)</p></def></gitem>
<gitem><label><code>style="http://www.w3.org/2005/05/wsdl/style/uri" </code></label><def><p>
--- 299,303 ----
</code></label><def><p>The <code>name</code> attribute defines a name for this fault. The name is required so that when an operation is defined, it can reference the desired fault by name. Fault names must be unique within an interface.</p></def></gitem><gitem><label><code>element = "ghns:invalidDataError"/></code></label><def><p>The <code>element</code> attribute specifies the schema type of the fault message, as previously defined in the <code>types</code> section. </p></def></gitem><gitem><label><code><operation name="opCheckAvailability"</code></label><def><p>The <code>name</code> attribute defines a name for this operation, so that it can be referenced later when bindings are defined. Operation names must also be unique within an interface. (WSDL 2.0 uses separate symbol spaces for operation and fault names, so operation name "foo" is distinct from fault name "foo".)</p></def></gitem>
! <gitem><label><code>pattern="http://www.w3.org/2005/05/wsdl/in-out" </code></label><def><p>This line specifies that this operation will use the <xspecref href="&w3c-designation-part2;#in-out">in-out</xspecref> pattern as described above. WSDL 2.0 uses URIs to identify message exchange patterns in order to ensure that the identifiers are globally unambiguous, while also permitting future new patterns to be defined by anyone. (However, just because someone defines a new pattern and creates a URI to identify it, that does <emph>not</emph> mean that other WSDL processors will automatically recognize or understand that pattern. As with any other extension, it can only be used among processors that <emph>do</emph> recognize and understand it.)</p></def></gitem>
<gitem><label><code>style="http://www.w3.org/2005/05/wsdl/style/uri" </code></label><def><p>
***************
*** 305,309 ****
</p></def></gitem>
! <gitem><label><code>safe="true" ></code></label><def><p>This line indicates that this operation will not obligate the client in any way, i.e., the client can safely invoke this operation without fear that it may be incurring an obligation (such as agreeing to buy something). This is further explained in <specref ref="more-interfaces-operations"/>. </p></def></gitem><gitem><label><code><input messageLabel="In"</code></label><def><p>The <code>input</code> element specifies an input message. Even though we have already specified which message exchange pattern the operation will use, a message exchange pattern represents a template for a message sequence, and in theory could consist of multiple input and/or output messages. Thus we must also indicate which potential input message in the pattern this particular input message represents. This is the purpose of the <code>messageLabel</code> attribute. Since the <xspecref href="&w3c-designation-part2;#in-out">in-out</xspecref> pattern tat we've chosen to use only has one input message, it is trivial in this case: we simply fill in the message label "In" that was defined in <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSDL-PART2"/> section 2.2.3 <xspecref href="&w3c-designation-part2;#in-out">In-Out</xspecref> for the <xspecref href="&w3c-designation-part2;#in-out">in-out</xspecref> pattern. However, if a new pattern is defined that involve multiple input messages, then the different input messages in the pattern could then be distinguished by having different labels.</p></def></gitem><gitem><label><code>element="ghns:checkAvailability" /></code></label><def><p>This specifies the message type for this input message, as defined previously in the <code>types</code> section.</p></def></gitem><gitem><label><code><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="&w3c-designation-part2;#fault-trigger">message-triggers-fault rule</xspecref>; others use a <xspecref href="&w3c-designation-part2;#fault-replacement">fault-replaces-message</xspecref> rule. See <emph>WSDL 2.0 Predefined Extensios</emph> <bibref ref="WSDL-PART2"/> section 2.1.2 <xspecref href="&w3c-designation-part2;#fault-trigger">Message Triggers Fault</xspecref> and section 2.1.1 <xspecref href="&w3c-designation-part2;#fault-replacement">Fault Replaces Message</xspecref>.) </p></def></gitem></glist><p>Now that we've defined the abstract interface for the GreatH service, we're ready to define a binding for it.</p></div3></div2>
--- 305,309 ----
</p></def></gitem>
! <gitem><label><code>safe="true" ></code></label><def><p>This line indicates that this operation will not obligate the client in any way, i.e., the client can safely invoke this operation without fear that it may be incurring an obligation (such as agreeing to buy something). This is further explained in <specref ref="more-interfaces-operations"/>. </p></def></gitem><gitem><label><code><input messageLabel="In"</code></label><def><p>The <code>input</code> element specifies an input message. Even though we have already specified which message exchange pattern the operation will use, a message exchange pattern represents a template for a message sequence, and in theory could consist of multiple input and/or output messages. Thus we must also indicate which potential input message in the pattern this particular input message represents. This is the purpose of the <code>messageLabel</code> attribute. Since the <xspecref href="&w3c-designation-part2;#in-out">in-out</xspecref> pattern tat we've chosen to use only has one input message, it is trivial in this case: we simply fill in the message label "In" that was defined in <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSDL-PART2"/> section 2.2.3 <xspecref href="&w3c-designation-part2;#in-out">In-Out</xspecref> for the <xspecref href="&w3c-designation-part2;#in-out">in-out</xspecref> pattern. However, if a new pattern is defined that involve multiple input messages, then the different input messages in the pattern could then be distinguished by using different labels.</p></def></gitem><gitem><label><code>element="ghns:checkAvailability" /></code></label><def><p>This specifies the message type for this input message, as defined previously in the <code>types</code> section.</p></def></gitem><gitem><label><code><output messageLabel="Out" . . .</code></label><def><p>This is similar to defining an input message.</p></def></gitem><gitem><label><code><outfault ref="tns:invalidDataFault" messageLabel="Out"/></code></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 <code>messageLabel</code> is used to indicate the desired point for this particular fault. It does so indirectly by specifying the message that will either trigger this fault or that this fault will replace, depending on the pattern. (Some patterns use a <xspecref href="&w3c-designation-part2;#fault-trigger">message-triggers-fault rule</xspecref>; others use a <xspecref href="&w3c-designation-part2;#fault-replacement">fault-replaces-message</xspecref> rule. See <emph>WSDL 2.0 Predefied Extensions</emph> <bibref ref="WSDL-PART2"/> section 2.1.2 <xspecref href="&w3c-designation-part2;#fault-trigger">Message Triggers Fault</xspecref> and section 2.1.1 <xspecref href="&w3c-designation-part2;#fault-replacement">Fault Replaces Message</xspecref>.) </p></def></gitem></glist><p>Now that we've defined the abstract interface for the GreatH service, we're ready to define a binding for it.</p></div3></div2>
***************
*** 397,401 ****
</example><div3 id="example-initial-binding-explanation"><head>Explanation of Example</head><glist><gitem><label><code>xmlns:wsoap= "http://www.w3.org/2005/05/wsdl/soap"</code></label><def><p>We've added two more namespace declarations. This one is the namespace for the SOAP 1.2 binding extension that is defined in WSDL 2.0 Part 3 <bibref ref="SOAP12-PART1"/>. Elements and attributes prefixed with <code>wsoap:</code> are constructs defined there. </p></def></gitem><gitem><label><code>xmlns:soap="http://www.w3.org/2003/05/soap-envelope"</code></label><def><p>This namespace is defined by the SOAP 1.2 specification itself. The SOAP 1.2 specification defines certain terms within this namespace to unambiguously identify particular concepts. Thus, we will use the <code>soap:</code> prefix when we need to refer to one of those terms.</p></def></gitem><gitem><label><code><binding name="reservationSOAPBinding"</code></label><def><p>Bindings are declared directly inside the <code>description</code> eement. The <att>name</att> attribute defines a name for this binding. Each name must be unique among all bindings in this WSDL 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/2005/05/wsdl/soap"</code></label><def><p>This specifies what kind of concrete message format to use, in this case SOAP 1.2.</p></def></gitem><gitem><label><code>wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP"</code></label><def><p>This attribute is specific to WSDL 2.0's SOAP binding extension (thus it uses the <code>wsoap:</code> prefix). It specifies the underlying transmission protocol that should be used, in this case HTTP. </p></def></gitem><gitem><label><code><operation ref="tns:opCheckAvailability"</code></label><def>
<p>
! This not defining a new operation; rather, it is referencing the
previously defined
<code>opCheckAvailability</code>
--- 397,401 ----
</example><div3 id="example-initial-binding-explanation"><head>Explanation of Example</head><glist><gitem><label><code>xmlns:wsoap= "http://www.w3.org/2005/05/wsdl/soap"</code></label><def><p>We've added two more namespace declarations. This one is the namespace for the SOAP 1.2 binding extension that is defined in WSDL 2.0 Part 3 <bibref ref="SOAP12-PART1"/>. Elements and attributes prefixed with <code>wsoap:</code> are constructs defined there. </p></def></gitem><gitem><label><code>xmlns:soap="http://www.w3.org/2003/05/soap-envelope"</code></label><def><p>This namespace is defined by the SOAP 1.2 specification itself. The SOAP 1.2 specification defines certain terms within this namespace to unambiguously identify particular concepts. Thus, we will use the <code>soap:</code> prefix when we need to refer to one of those terms.</p></def></gitem><gitem><label><code><binding name="reservationSOAPBinding"</code></label><def><p>Bindings are declared directly inside the <code>description</code> eement. The <att>name</att> attribute defines a name for this binding. Each name must be unique among all bindings in this WSDL 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/2005/05/wsdl/soap"</code></label><def><p>This specifies what kind of concrete message format to use, in this case SOAP 1.2.</p></def></gitem><gitem><label><code>wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP"</code></label><def><p>This attribute is specific to WSDL 2.0's SOAP binding extension (thus it uses the <code>wsoap:</code> prefix). It specifies the underlying transmission protocol that should be used, in this case HTTP. </p></def></gitem><gitem><label><code><operation ref="tns:opCheckAvailability"</code></label><def>
<p>
! This is not defining a new operation; rather, it is referencing the
previously defined
<code>opCheckAvailability</code>
***************
*** 609,613 ****
<ednote><name>dbooth</name><date>2005-04-13</date><edtext>ToDo: Check the sections below on import and include mechanisms for correctness. (Be sure to check the table also.) I'm not sure I got them all right.</edtext></ednote><p>There are two ways to indicate XML Schema message definitions using the <code>types</code> element. One way is to embed schema definitions within <code>xs:schema</code> elements that are children of <code>types</code>, as we have already seen. The other way is to use <code>xs:import</code> directly under <code>types</code>. It is perfectly reasonable to use both ways in one WSDL document.</p>
! <p>A WSDL <code>description</code> MUST NOT refer to XML Schema components that are neither imported nor embedded into that WSDL <code>description</code>. In other words, the use of <code>xs:import</code> and/or <code>xs:schema</code> is a necessary condition for making XML Schema components available to a WSDL Description component. </p>
<p>The following XML syntax for the <code>types</code> element illustrates the use of <code>xs:import</code> and <code>xs:schema</code>:</p>
--- 609,613 ----
<ednote><name>dbooth</name><date>2005-04-13</date><edtext>ToDo: Check the sections below on import and include mechanisms for correctness. (Be sure to check the table also.) I'm not sure I got them all right.</edtext></ednote><p>There are two ways to indicate XML Schema message definitions using the <code>types</code> element. One way is to embed schema definitions within <code>xs:schema</code> elements that are children of <code>types</code>, as we have already seen. The other way is to use <code>xs:import</code> directly under <code>types</code>. It is perfectly reasonable to use both ways in one WSDL document.</p>
! <p>A WSDL <code>description</code> must NOT refer to XML Schema components that are neither imported nor embedded into that WSDL <code>description</code>. In other words, the use of <code>xs:import</code> and/or <code>xs:schema</code> is a necessary condition for making XML Schema components available to a WSDL Description component. </p>
<p>The following XML syntax for the <code>types</code> element illustrates the use of <code>xs:import</code> and <code>xs:schema</code>:</p>
***************
*** 637,641 ****
<div2 id="more-types-schema-import">
<head>Importing XML Schema</head>
! <p> There are many cases where one would prefer importing schema definitions from separate schema files instead of embedding them directly under the <code>types</code> element. One reason is reusability of the schemas. Although WSDL 2.0 provides a <code>wsdl:import</code> mechanism, type and element declarations embedded in a WSDL 2.0 document are NOT automatically made available to the importing document, even though other WSDL 2.0 components (such as Interfaces, Bindings, etc.) do become available. Therefore, if you wish to share schema documents across several WSDL 2.0 documents, they should instead be placed in separate XML Schema documents and imported into each WSDL 2.0 document using <code>xs:import</code> directly under <code>types</code>. </p>
--- 637,641 ----
<div2 id="more-types-schema-import">
<head>Importing XML Schema</head>
! <p> There are many cases where one would prefer importing schema definitions from separate schema files instead of embedding them directly under the <code>types</code> element. One reason is reusability of the schemas. Although WSDL 2.0 provides a <code>wsdl:import</code> mechanism, type and element declarations embedded in a WSDL 2.0 document are NOT automatically made available to the importing document, even though other WSDL 2.0 components (such as Interfaces, Bindings, etc.) do become available. Therefore, if one wishes to share schema documents across several WSDL 2.0 documents, they should instead be placed in separate XML Schema documents and imported into each WSDL 2.0 document using <code>xs:import</code> directly under <code>types</code>. </p>
***************
*** 734,738 ****
<div2 id="more-interfaces-inheritance">
<head>Interface Inheritance</head>
! <p>The optional <att>extends</att> attribute allows an interface to extend or inherit from one or more other interfaces. In such cases the interface contains the operations of the interfaces it extends, along with any operations it defines directly. Two things about extending interfaces deserve some attention. </p><p>First, an inheritance loop (or infinite recursion) is prohibited: the interfaces that a given interface extends MUST NOT themselves extend that interface either directly or indirectly. </p><p>Second, we must explain what happens when operations from two different interfaces have the same target namespace and operation name. There are two cases: either the component models of the operations are the same, or they are different. If the component models are the same (per the component comparison algorithm defined in WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> "<xspecref href="&w3c-designation-part1;#compequiv">Equivalence of Components</xspecref>") then they are considered to be the same peration, i.e., they are collapsed into a single operation, and the fact that they were included more than once is not considered an error. (For operations, component equivalence basically means that the two operations have the same set of attributes and descendents.) In the second case, if two operations have the same name in the same WSDL target namespace but are not equivalent, then it is an error. For the above reason, it is considered good practice to ensure that all operations within the same target namespace are named uniquely. </p><p>Finally, since faults, features and properties can also be defined as children of the <code>interface</code> element (as described in the following sections), the same name-collision rules apply to those constructs. </p>
<p>Let's say the GreatH hotel wants to maintain a a standard message log operation for all received messages. It wants this operation to be reusable across the whole reservation system, so each service will send out, for potential use of a logging service, the content of of each message it receives together with a timestamp and the originator of the message. One way to meet such requirement is to define the log operation in an interface which can be inherited by other interfaces. Assuming a <code>messageLog</code> element is already defined in the ghns namespace with the required content, the inheritance use case is illustrated in the following example. As a result of the inheritance, the <code>reservationInterface</code> now contains two operations: <code>opCheckAvailability</code> and <code>opLogMessage</code></p>
--- 734,738 ----
<div2 id="more-interfaces-inheritance">
<head>Interface Inheritance</head>
! <p>The optional <att>extends</att> attribute allows an interface to extend or inherit from one or more other interfaces. In such cases the interface contains the operations of the interfaces it extends, along with any operations it defines directly. Two things about extending interfaces deserve some attention. </p><p>First, an inheritance loop (or infinite recursion) is prohibited: the interfaces that a given interface extends must NOT themselves extend that interface either directly or indirectly. </p><p>Second, we must explain what happens when operations from two different interfaces have the same target namespace and operation name. There are two cases: either the component models of the operations are the same, or they are different. If the component models are the same (per the component comparison algorithm defined in WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> "<xspecref href="&w3c-designation-part1;#compequiv">Equivalence of Components</xspecref>") then they are considered to be the same peration, i.e., they are collapsed into a single operation, and the fact that they were included more than once is not considered an error. (For operations, component equivalence basically means that the two operations have the same set of attributes and descendents.) In the second case, if two operations have the same name in the same WSDL target namespace but are not equivalent, then it is an error. For the above reason, it is considered good practice to ensure that all operations within the same target namespace are named uniquely. </p><p>Finally, since faults, features and properties can also be defined as children of the <code>interface</code> element (as described in the following sections), the same name-collision rules apply to those constructs. </p>
<p>Let's say the GreatH hotel wants to maintain a a standard message log operation for all received messages. It wants this operation to be reusable across the whole reservation system, so each service will send out, for potential use of a logging service, the content of of each message it receives together with a timestamp and the originator of the message. One way to meet such requirement is to define the log operation in an interface which can be inherited by other interfaces. Assuming a <code>messageLog</code> element is already defined in the ghns namespace with the required content, the inheritance use case is illustrated in the following example. As a result of the inheritance, the <code>reservationInterface</code> now contains two operations: <code>opCheckAvailability</code> and <code>opLogMessage</code></p>
***************
*** 793,797 ****
them, thereby ensuring consistency across all operations that use the faults </p>
! <p>The <code>fault</code> element has a required <att>name</att> attribute that must be unique within the WSDL document's target namespace, and permits it to be referenced from operation declarations. The optional <att>element</att> attribute can be used to indicate a schema for the content or payload of the fault message. Its value should be the QName of a global element defined in the <code>types</code> section. Please note when other type systems are used to define the schema for a fault message, additional attributes may need to be defined via WSDL's attribute extension mechanism to allow the schema to be associated with the fault.</p>
--- 793,797 ----
them, thereby ensuring consistency across all operations that use the faults </p>
! <p>The <code>fault</code> element has a required <att>name</att> attribute that must be unique within the WSDL document's target namespace, and permits it to be referenced from operation declarations. The optional <att>element</att> attribute can be used to indicate a schema for the content or payload of the fault message. Its value should be the QName of a global element defined in the <code>types</code> section. Please note that when other type systems are used to define the schema for a fault message, additional attributes may need to be defined via WSDL's attribute extension mechanism to allow the schema to be associated with the fault.</p>
***************
*** 826,833 ****
</item>
<item>
! <p>An optional <att>safety</att> attribute whose value is a boolean indicating whether the operation is asserted to be "safe" (as defined in Section 3.5 of the Web Architecture <bibref ref="webarch"/>) for clients to invoke. In essence, a safe operation is any operation that does not give the client any new obligations. For example, an operation that permits the client to check prices on products typically would not obligate the client to buy those products, and thus would be safe, whereas an operation for purchasing products would obligate the client to pay for the products that were ordered, and thus would not be safe. </p><p>An operation SHOULD be marked safe (by setting the <att>safety</att> to true) if it meets the criteria for a safe interaction defined in Section 3.5 of the Web Architecture <bibref ref="webarch"/>, because this permits the infrastructure to perform efficiency optimizations, such as pre-fetch, re-fetch and caching. </p><p>The default value of this attribute is false. If i is false or is not set, then no assertion is made about the safety of the operation; thus the operation MAY or MAY NOT be safe.</p>
</item>
</ulist></div3><div3><head>Operation Message References</head><p>An <code>operation</code> will also have <code>input</code>, <code>output</code>,<code>infault</code>, and/or <code>outfault</code> element children that specify the ordinary and fault message types to be used by that operation. The MEP specified by the <code>pattern</code> attribute determines which of these elements should be included, since each MEP has placeholders for the message types involved in its pattern. </p><p>Since operations were already discussed in <specref ref="basics-interface"/>, this section will merely comment on additional capabilities that were not previously explained.</p>
! <div4><head>The messageLabel Attribute</head><p>The <att>messageLabel</att> attribute of the <code>input</code> and <code>output</code> elements is optional: it is not necessary to explicitly set the <code>messageLabel</code> when the MEP in use is one of the eight MEPs predefined in WSDL 2.0 Part 2 <bibref ref="WSDL-PART2"/> and it has only one message with a given direction. </p></div4><div4><head>The element Attribute</head><p>The <att>element</att> attribute of the <code>input</code> and <code>output</code> elements is used to specify the message content schema (a/k/a payload schema) when the content model is defined using XML Schema. As we have seen already, it can specify the QName of an element schema that was defined in the <code>types</code> section. However, alternatively it can specify one of the following tokens: <glist><gitem><label><code>#any</code></label><def><p>The message content is any single element.</p></def></gitem><gitem><label><code>#none</code></label><def><p>There is no mesage content, i.e., the message payload is empty.</p></def></gitem></glist>The <code>element</code> attribute is also optional. If it is not specified, then @@@@. <ednote><edtext>ToDo: Say what happens if the element attribute is not specified, after issue LC99 is resolved. See http://www.w3.org/2002/ws/desc/4/lc-issues/issues.html#LC99 </edtext></ednote></p></div4><div4><head>Multiple infault or outfault Elements</head><p>When <code>infault</code> and/or <code>outfault</code> occur multiple times within an <code>operation</code>, they define alternative fault messages. </p></div4></div3>
<!-- ************************MEPs*************************** -->
--- 826,833 ----
</item>
<item>
! <p>An optional <att>safe</att> attribute whose value is a boolean indicating whether the operation is asserted to be "safe" (as defined in Section 3.5 of the Web Architecture <bibref ref="webarch"/>) for clients to invoke. In essence, a safe operation is any operation that does not give the client any new obligations. For example, an operation that permits the client to check prices on products typically would not obligate the client to buy those products, and thus would be safe, whereas an operation for purchasing products would obligate the client to pay for the products that were ordered, and thus would not be safe. </p><p>An operation should be marked safe (by setting the <att>safe</att> to true) if it meets the criteria for a safe interaction defined in Section 3.5 of the Web Architecture <bibref ref="webarch"/>, because this permits the infrastructure to perform efficiency optimizations, such as pre-fetch, re-fetch and caching. </p><p>The default value of this attribute is false. If it isfalse or is not set, then no assertion is made about the safety of the operation; thus the operation may or may NOT be safe.</p>
</item>
</ulist></div3><div3><head>Operation Message References</head><p>An <code>operation</code> will also have <code>input</code>, <code>output</code>,<code>infault</code>, and/or <code>outfault</code> element children that specify the ordinary and fault message types to be used by that operation. The MEP specified by the <code>pattern</code> attribute determines which of these elements should be included, since each MEP has placeholders for the message types involved in its pattern. </p><p>Since operations were already discussed in <specref ref="basics-interface"/>, this section will merely comment on additional capabilities that were not previously explained.</p>
! <div4><head>The messageLabel Attribute</head><p>The <att>messageLabel</att> attribute of the <code>input</code> and <code>output</code> elements is optional. It is not necessary to explicitly set the <code>messageLabel</code> when the MEP in use is one of the eight MEPs predefined in WSDL 2.0 Part 2 <bibref ref="WSDL-PART2"/> and it has only one message with a given direction. </p></div4><div4><head>The element Attribute</head><p>The <att>element</att> attribute of the <code>input</code> and <code>output</code> elements is used to specify the message content schema (a/k/a payload schema) when the content model is defined using XML Schema. As we have seen already, it can specify the QName of an element schema that was defined in the <code>types</code> section. However, alternatively it can specify one of the following tokens: <glist><gitem><label><code>#any</code></label><def><p>The message content is any single element.</p></def></gitem><gitem><label><code>#none</code></label><def><p>There is no mesage content, i.e., the message payload is empty.</p></def></gitem></glist>The <code>element</code> attribute is also optional. If it is not specified, then @@@@. <ednote><edtext>ToDo: Say what happens if the element attribute is not specified, after issue LC99 is resolved. See http://www.w3.org/2002/ws/desc/4/lc-issues/issues.html#LC99 </edtext></ednote></p></div4><div4><head>Multiple infault or outfault Elements</head><p>When <code>infault</code> and/or <code>outfault</code> occur multiple times within an <code>operation</code>, they define alternative fault messages. </p></div4></div3>
<!-- ************************MEPs*************************** -->
***************
*** 839,848 ****
from a service to one other node, a service defined by that MEP may multicast that message to
other nodes. To maximize reuse, WSDL message exchange patterns identify a minimal contract between other parties and Web Services, and contain only information that is relevant to both the Web service and the client that engages that service.</p>
! <p>A total of 8 MEPs are defined in <bibref ref="WSDL-PART2"/>. Hopefully, these MEPs will cover the most common use cases, but they are not meant to be an exhaustive list of MEPs that can ever be used by operations. More MEPs can be defined for particular application needs by interested parties. (See <specref ref="more-interfaces-defining-meps"/> )</p>
! <p>For the 8 MEPs defined by WSDL 2.0, some of them are variations of others based on how faults may be generated. For example, the In-Only pattern ("http://www.w3.org/2005/05/wsdl/in-only") consists of exactly one message received by a service from some other node. No fault maybe generated. As a variation of In-Only, Robust In-Only pattern ("http://www.w3.org/2005/05/wsdl/robust-in-only") also consists of exactly one message received by a service, but in this case faults can be triggered by the message and MUST be delivered to the originator of the message. If there is no path to this node, the fault MUST be discarded. For details about the common fault generation models used by the 8 WSDL 2.0 MEPs, see <bibref ref="WSDL-PART2"/>. </p>
! <p>Depends on how the first message in the MEP is initiated, the 8 WSDL MEPs may be grouped into two groups: in-bound MEPs in which case the service receives the first message in the exchange, and out-bound MEPs in which case the service sends out the first message in the exchange. (Such Grouping is only for the purpose of easy reference in this primer).</p>
! <p> A frequently asked question about out-bound MEPs is how a service knows where to send the message. Services using out-bound MEPs are typically part of large scale integration systems that rely on mapping and routing facilities. In such systems, out-bound MEPs are useful for abstractly specifying the functionality of a service, including its requirements for potential customers, while endpoint address information can be provided at deployment or runtime by integration infrastructure. For example, the GreatH hotel reservation system may require that every time a customer interacts with the system to check availability, data about the customer must be logged by a CRM system. At design time, it's unknown which particular CRM system would be used together with the reservation system. To address this requirement, we may change the "reservationInterface" in <specref ref="example-initial"/> to include an out-bound logInquiry operation. This logInquiry operation advertises to potential service clients tha customer data will be made available by the reservation service at run time. When the reservation service is deployed to GreatH's IT landscape, appropriate configuration time and run time infrastructure will help determine which CRM system will get the customer data and log it appropriately. It's worth noting that in addition to being used by a CRM system for customer management purpose, the same data may also be used by a system performance analysis tool for different purpose. Providing an out-bound operation in the reservation service enables loose coupling and so improves the overall GreatH IT landscape's flexibility and scalability. </p>
<example id="example-outbound-operation">
--- 839,848 ----
from a service to one other node, a service defined by that MEP may multicast that message to
other nodes. To maximize reuse, WSDL message exchange patterns identify a minimal contract between other parties and Web Services, and contain only information that is relevant to both the Web service and the client that engages that service.</p>
! <p>A total of eight MEPs are defined in <bibref ref="WSDL-PART2"/>. These MEPs should cover the most common use cases, but they are not meant to be an exhaustive list of MEPs that can ever be used by operations. More MEPs can be defined for particular application needs by interested parties. (See <specref ref="more-interfaces-defining-meps"/> )</p>
! <p>For the eight MEPs defined by WSDL 2.0, some of them are variations of others based on how faults may be generated. For example, the In-Only pattern ("http://www.w3.org/2005/05/wsdl/in-only") consists of exactly one message received by a service from some other node. No fault can be generated. As a variation of In-Only, Robust In-Only pattern ("http://www.w3.org/2005/05/wsdl/robust-in-only") also consists of exactly one message received by a service, but in this case faults can be triggered by the message and must be delivered to the originator of the message. If there is no path to this node, the fault must be discarded. For details about the common fault generation models used by the eight WSDL 2.0 MEPs, see <bibref ref="WSDL-PART2"/>. </p>
! <p>Depending on how the first message in the MEP is initiated, the eight WSDL MEPs may be grouped into two groups: in-bound MEPs, for which the service receives the first message in the exchange, and out-bound MEPs, for which the service sends out the first message in the exchange. (Such grouping is not provided in the WSDL 2.0 specification and is presented here only for the purpose of easy reference in this primer).</p>
! <p> A frequently asked question about out-bound MEPs is how a service knows where to send the message. Services using out-bound MEPs are typically part of large scale integration systems that rely on mapping and routing facilities. In such systems, out-bound MEPs are useful for specifying the functionality of a service abstractly, including its requirements for potential customers, while endpoint address information can be provided at deployment or runtime by the underlying integration infrastructure. For example, the GreatH hotel reservation system may require that every time a customer interacts with the system to check availability, data about the customer must be logged by a CRM system. At design time, it's unknown which particular CRM system would be used together with the reservation system. To address this requirement, we may change the "reservationInterface" in <specref ref="example-initial"/> to include an out-bound logInquiry operation. This <code>logInquiry</code> operation advertises to ptential service clients that customer data will be made available by the reservation service at run time. When the reservation service is deployed to GreatH's IT landscape, appropriate configuration time and run time infrastructure will help determine which CRM system will get the customer data and log it appropriately. It's worth noting that in addition to being used by a CRM system for customer management purpose, the same data may also be used by a system performance analysis tool for different purpose. Providing an out-bound operation in the reservation service enables loose coupling and so improves the overall GreatH IT landscape's flexibility and scalability. </p>
<example id="example-outbound-operation">
***************
*** 868,872 ****
</div3>
! <div3 id="more-interfaces-defining-meps"><head>Defining New Message Exchange Patterns (MEPs)</head><p>Although the 8 MEPs defined in WSDL 2.0 Part 2 <bibref ref="WSDL-PART2"/> are intended to cover most use cases, WSDL 2.0 has designed this set to be extensible. This is why MEPs are identified by URIs rather than a fixed set of tokens. Here are the general steps for defining a new MEP.<olist><item><p>Search around on the Web to see if somebody else has already defined
an MEP that is close enough to what you want. If others are already using an MEP that fits your needs, it will reduce the effort required in step 4 to get other people to adopt yours. </p></item><item><p>Write an HTML document that clearly defines the MEP, and publish it at a
stable URL -- see <loc href="http://purl.org/">purl.org</loc>, for example -- that will represent the full, formal name of the MEP, such as
--- 868,882 ----
</div3>
! <div3 id="more-interfaces-defining-meps"><head>Defining New Message Exchange Patterns (MEPs)</head><p>Although the eight MEPs defined in WSDL 2.0 Part 2 <bibref ref="WSDL-PART2"/> are intended to cover most use cases, WSDL 2.0 has designed this set to be extensible. This is why MEPs are identified by URIs rather than a fixed set of tokens. Here are the general steps for defining a new MEP.
!
! <ednote>
! <name>KevinL</name>
! <date>20050519</date>
! <edtext>
! This section is subject to change. The WG has decided to add a template for defining new MEPs in part 2, and provide an example here.
! </edtext>
! </ednote>
!
! <olist><item><p>Search around on the Web to see if somebody else has already defined
an MEP that is close enough to what you want. If others are already using an MEP that fits your needs, it will reduce the effort required in step 4 to get other people to adopt yours. </p></item><item><p>Write an HTML document that clearly defines the MEP, and publish it at a
stable URL -- see <loc href="http://purl.org/">purl.org</loc>, for example -- that will represent the full, formal name of the MEP, such as
***************
*** 927,931 ****
<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>
</div2>
<div2 id="bindingOperations">
--- 937,941 ----
<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>
</div2>
<div2 id="bindingOperations">
***************
*** 934,938 ****
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>. As with faults, for each <code>operation</code> within a <code>binding</code>, the value of the <att>ref</att> attribute MUST be unique.</p>
</div2>
--- 944,948 ----
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>. As with faults, for each <code>operation</code> within a <code>binding</code>, the value of the <att>ref</att> attribute must be unique.</p>
</div2>
***************
*** 1074,1078 ****
</example><p>
! This would instead serialize to a request URI such as: <code>http://greath.example.com/2004/bycheckInDate/5-5-5</code></p></div3></div2>
<div2 id="adv-get-vs-post"><head>HTTP GET Versus POST: Which to Use?</head>
<p> When a binding using HTTP is specified for an operation, the WSDL 2.0 author must decide which HTTP method is appropriate to use -- usually a choice between GET and POST. In the context of the Web as a whole (rather than specifically Web services), the W3C Technical Architecture Group (TAG) has addressed the question of when it is appropriate to use GET, versus when to use POST, in a finding entitled <emph>URIs, Addressability, and the use of HTTP GET and POST</emph> (<bibref ref="TAG-whenToUseGET"/>). From the abstract:</p><p><quote><emph>. . . designers should adopt [GET] for safe operations such as simple queries. POST is appropriate for other types of applications where a user request has the potential to change the state of the resource (or of related resources). The finding explains how to choose between HTTP GET and POST for an application taking into account architectural, security, and practical considerations.</emph></quote></p><p>Recall that the concept of a safe operation was disussed in <specref ref="more-interfaces-op-attr"/>. (Briefly, a safe operation is one that does not cause the invoker to incur new obligations.) Although the <code>safe</code> attribute of an interface operation indicates that the abstract operation is safe, it does not automatically cause GET to be used at the HTTP level when the binding is specified. The choice of GET or POST is determined at the binding level: </p><ulist><item><p>If the WSDL 2.0 SOAP binding extension is used (<specref ref="more-bindings-soap"/>), with HTTP as the underlying transport protocol, then GET may be specified by setting:<glist><gitem><label><code>wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP"</code></label><def><p>on the <code>binding</code> element (to indicate the use of HTTP as the underlying protocol); and</p></def></gitem><gitem><label><code>wsoap:mep="http://www.w3.org/2003/05/soap/mep/soap-response/"</code></label><def><p>on the binding <code>operation</code> element, which causes GET to be used by defalt.</p></def></gitem></glist> </p></item><item><p>If the WSDL 2.0 HTTP binding extension is used directly (<specref ref="more-bindings-http"/>), GET may be specified by setting either:<glist><gitem><label><code>whttp:methodDefault="GET"</code></label><def><p>on the <code>binding</code> element; or</p></def></gitem><gitem><label><code>whttp:method="GET"</code></label><def><p>on the binding <code>operation</code> element, which overrides <code>whttp:methodDefault</code> if set on the <code>binding</code> element.</p></def></gitem></glist></p></item></ulist>
--- 1084,1088 ----
</example><p>
! This would instead serialize to a request URI such as: <code>http://greath.example.com/2004/bycheckInDate/5-5-5</code>. The rest of the message content would go to the HTTP message body.</p></div3></div2>
<div2 id="adv-get-vs-post"><head>HTTP GET Versus POST: Which to Use?</head>
<p> When a binding using HTTP is specified for an operation, the WSDL 2.0 author must decide which HTTP method is appropriate to use -- usually a choice between GET and POST. In the context of the Web as a whole (rather than specifically Web services), the W3C Technical Architecture Group (TAG) has addressed the question of when it is appropriate to use GET, versus when to use POST, in a finding entitled <emph>URIs, Addressability, and the use of HTTP GET and POST</emph> (<bibref ref="TAG-whenToUseGET"/>). From the abstract:</p><p><quote><emph>. . . designers should adopt [GET] for safe operations such as simple queries. POST is appropriate for other types of applications where a user request has the potential to change the state of the resource (or of related resources). The finding explains how to choose between HTTP GET and POST for an application taking into account architectural, security, and practical considerations.</emph></quote></p><p>Recall that the concept of a safe operation was disussed in <specref ref="more-interfaces-op-attr"/>. (Briefly, a safe operation is one that does not cause the invoker to incur new obligations.) Although the <code>safe</code> attribute of an interface operation indicates that the abstract operation is safe, it does not automatically cause GET to be used at the HTTP level when the binding is specified. The choice of GET or POST is determined at the binding level: </p><ulist><item><p>If the WSDL 2.0 SOAP binding extension is used (<specref ref="more-bindings-soap"/>), with HTTP as the underlying transport protocol, then GET may be specified by setting:<glist><gitem><label><code>wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP"</code></label><def><p>on the <code>binding</code> element (to indicate the use of HTTP as the underlying protocol); and</p></def></gitem><gitem><label><code>wsoap:mep="http://www.w3.org/2003/05/soap/mep/soap-response/"</code></label><def><p>on the binding <code>operation</code> element, which causes GET to be used by defalt.</p></def></gitem></glist> </p></item><item><p>If the WSDL 2.0 HTTP binding extension is used directly (<specref ref="more-bindings-http"/>), GET may be specified by setting either:<glist><gitem><label><code>whttp:methodDefault="GET"</code></label><def><p>on the <code>binding</code> element; or</p></def></gitem><gitem><label><code>whttp:method="GET"</code></label><def><p>on the binding <code>operation</code> element, which overrides <code>whttp:methodDefault</code> if set on the <code>binding</code> element.</p></def></gitem></glist></p></item></ulist>
***************
*** 1090,1097 ****
<div2 id="adv-extensibility">
<head>Extensibility</head>
! <p>WSDL 2.0 provides two extensibility mechanisms: an open content model, which allows XML elements and attributes from other (non-WSDL 2.0) XML namespaces to be interspersed in a WSDL 2.0 document; and <xspecref href="&w3c-designation-part1;#Feature">Features</xspecref> and <xspecref href="&w3c-designation-part1;#Property">Properties</xspecref>. Both mechanisms use URIs to identify the semantics of the extensions. For extension XML elements and attributes, the namespace URI of the extension element or attribute acts as an unambiguous name for the semantics of that extension. For Features and Properties, the Feature or Property is named by a URI.</p><p>In either case, the URI that identifies the semantics of an extension SHOULD be dereferenceable to a document that describes the semantics of that extension. As of this writing, there is no generally accepted standard for what kind of document that should be. However, the <loc href="http://www.w3.org/2001/tag/">W3C TAG</loc> has been discussing th issue (see TAG issue <loc href="http://www.w3.org/2001/tag/issues.html?type=1#namespaceDocument-8">namespaceDocument-8</loc>) and is likely to provide guidance at some point.</p><div3 id="adv-optional-versus-required"><head>Optional Versus Required Extensions</head><p>Extensions can either be required or optional.</p><p>An <emph>optional</emph> extension is one that the client may either engage or ignore, entirely at its discretion, and is signaled by attribute <code>wsdl:required="false"</code> or the absence of the <code>wsdl:required</code> attribute (because it defaults to false). Thus, a WSDL processor, acting on behalf of the client, that encounters an unknown optional extension can safely ignore it and continue to process the WSDL 2.0 document. However, it is important to stress that optional extensions are only optional to the <emph>client</emph> -- not the service. A service MUST support all optional and required extensions that it advertises in its WSDL 2.0 document. </p><p>A <emph>required/emph> extension is one that MUST be supported and engaged by the client in order for the interaction to procede properly, and is signaled by attribute <code>wsdl:required="true"</code>. If a WSDL processor, acting on behalf of the client, encounters a required extension that it does not recognize or does not support, then it cannot safely continue to process the WSDL 2.0 document. In most practical cases, this is likely to mean that the processor will require manual intervention to deal with the extension. For example, a client developer might manually provide an implementation for the required extension to the WSDL processor. </p></div3><div3 id="adv-scope-of-wsdl-required"><head>Scoping of the wsdl:required Attribute</head><ednote><name>dbooth</name><date>2005-04-15</date><edtext>ToDo: Need to check the scoping rules to see if this is correct.</edtext></ednote><p>As a convenience mechanism, the <code>wsdl:required</code> attribute need not be specified on every extension element. If it is omitted fom an extension element, its effective value is inherited from the smallest enclosing scope that explicitly sets its value. If there is no enclosing scope that explicitly sets its value, then its value defaults to <code>false</code>. </p><p>Because portions of a Web service description can be written in different physical documents by different people, one should be cautious about setting <code>wsdl:required="false"</code> when an outer scope, written by someone else, had set <code>wsdl:required="true"</code>.</p></div3></div2><div2 id="adv-FP">
<head>Features and Properties</head>
! <p>After a few successful trials of the reservation service, GreatH decides that it is time to make the makeReservation operation secure, so that sensitive credit-card information is not being sent across the public network in a snoopable fashion. We will do this using the WSDL 2.0 Features and Properties mechanisms <bibref ref="WSDL-PART1"/>, which is modeled after the Features and Properties mechanism defined in SOAP 1.2 <bibref ref="SOAP12-PART1"/>.</p><p>To facilitate presentation, this section will assume the existence of a hypothetical security feature named "<code>http://features.example.com/2005/securityFeature</code>", which defines, in the abstract, the idea of message confidentiality. This feature has an associated property, named "<code>http://features.example.com/2005/securityFeature/securityLevel</code>", which defines various safety levels (from 0 meaning clear text, all the way through 10, involving highly complex cryptographic algorithms with keys in the tens of thousands of bits). We also assume that a SOAP module, named "<code>http://features.example.com/2005/modules/Security</code>", has been defined, which implements the security feature described above.</p><p>GreatH has chosen an abstract security feature which is standard in the fictitious hotels community, and has integrated both a SOAP module and a new secure HTTP binding into its infrastructure – both of which implement the security feature (the SOAP module does this inside the SOAP envelope using headers, and the secure binding does it at the transport layer). Now they'd like to advertise and control the usage of these extensions using WSDL 2.0.</p>
<div3 id="adv-FP-soap-modules"><head>SOAP Modules</head><p>The first step GreatH takes is to require the usage of the SOAP module in their normal SOAP/HTTP endpoint, which looks like this:</p><example id="example-fp-requiring-soap-module">
--- 1100,1121 ----
<div2 id="adv-extensibility">
<head>Extensibility</head>
! <p>WSDL 2.0 provides two extensibility mechanisms: an open content model, which allows XML elements and attributes from other (non-WSDL 2.0) XML namespaces to be interspersed in a WSDL 2.0 document; and <xspecref href="&w3c-designation-part1;#Feature">Features</xspecref> and <xspecref href="&w3c-designation-part1;#Property">Properties</xspecref>. Both mechanisms use URIs to identify the semantics of the extensions. For extension XML elements and attributes, the namespace URI of the extension element or attribute acts as an unambiguous name for the semantics of that extension. For Features and Properties, the Feature or Property is named by a URI.</p><p>In either case, the URI that identifies the semantics of an extension should be dereferenceable to a document that describes the semantics of that extension. As of this writing, there is no generally accepted standard for what kind of document that should be. However, the <loc href="http://www.w3.org/2001/tag/">W3C TAG</loc> has been discussing th issue (see TAG issue <loc href="http://www.w3.org/2001/tag/issues.html?type=1#namespaceDocument-8">namespaceDocument-8</loc>) and is likely to provide guidance at some point.</p><div3 id="adv-optional-versus-required"><head>Optional Versus Required Extensions</head><p>Extensions can either be required or optional.</p><p>An <emph>optional</emph> extension is one that the client may either engage or ignore, entirely at its discretion, and is signaled by attribute <code>wsdl:required="false"</code> or the absence of the <code>wsdl:required</code> attribute (because it defaults to false). Thus, a WSDL processor, acting on behalf of the client, that encounters an unknown optional extension can safely ignore it and continue to process the WSDL 2.0 document. However, it is important to stress that optional extensions are only optional to the <emph>client</emph> -- not the service. A service must support all optional and required extensions that it advertises in its WSDL 2.0 document. </p><p>A <emph>required/emph> extension is one that must be supported and engaged by the client in order for the interaction to procede properly, and is signaled by attribute <code>wsdl:required="true"</code>. If a WSDL processor, acting on behalf of the client, encounters a required extension that it does not recognize or does not support, then it cannot safely continue to process the WSDL 2.0 document. In most practical cases, this is likely to mean that the processor will require manual intervention to deal with the extension. For example, a client developer might manually provide an implementation for the required extension to the WSDL processor. </p></div3>
!
! <!-- removed per minutes 5-12-2005 AI div3 id="adv-scope-of-wsdl-required"><head>Scoping of the wsdl:required Attribute</head><ednote><name>dbooth</name><date>2005-04-15</date><edtext>ToDo: Need to check the scoping rules to see if this is correct.</edtext></ednote><p>As a convenience mechanism, the <code>wsdl:required</code> attribute need not be specified on every extension element. If it is omitted from an extension element, its effective value is inherited from the smallest enclosing scope that explicitly sets its value. If there is no enclosing scope that explicitly sets its value, then its value defaults to <code>false</code>. </p><p>Because portions of a Web service description can be written in different physical documents by different people, one should be cautious about setting <code>wsdl:required="false"</code> when an outer scope, written by someone else, had set <code>wsdl:required="true"</code>.</p></div3 -->
!
! </div2>
!
!
! <div2 id="adv-FP">
<head>Features and Properties</head>
! <ednote>
! <name>KevinL</name>
! <date>20050519</date>
! <edtext>
! The section is subject to change. Pending on the resolution of the minority opinions filed about Feature and Property.
! </edtext>
! </ednote>
! <p>After a few successful trials of the reservation service, GreatH decides that it is time to make the makeReservation operation secure, so that sensitive credit-card information is not being sent across the public network in a snoopable fashion. We will do this using the WSDL 2.0 Features and Properties mechanisms <bibref ref="WSDL-PART1"/>, which is modeled after the Features and Properties mechanism defined in SOAP 1.2 <bibref ref="SOAP12-PART1"/>.</p><p>To facilitate presentation, this section will assume the existence of a hypothetical security feature named "<code>http://features.example.com/2005/securityFeature</code>", which defines, in the abstract, the idea of message confidentiality. This feature has an associated property, named "<code>http://features.example.com/2005/securityFeature/securityLevel</code>", which defines various safety levels (from 0 meaning clear text, all the way through 10, involving highly complex cryptographic algorithms with keys in the tens of thousands of bits). We also assume that a SOAP module (for more about SOAP module, see <loc href="http://www.w3.org/TR/soap12-part1/#soapmodules"> SOAP1.2 spec</loc> and <specref ref="adv-FP-soap-modules"/>), named "<code>http://features.example.com/2005/modules/Security</code>", has been defined, which implements the security feature described above.</p><p>GreatH has chosen an abstract security feature which is standard in the fictitious hotels community, and has integrated both a SOAP module and a new secure HTTP binding into its infrastructure – both of which implement the security feature (the SOAP module does this inside the SOAP envelope using headers, and the secure binding does it at the transport layer). Now they'd like to advertise and control the usage of these extensions using WSDL 2.0.</p>
<div3 id="adv-FP-soap-modules"><head>SOAP Modules</head><p>The first step GreatH takes is to require the usage of the SOAP module in their normal SOAP/HTTP endpoint, which looks like this:</p><example id="example-fp-requiring-soap-module">
***************
*** 1145,1149 ****
</service>
. . .]]></eg>
! </example><p>The user will have a choice as to which of the endpoints, and therefore which binding, is to be used, but they both satisfy the abstract feature requirement specified in the interface.</p><p>Note that it is not necessary to declare the abstract feature in order to use/require the SOAP module, or in order to use/require the secure binding. Abstract feature declarations serve purely to indicate requirements which must be fulfilled by more concrete components such as modules or bindings. In other words, the abstract feature declaration allows components such as interfaces to be reused without caring exactly which SOAP modules or bindings satisfy the feature.</p></div3><div3 id="adv-fp-properties"><head>Properties</head><p>So far we've discussed how to indicate the availability or the "requiredness" of features and modules. Often it is not enough to indicate that a particular extension is available/required: you also need some way to control or parameterize aspects of its behavior. This i achieved by the use of WSDL 2.0 <emph>properties</emph>. Each feature, SOAP module, or SOAP binding may express a variety of <emph>properties</emph> in its specification. These properties are very much like variables in a programming language. If GreatH would like to indicate that the securityLevel property should be 5 for the "makeReservation" operation, it would look like this:</p><example id="example-fp-def-prop">
<head>Defining a Property</head>
<eg xml:space="preserve">
--- 1169,1173 ----
</service>
. . .]]></eg>
! </example><p>The user will have a choice as to which of the endpoints, and therefore which binding, is to be used, but they both satisfy the abstract feature requirement specified in the interface.</p><p>Note that it is not necessary to declare the abstract feature in order to use/require the SOAP module, or in order to use/require the secure binding. Abstract feature declarations serve purely to indicate requirements which must be fulfilled by more concrete components such as modules or bindings. In other words, the abstract feature declaration allows components such as interfaces to be reused without caring exactly which SOAP modules or bindings satisfy the feature.</p></div3><div3 id="adv-fp-properties"><head>Properties</head><p>So far we've discussed how to indicate the availability or the "requiredness" of features and modules. Often it is not enough to indicate that a particular extension is available/required: you also need some way to control or parameterize aspects of its behavior. This i achieved by the use of WSDL 2.0 <emph>properties</emph>. Each feature, SOAP module, or SOAP binding may express a variety of <emph>properties</emph> in its specification. These properties are very much like variables in a programming language. If GreatH would like to indicate that the <code>securityLevel</code> property should be 5 for the "makeReservation" operation, it would look like this:</p><example id="example-fp-def-prop">
<head>Defining a Property</head>
<eg xml:space="preserve">
***************
*** 1324,1331 ****
Another typical situation for using imports is to define a standard interface that is to be implemented
by many services. For example, suppose the hotel industry decided that it was useful to have a standard interface for
! making reservations. This interface would belong to some industry association namespace, e.g. http://hotels.example.com/reservations/wsdl.
Each hotel that implemented the standard reservation service
! would define a service in its own namespace, e.g. http://greath.example.com/2004/wsdl/resSvc.
! The description of each service would import the http://hotels.example.com/reservations/wsdl namespace and refer to the
standard reservation interface in it.
</p>
--- 1348,1355 ----
Another typical situation for using imports is to define a standard interface that is to be implemented
by many services. For example, suppose the hotel industry decided that it was useful to have a standard interface for
! making reservations. This interface would belong to some industry association namespace, e.g. <code>http://hotels.example.com/reservations/wsdl</code>.
Each hotel that implemented the standard reservation service
! would define a service in its own namespace, e.g. <code>http://greath.example.com/2004/wsdl/resSvc</code>.
! The description of each service would import the <code>http://hotels.example.com/reservations/wsdl</code> namespace and refer to the
standard reservation interface in it.
</p>
***************
*** 1333,1338 ****
</div2><div2 id="adv-multiple-docs-describing-same-service">
<head>Multiple Interfaces for the Same Service</head>
! <p>Suppose a Web service wishes to expose two different interfaces: a customer interface for its regular users, and a management interface for its operator. A wsdl:service specifies only one wsdl:interface, so to achieve the desired effect the service provider would somehow need to indicate a relationship between two services. How can a service provider indicate a relationship between services? Potential strategies include:<ulist><item><p><b>Declare both interfaces in the same wsdl:description element.</b> Although WSDL 2.0 does not ascribe any particular significance to the fact that two wsdl:services are declared within the same wsdl:description, an application or toolkit could interpret this to mean that they are related in some way.</p></item><item><p><b>Declare both interfaces in the same wsdl:targetNamespace.</b> Again, although WSDL 2.0 does not ascribe any particular significance to the fact that two wsdl:services are declared within the same wsdl:targetNamespace, an application or toolit could interpret this to mean that they are related in some way.
! </p></item><item><p><b>Add an extension to WSDL 2.0</b> that links together all services that are related in this way. WSDL 2.0's open content model permits extension elements from other namespaces to appear in a WSDL 2.0 document.</p></item><item><p><b>Declare them in completely separate WSDL documents, but use the same endpoint address for both.</b> I.e., declare a wsdl:interface and wsdl:service for the customer interface in one WSDL document, and a wsdl:interface and wsdl:service for the management interface in a different WSDL document, but use the same endpoint address for both. (By "different WSDL document" we mean that both documents are never included or imported into the same WSDL 2.0 descriptions component.) Although this approach may work in some circumstances, it means that the same endpoint address would be used for two different purposes, which is apt to cause confusion or ambiguity. Furthermore, it is contrary to the Web architectural principle that different URIs should be used to idntify different Web resources. (See the Web Architecture <bibref ref="webarch"/> section on <xspecref href="http://www.w3.org/TR/webarch/#URI-collision">URI collision</xspecref>.)</p></item><item><p><b>Use inheritance to combine the customer interface and management interface</b> into a single, larger wsdl:interface. Of course, this reduces modularity and means that the management interface becomes exposed to the customers, which is not good. </p></item></ulist></p><p>Bear in mind that since the above strategies step outside of the WSDL 2.0 language specifies (and are therefore neither endorsed nor forbidden by the WSDL 2.0 specification) the WSDL 2.0 specification cannot define or standardize their semantics. </p><p>The desire to express relationships between services is also relevant to Web service versioning, discussed next.</p>
</div2><div2 id="adv-versioning">
<head>Web Service Versioning</head>
--- 1357,1362 ----
</div2><div2 id="adv-multiple-docs-describing-same-service">
<head>Multiple Interfaces for the Same Service</head>
! <p>Suppose a Web service wishes to expose two different interfaces: a customer interface for its regular users, and a management interface for its operator. A <code>wsdl:service</code> specifies only one wsdl:interface, so to achieve the desired effect the service provider would somehow need to indicate a relationship between two services. How can a service provider indicate a relationship between services? Potential strategies include:<ulist><item><p><b>Declare both interfaces in the same wsdl:description element.</b> Although WSDL 2.0 does not ascribe any particular significance to the fact that two wsdl:services are declared within the same wsdl:description, an application or toolkit could interpret this to mean that they are related in some way.</p></item><item><p><b>Declare both interfaces in the same wsdl:targetNamespace.</b> Again, although WSDL 2.0 does not ascribe any particular significance to the fact that two wsdl:services are declared within the same wsdl:targetNamespace, an appliction or toolkit could interpret this to mean that they are related in some way.
! </p></item><item><p><b>Add an extension to WSDL 2.0</b> that links together all services that are related in this way. WSDL 2.0's open content model permits extension elements from other namespaces to appear in a WSDL 2.0 document.</p></item><item><p><b>Declare them in completely separate WSDL documents, but use the same endpoint address for both.</b> I.e., declare a <code>wsdl:interface</code> and <code>wsdl:service</code> for the customer interface in one WSDL document, and a <code>wsdl:interface</code> and <code>wsdl:service</code> for the management interface in a different WSDL document, but use the same endpoint address for both. (By "different WSDL document" we mean that both documents are never included or imported into the same WSDL 2.0 descriptions component.) Although this approach may work in some circumstances, it means that the same endpoint address would be used for two different purposes, which is apt to cause confusion or ambiguity. Furthermore, it is contrary to the Web architectura principle that different URIs should be used to identify different Web resources. (See the Web Architecture <bibref ref="webarch"/> section on <xspecref href="http://www.w3.org/TR/webarch/#URI-collision">URI collision</xspecref>.)</p></item><item><p><b>Use inheritance to combine the customer interface and management interface</b> into a single, larger wsdl:interface. Of course, this reduces modularity and means that the management interface becomes exposed to the customers, which is not good. </p></item></ulist></p><p>Bear in mind that since the above strategies step outside of the WSDL 2.0 language specifies (and are therefore neither endorsed nor forbidden by the WSDL 2.0 specification) the WSDL 2.0 specification cannot define or standardize their semantics. </p><p>The desire to express relationships between services is also relevant to Web service versioning, discussed next.</p>
</div2><div2 id="adv-versioning">
<head>Web Service Versioning</head>
***************
*** 1350,1354 ****
for schema versioning as a part of the Schema 1.1 activity. See XML Schema Versioning Use Cases <bibref ref="xsd-versioning"/>.</p></item><item><p>The <loc href="http://www.w3.org/2001/sw/BestPractices/">Semantic Web Best Practices and Deployments Working Group</loc> is
examining how vocabularies may evolve. See <bibref ref="sw-vocabulary"/></p></item></ulist><p>While incomplete, these activities all agree in one important
! respect: that versioning is difficult, but you SHOULD
anticipate and plan for change.</p><p>The draft finding on Versioning and Extensibility details two key
approaches to versioning:</p><ulist><item><p>compatible evolution; and</p></item><item><p>big bang.</p></item></ulist><div3 id="adv-versioning-compatible-evolution"><head>Compatible Evolution</head><p>In <emph>compatible evolution</emph>, designers are expected to limit changes to
--- 1374,1378 ----
for schema versioning as a part of the Schema 1.1 activity. See XML Schema Versioning Use Cases <bibref ref="xsd-versioning"/>.</p></item><item><p>The <loc href="http://www.w3.org/2001/sw/BestPractices/">Semantic Web Best Practices and Deployments Working Group</loc> is
examining how vocabularies may evolve. See <bibref ref="sw-vocabulary"/></p></item></ulist><p>While incomplete, these activities all agree in one important
! respect: that versioning is difficult, but you should
anticipate and plan for change.</p><p>The draft finding on Versioning and Extensibility details two key
approaches to versioning:</p><ulist><item><p>compatible evolution; and</p></item><item><p>big bang.</p></item></ulist><div3 id="adv-versioning-compatible-evolution"><head>Compatible Evolution</head><p>In <emph>compatible evolution</emph>, designers are expected to limit changes to
***************
*** 1411,1415 ****
<p>This section shows how theSOAP Message Transmission Optimization Mechanism (MTOM) <bibref ref="SOAP-MTOM"/> may be engaged in the WSDL 2.0 SOAP binding extension.</p>
! <p>We will modify the CheckAvailability operation of the GreatH Hotel Reservation Service (<specref ref="example-initial"/>) to return not only the room rate, but images of the room and the floorplan. This will involve modifying the checkAvailabilityResponse data structure to include binary data representing these two images, indicated by the <code>xs:base64Binary</code> data type. Here is an example:</p>
<example id="example-MTOM-schema">
--- 1435,1439 ----
<p>This section shows how theSOAP Message Transmission Optimization Mechanism (MTOM) <bibref ref="SOAP-MTOM"/> may be engaged in the WSDL 2.0 SOAP binding extension.</p>
! <p>We will modify the <code>CheckAvailability</code> operation of the GreatH Hotel Reservation Service (<specref ref="example-initial"/>) to return not only the room rate, but images of the room and the floorplan. This will involve modifying the <code>checkAvailabilityResponse</code> data structure to include binary data representing these two images, indicated by the <code>xs:base64Binary</code> data type. Here is an example:</p>
<example id="example-MTOM-schema">
***************
*** 1444,1450 ****
]]></eg></example>
! <p>Note the use of the <code>xmime:expectedContentType</code> and <code>xmime:contentType</code> attributes to declare the expected media type of the encoded data and to allow the client to indicate the type at runtime, respectively. These attributes are defined in Describing Media Content of Binary Data in XML [ref].</p>
! <p>A checkAvailabilityResponse message conforming to this schema might look like this:</p>
<example id="example-MTOM-soap-message">
--- 1468,1474 ----
]]></eg></example>
! <p>Note the use of the <code>xmime:expectedContentType</code> and <code>xmime:contentType</code> attributes to declare the expected media type of the encoded data and to allow the client to indicate the type at runtime, respectively. These attributes are defined in <bibref ref="DESCRIBEMEDIA">Describing Media Content of Binary Data in XML </bibref>.</p>
! <p>A <code>checkAvailabilityResponse</code> message conforming to this schema might look like this:</p>
<example id="example-MTOM-soap-message">
***************
*** 1501,1508 ****
! <p>The HTTP Message Transmission Optimization (MTOM) feature is engaged using the <code>feature</code> element. Note that the attribute required=�?true�? on the feature declaration indicates that the message must be encoded using the HTTP Optimization feature. If the attribute were required=�?false�? (or this attribute were absent), it would indicate that the use of MTOM is optional for this service: the service accepts either MTOM-encoded messages, or the embedded base64Binary data directly in the Body, and the client is free to send either form of message. </p>
! <p>The example above shows MTOM enabled for a specific message within an operation. Placing the feature declaration as a child of <code>operation</code> would require (or enable if required=�?false�?) MTOM support for all the messages in that operation. Placing the feature declaration as a child of <code>binding</code> would require (or enable if required=�?false�?) MTOM support for all the operations in that interface.
</p>
--- 1525,1532 ----
! <p>The HTTP Message Transmission Optimization (MTOM) feature is engaged using the <code>feature</code> element. Note that the attribute <code>required="true"</code> on the feature declaration indicates that the message must be encoded using the HTTP Optimization feature. If the attribute were <code>required="false"</code> (or this attribute were absent), it would indicate that the use of MTOM is optional for this service: the service accepts either MTOM-encoded messages, or the embedded base64Binary data directly in the SOAP Body, and the client is free to send either form of message. </p>
! <p>The example above shows MTOM enabled for a specific message within an operation. Placing the feature declaration as a child of <code>operation</code> would require (or enable if <code>required="false"</code>) MTOM support for all the messages in that operation. Placing the feature declaration as a child of <code>binding</code> would require (or enable if <code>required="false"</code>) MTOM support for all the operations in that interface.
</p>
***************
*** 1575,1579 ****
subject to further mapping restrictions specific to the target
programming language. In this case, the name of the method would be
! "checkAvailability".</p><p>The local children elements of the input element and output element
designate
the parameters and the return type for a method call. Note that the
--- 1599,1603 ----
subject to further mapping restrictions specific to the target
programming language. In this case, the name of the method would be
! "<code>checkAvailability</code>".</p><p>The local children elements of the input element and output element
designate
the parameters and the return type for a method call. Note that the
***************
*** 2696,2700 ****
schemas because they were part of the WSDL documents being processed. The <code>schemaLocation</code> attribute can be used to give the processor a URI reference
that explicitly locates the schemas. A URI reference is a URI plus an optional fragment identifier that indicates part of the resource. For schemas, the fragment should identify
! the <code>schema</code> element. The simplest way to accomplish this is to use the <code>id</code> attribute, however XPointer can also be used.
</p><div4><head>Using the id Attribute to Identify Inline
Schemas</head><p>
--- 2720,2724 ----
schemas because they were part of the WSDL documents being processed. The <code>schemaLocation</code> attribute can be used to give the processor a URI reference
that explicitly locates the schemas. A URI reference is a URI plus an optional fragment identifier that indicates part of the resource. For schemas, the fragment should identify
! the <code>schema</code> element. The simplest way to accomplish this is to use the <code>id</code> attribute, however XPointer (see <bibref ref="XPTR"/>) can also be used.
</p><div4><head>Using the id Attribute to Identify Inline
Schemas</head><p>
***************
*** 2842,2850 ****
<att>import</att> mechanism, which is based on XML
Schema's term for the similar concept.</p></div3><div3 id="adv-relative-uris"><head>Relative URIs</head><p>Throughout this document there are fully qualified URIs used
! in WSDL 2.0 and XSD examples. In some cases, the use of a fully qualified URI
! is simply to illustrate the referencing concepts. however, the use of
relative URIs is allowed and warranted in many
cases. For information on processing relative URIs, see
! <loc href="http://www.ietf.org/rfc/rfc2396.txt">RFC2396</loc>.</p></div3><div3 id="adv-generating-uris"><head>Generating Temporary URIs</head><p>In general, when a WSDL 2.0 document is published for use by others, it should contain URIs that are globally unique. This is usually done by allocating them under a domain name that is controlled by the issuer. For example, the W3C allocates namespace URIs under its base domain name, w3.org.</p><p>However, it is sometimes desirable to make
up a temporary URI for an entity, for use during development, but not make the URI globally unique
for all time and have it "mean" that version of the
--- 2866,2874 ----
<att>import</att> mechanism, which is based on XML
Schema's term for the similar concept.</p></div3><div3 id="adv-relative-uris"><head>Relative URIs</head><p>Throughout this document there are fully qualified URIs used
! in WSDL 2.0 and XSD examples. In some cases, fully qualified URIs
! were used simply to illustrate the referencing concepts. However, the use of
relative URIs is allowed and warranted in many
cases. For information on processing relative URIs, see
! <loc href="http://www.ietf.org/rfc/rfc2396.txt">RFC2396</loc>.</p></div3><div3 id="adv-generating-uris"><head>Generating Temporary URIs</head><p>In general, when a WSDL 2.0 document is published for use by others, it should only contain URIs that are globally unique. This is usually done by allocating them under a domain name that is controlled by the issuer. For example, the W3C allocates namespace URIs under its base domain name, w3.org.</p><p>However, it is sometimes desirable to make
up a temporary URI for an entity, for use during development, but not make the URI globally unique
for all time and have it "mean" that version of the
***************
*** 3043,3046 ****
--- 3067,3081 ----
http://www.w3.org/TR/2004/NOTE-ws-gloss-20040211/ .
</bibl>
+
+ <bibl key="Describing Media Content of Binary Data in XML" xmlns:xlink="http://www.w3.org/1999/xlink" xlink:type="simple" xlink:show="replace" xlink:actuate="onRequest" href="http://www.w3.org/TR/xml-media-types/" id="DESCRIBEMEDIA">
+ <titleref>Describing Media Content of Binary Data in XML
+ </titleref>,
+ Anish Karmarkar, Ümit Yalçınalp, Editors. W3C Working Group Note 4 May 2005.
+ Available at http://www.w3.org/TR/xml-media-types/
+
+ </bibl>
+
+
+
</blist>
</div2>
***************
*** 3093,3097 ****
http://www.w3.org/TR/soap12-part1/.
</bibl>
! <!--
<bibl id="SOAP12-PART2" key="SOAP 1.2 Part 2: Adjuncts"
--- 3128,3132 ----
http://www.w3.org/TR/soap12-part1/.
</bibl>
!
<bibl id="SOAP12-PART2" key="SOAP 1.2 Part 2: Adjuncts"
***************
*** 3109,3113 ****
available at http://www.w3.org/TR/soap12-part2/.
</bibl>
!
<bibl key="23" id="RFC2026" href="http://www.ietf.org/rfc/rfc2026.txt">IETF "RFC 2026:
The Internet Standards Process - Revision 3", section
--- 3144,3148 ----
available at http://www.w3.org/TR/soap12-part2/.
</bibl>
! <!--
<bibl key="23" id="RFC2026" href="http://www.ietf.org/rfc/rfc2026.txt">IETF "RFC 2026:
The Internet Standards Process - Revision 3", section
Index: wsdl20-primer.html
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.html,v
retrieving revision 1.59
retrieving revision 1.60
diff -C2 -d -r1.59 -r1.60
*** wsdl20-primer.html 10 May 2005 17:28:20 -0000 1.59
--- wsdl20-primer.html 20 May 2005 02:18:18 -0000 1.60
***************
*** 1,15 ****
! <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
! "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
! <html lang="en" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
! <head>
! <meta name="generator" content=
! "HTML Tidy for Linux/x86 (vers 1st February 2005), see www.w3.org" />
! <meta http-equiv="Content-Type" content=
! "text/html; charset=utf-8" />
! <title>Web Services Description Language (WSDL) Version 2.0 Part 0:
! Primer</title>
[...7889 lines suppressed...]
! (Electronic Data Systems), Yaron Goland
! (BEA Systems, Inc.), Ümit Yalçınalp
! (Oracle Corporation), Peter Madziak
! (Agfa-Gevaert N. V.), Jeffrey Schlimmer
! (Microsoft Corporation), Hao He
! (The Thomson Corporation), Erik Ackerman
! (Lexmark), Jerry Thrasher
! (Lexmark), Prasad Yendluri
! (webMethods, Inc.), William Vambenepe
! (Hewlett-Packard Company), David Booth
! (W3C), Sanjiva Weerawarana
! (IBM).</p>
! <p>The people who have contributed to <a href="http://lists.w3.org/Archives/Public/www-ws-desc/">discussions
! on www-ws-desc@w3.org</a> are also gratefully
! acknowledged.</p>
</div>
!
! </div>
! </body></html>
\ No newline at end of file
Received on Friday, 20 May 2005 02:18:33 UTC