- From: David Booth via cvs-syncmail <cvsmail@w3.org>
- Date: Mon, 18 Apr 2005 07:39:24 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20
In directory hutz:/tmp/cvs-serv13536
Modified Files:
wsdl20-primer.xml wsdl20-primer.html
Log Message:
Added DaveO REST examples to sec 7.9 Service References
Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.56
retrieving revision 1.57
diff -C2 -d -r1.56 -r1.57
*** wsdl20-primer.xml 18 Apr 2005 04:09:17 -0000 1.56
--- wsdl20-primer.xml 18 Apr 2005 07:39:22 -0000 1.57
***************
*** 204,209 ****
</description>]]></eg>
</example><ednote><name>dbooth</name><date>205-04-12</date><edtext>ToDo: Make opCheckAvailability use GET instead of POST,
! and set the safe="true" on it.</edtext></ednote><ednote><name>dbooth</name><date>2005-04-12</date><edtext>ToDo: Should we add line numbers to the examples, to make it clearer in the explanations when we refer to specific portions? I think this may be helpful. If so, we should: 1. Add them to the complete example above; 2. When showing excerpts, use the same line numbers from the complete example above (for consistency); 3. Explain that the line numbers are not a part of the XML or WSDL 2.0 document, but are merely shown in this primer for ease of reference.</edtext></ednote></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 distingishable from similar names in a different WSDL target namespace. (This will become important if using WSDL 2.0's import or interface inheritance mechanisms.) </p><p>The value of the WSDL target namespace MUST be an absolute URI. Furthermore, it SHOULD be dereferenceable to a WSDL document that describes the Web service that the WSDL target namespace is used to describe. For example, the GreatH owners SHOULD make the WSDL document available from this URI. (And if a WSDL description is split into multiple documents, then the WSDL target namespace should resolve to a master document that includes all the WSDL documents needed for that service description.) However, there is no absolute requirement for this URI to be dereferenceable, so a WSDL processor must not depend on it being dereferenceable. </p><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 trget namespace URI, a user SHOULD be able to obtain an authoritative version. Since GreatH will be the owner of the service, the WSDL target namespace URI should refer to a location on the GreatH Web site or otherwise within its control.</p><p>Once we have decided on a WSDL target namespace URI, we can begin our WSDL 2.0 document as the following empty shell.</p><example id="example-empty-shell">
! <head>An Initial Empty WSDL Document</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
<description
--- 204,209 ----
</description>]]></eg>
</example><ednote><name>dbooth</name><date>205-04-12</date><edtext>ToDo: Make opCheckAvailability use GET instead of POST,
! and set the safe="true" on it.</edtext></ednote><ednote><name>dbooth</name><date>2005-04-12</date><edtext>ToDo: Should we add line numbers to the examples, to make it clearer in the explanations when we refer to specific portions? I think this may be helpful. If so, we should: 1. Add them to the complete example above; 2. When showing excerpts, use the same line numbers from the complete example above (for consistency); 3. Explain that the line numbers are not a part of the XML or WSDL 2.0 document, but are merely shown in this primer for ease of reference.</edtext></ednote></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 distingishable 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 master document that includes all the WSDL documents needed for that service description.) However, there is no absolute requirement for this URI to be dereferenceable, so a WSDL processor must not depend on it being dereferenceable. </p><p>This recommendation may sound circular, but bear in mind that the client might have obtained the WSDL document from anywhere -- not necessarily an authoritative source. But by dereferencing the WSD 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" ?>
<description
***************
*** 297,301 ****
. . .
! </description>]]></eg></example><div3 id="example-initial-interface-explanation"><head>Explanation of Example</head><glist><gitem><label><code><interface name = "reservationInterface" ></code></label><def><p>Interfaces are declared directly inside the <code>description</code> element. In this example, we are declaring only one interface, but in general a WSDL document may declare more than one interface. Thus, each interface must be given a name that is unique within the set of interfaces defined in this WSDL target namespace. Interface names are tokens that must not contain a space or colon (":").</p></def></gitem><gitem><label><code><fault name = "invalidDataFault"
</code></label><def><p>The <code>name</code> attribute defines a name for this fault. The name is required so that when an operation is defined, it can reference the desired fault by name. Fault names must be unique within an interface.</p></def></gitem><gitem><label><code>element = "ghns:invalidDataError"/></code></label><def><p>The <code>element</code> attribute specifies the schema type of the fault message, as previously defined in the <code>types</code> section. </p></def></gitem><gitem><label><code><operation name="opCheckAvailability"</code></label><def><p>The <code>name</code> attribute defines a name for this operation, so that it can be referenced later when bindings are defined. Operation names must also be unique within an interface. (WSDL 2.0 uses separate symbol spaces for operation and fault names, so operation name "foo" is distinct from fault name "foo".)</p></def></gitem><gitem><label><code>pattern="http://www.w3.org/2004/03/wsdl/in-out" </code></label><def><p>Thi line specifies that this operation will use the <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref> pattern as described above. WSDL 2.0 uses URIs to identify message exchange patterns in order to ensure that the identifiers are globally unambiguous, while also permitting future new patterns to be defined by anyone. (However, just because someone defines a new pattern and creates a URI to identify it, that does <emph>not</emph> mean that other WSDL processors will automatically recognize or understand that pattern. As with any other extension, it can be used among processors that <i>do</i> recognize and understand it.)</p></def></gitem><gitem><label><code>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="mor-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="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref> pattern that we've chosen to use only has one input message, it is trivial in this case: we simply fill in the message label "In" that was defined in <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSDL-PART2"/> section 2.2.3 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">InOut</xspecref> for the <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref> pattern. However, if a new pattern is defined that involve multiple input messages, then the different input messages in the pattern could then be distinguished by having different labels.</p></def></gitem><gitem><label><code>element="ghns: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 shema 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="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-trigger">message-triggers-fault rule</xspecref>; others use a <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-replacement">fault-replaces-message</xspecref> rule. See <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSDL-PART2"/> section 2.1.2 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-trigger">Message Triggers Fault</xspecref> and ection 2.1.1 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-replacement">Fault Replaces Message</xspecref>.) </p></def></gitem></glist><p>Now that we've defined the abstract interface for the GreatH service, we're ready to define a binding for it.</p></div3></div2>
--- 297,301 ----
. . .
! </description>]]></eg></example><div3 id="example-initial-interface-explanation"><head>Explanation of Example</head><glist><gitem><label><code><interface name = "reservationInterface" ></code></label><def><p>Interfaces are declared directly inside the <code>description</code> element. In this example, we are declaring only one interface, but in general a WSDL 2.0 document may declare more than one interface. Thus, each interface must be given a name that is unique within the set of interfaces defined in this WSDL target namespace. Interface names are tokens that must not contain a space or colon (":").</p></def></gitem><gitem><label><code><fault name = "invalidDataFault"
</code></label><def><p>The <code>name</code> attribute defines a name for this fault. The name is required so that when an operation is defined, it can reference the desired fault by name. Fault names must be unique within an interface.</p></def></gitem><gitem><label><code>element = "ghns:invalidDataError"/></code></label><def><p>The <code>element</code> attribute specifies the schema type of the fault message, as previously defined in the <code>types</code> section. </p></def></gitem><gitem><label><code><operation name="opCheckAvailability"</code></label><def><p>The <code>name</code> attribute defines a name for this operation, so that it can be referenced later when bindings are defined. Operation names must also be unique within an interface. (WSDL 2.0 uses separate symbol spaces for operation and fault names, so operation name "foo" is distinct from fault name "foo".)</p></def></gitem><gitem><label><code>pattern="http://www.w3.org/2004/03/wsdl/in-out" </code></label><def><p>Thi line specifies that this operation will use the <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref> pattern as described above. WSDL 2.0 uses URIs to identify message exchange patterns in order to ensure that the identifiers are globally unambiguous, while also permitting future new patterns to be defined by anyone. (However, just because someone defines a new pattern and creates a URI to identify it, that does <emph>not</emph> mean that other WSDL processors will automatically recognize or understand that pattern. As with any other extension, it can be used among processors that <i>do</i> recognize and understand it.)</p></def></gitem><gitem><label><code>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="mor-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="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref> pattern that we've chosen to use only has one input message, it is trivial in this case: we simply fill in the message label "In" that was defined in <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSDL-PART2"/> section 2.2.3 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">InOut</xspecref> for the <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref> pattern. However, if a new pattern is defined that involve multiple input messages, then the different input messages in the pattern could then be distinguished by having different labels.</p></def></gitem><gitem><label><code>element="ghns: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 shema 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="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-trigger">message-triggers-fault rule</xspecref>; others use a <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-replacement">fault-replaces-message</xspecref> rule. See <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSDL-PART2"/> section 2.1.2 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-trigger">Message Triggers Fault</xspecref> and ection 2.1.1 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-replacement">Fault Replaces Message</xspecref>.) </p></def></gitem></glist><p>Now that we've defined the abstract interface for the GreatH service, we're ready to define a binding for it.</p></div3></div2>
***************
*** 346,350 ****
<bibref ref="RFC2616"/>
as predefined extensions, so that SOAP 1.2 or HTTP 1.1
! bindings can be easily defined in WSDL documents.
However, other specifications could define new binding
extensions that could also be used to define bindings.
--- 346,350 ----
<bibref ref="RFC2616"/>
as predefined extensions, so that SOAP 1.2 or HTTP 1.1
! bindings can be easily defined in WSDL 2.0 documents.
However, other specifications could define new binding
extensions that could also be used to define bindings.
***************
*** 445,449 ****
</service>]]></eg>
! </example><div3 id="example-initial-service-explanation"><head>Explanation of Example</head><glist><gitem><label><code><service name="reservationService"</code></label><def><p>This defines a name for this service, which must be unique among service names in the WSDL target namespace. The name attribute is required. It allows URIs to be created that indentify components in WSDL 2.0 description. (See <emph>WSDL 2.0 Core Language</emph> <bibref ref="WSDL-PART1"/> appendix C <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-20040803/#wsdl-uri-references">URI References for WSDL constructs</xspecref>.)</p></def></gitem><gitem><label><code>interface="tns:reservationInterface"></code></label><def><p>This specifies the name of the previously defined interface that these service endpoints will support. </p></def></gitem><gitem><label><code><endpoint name="reservationEndpoint"</code></label><def><p>This defines an endpoint for the service, and a name for this endpoint, which must be unique withn this service. </p></def></gitem><gitem><label><code>binding="tns:reservationSOAPBinding"</code></label><def><p>This specifies the name of the previously defined binding to be used by this endpoint. </p></def></gitem><gitem><label><code>address ="http://greath.example.com/2004/reservation"/></code></label><def><p>This specifies the physical address at which this service can be accessed using the binding specified by the <att>binding</att> attribute.</p></def></gitem></glist><p>That's it! Well, almost. </p></div3></div2><div2 id="basics-documentation"><head>Documenting the Service</head><p>As we have seen, a WSDL 2.0 document is inherently only a <emph>partial</emph> description of a service. Although it captures the basic mechanics of interacting with the service -- the message types, transmission protocols, service location, etc. -- in general, additional documention will need to explain other application-level requirements for its use. For example, such documentation should explain the purpose ad use of the service, the meanings of all messages, constraints on their use, and the sequence in which operations should be invoked.</p><p>The <code>documentation</code> element allows the WSDL author to include some human-readable documentation inside a WSDL document. It is also a convenient place to reference any additional external documentation that a client developer may need in order to use the service. It can appear in a number of places in a WSDL 2.0 document (see <specref ref="wsdl-infoset-diagram"/>), though in this example we have only demonstrated its use at the beginning.</p><example id="example-initial-documentation">
<head>Documenting the GreatH Service</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
--- 445,449 ----
</service>]]></eg>
! </example><div3 id="example-initial-service-explanation"><head>Explanation of Example</head><glist><gitem><label><code><service name="reservationService"</code></label><def><p>This defines a name for this service, which must be unique among service names in the WSDL target namespace. The name attribute is required. It allows URIs to be created that indentify components in WSDL 2.0 description. (See <emph>WSDL 2.0 Core Language</emph> <bibref ref="WSDL-PART1"/> appendix C <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-20040803/#wsdl-uri-references">URI References for WSDL constructs</xspecref>.)</p></def></gitem><gitem><label><code>interface="tns:reservationInterface"></code></label><def><p>This specifies the name of the previously defined interface that these service endpoints will support. </p></def></gitem><gitem><label><code><endpoint name="reservationEndpoint"</code></label><def><p>This defines an endpoint for the service, and a name for this endpoint, which must be unique withn this service. </p></def></gitem><gitem><label><code>binding="tns:reservationSOAPBinding"</code></label><def><p>This specifies the name of the previously defined binding to be used by this endpoint. </p></def></gitem><gitem><label><code>address ="http://greath.example.com/2004/reservation"/></code></label><def><p>This specifies the physical address at which this service can be accessed using the binding specified by the <att>binding</att> attribute.</p></def></gitem></glist><p>That's it! Well, almost. </p></div3></div2><div2 id="basics-documentation"><head>Documenting the Service</head><p>As we have seen, a WSDL 2.0 document is inherently only a <emph>partial</emph> description of a service. Although it captures the basic mechanics of interacting with the service -- the message types, transmission protocols, service location, etc. -- in general, additional documention will need to explain other application-level requirements for its use. For example, such documentation should explain the purpose ad use of the service, the meanings of all messages, constraints on their use, and the sequence in which operations should be invoked.</p><p>The <code>documentation</code> element allows the WSDL author to include some human-readable documentation inside a WSDL 2.0 document. It is also a convenient place to reference any additional external documentation that a client developer may need in order to use the service. It can appear in a number of places in a WSDL 2.0 document (see <specref ref="wsdl-infoset-diagram"/>), though in this example we have only demonstrated its use at the beginning.</p><example id="example-initial-documentation">
<head>Documenting the GreatH Service</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
***************
*** 581,585 ****
<!-- ******************MessageTypes********************************** -->
<!-- ******************MessageTypes********************************** -->
! <p>The WSDL 2.0 <code>types</code> element provides a mechanism for enclosing message schemas in a WSDL document. Because WSDL 2.0 directly supports schemas written in XML Schema
<bibref ref="XMLSchemaP1"/>, we will focus here on the use of XML Schema to define message types. Schemas written in other type definition languages must be defined using a WSDL 2.0 language extension. For examples of other schema languages, see WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> Appendix E "<xspecref href="http://www.w3.org/TR/wsdl20-primer#other-schemalang">Examples of Specifications of Extension Elements for Alternative Schema Language Support. (Non-Normative)</xspecref>".
<ednote><name>dbooth</name><date>2005-04-13</date><edtext>ToDo: Update the above reference to appendix E, as the WG decided to move it to a separate document.</edtext></ednote></p>
--- 581,585 ----
<!-- ******************MessageTypes********************************** -->
<!-- ******************MessageTypes********************************** -->
! <p>The WSDL 2.0 <code>types</code> element provides a mechanism for enclosing message schemas in a WSDL 2.0 document. Because WSDL 2.0 directly supports schemas written in XML Schema
<bibref ref="XMLSchemaP1"/>, we will focus here on the use of XML Schema to define message types. Schemas written in other type definition languages must be defined using a WSDL 2.0 language extension. For examples of other schema languages, see WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> Appendix E "<xspecref href="http://www.w3.org/TR/wsdl20-primer#other-schemalang">Examples of Specifications of Extension Elements for Alternative Schema Language Support. (Non-Normative)</xspecref>".
<ednote><name>dbooth</name><date>2005-04-13</date><edtext>ToDo: Update the above reference to appendix E, as the WG decided to move it to a separate document.</edtext></ednote></p>
***************
*** 604,608 ****
<div2 id="more-types-schema-embed">
<head>Embedding XML Schema</head>
! <p>We have already seen an example of using embedded schema definitions in section <specref ref="basics-types"/>, so we will merely add a few additional points here. </p><p>When XML Schema is embedded directly in a WSDL document, it uses the existing top-level <code>xs:schema</code> element defined by XML Schema <bibref ref="XMLSchemaP1"/> to do so, as though the schema had been copied and pasted into the <code>types</code> element. The schema components defined in the embedded schema are then available to
WSDL for reference by QName (see WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> "<xspecref href="http://www.w3.org/TR/wsdl20-primer#qnameres">QName Resolution</xspecref>"). </p>
<p>Although WSDL 2.0 provides a <code>wsdl:import</code> mechanism (described in the next section), an embedded XML schema may also use XML Schema's native <code>xs:import</code> and <code>xs:include</code>
--- 604,608 ----
<div2 id="more-types-schema-embed">
<head>Embedding XML Schema</head>
! <p>We have already seen an example of using embedded schema definitions in section <specref ref="basics-types"/>, so we will merely add a few additional points here. </p><p>When XML Schema is embedded directly in a WSDL 2.0 document, it uses the existing top-level <code>xs:schema</code> element defined by XML Schema <bibref ref="XMLSchemaP1"/> to do so, as though the schema had been copied and pasted into the <code>types</code> element. The schema components defined in the embedded schema are then available to
WSDL for reference by QName (see WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> "<xspecref href="http://www.w3.org/TR/wsdl20-primer#qnameres">QName Resolution</xspecref>"). </p>
<p>Although WSDL 2.0 provides a <code>wsdl:import</code> mechanism (described in the next section), an embedded XML schema may also use XML Schema's native <code>xs:import</code> and <code>xs:include</code>
***************
*** 1127,1131 ****
<div2 id="adv-extensibility">
<head>Extensibility</head>
! <p>WSDL 2.0 provides two extensibility mechanisms: an open content model, which allows XML elements and attributes from other (non-WSDL 2.0) XML namespaces to be interspersed into a WSDL document; and <xspecref href="&w3c-designation-part1;#Feature">Features</xspecref> and <xspecref href="&w3c-designation-part1;#Property">Properties</xspecref>. Both mechanisms use URIs to identify the semantics of the extensions. For extension XML elements and attributes, the namespace URI of the extension element or attribute acts as an unambiguous name for the semantics of that extension. For Features and Properties, the Feature or Property is named by a URI.</p><p>In either case, the URI that identifies the semantics of an extension SHOULD be dereferenceable to a document that describes the semantics of that extension. As of this writing, there is no generally accepted standard for what kind of document that should be. However, the <loc href="http://www.w3.org/2001/tag/">W3C TAG</loc> has been discussing the ssue (see TAG issue <loc href="http://www.w3.org/2001/tag/issues.html?type=1#namespaceDocument-8">namespaceDocument-8</loc>) and is likely to provide guidance at some point.</p><div3 id="adv-optional-versus-required"><head>Optional Versus Required Extensions</head><p>Extensions can either be required or optional.</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</mph> 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 fro 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>
--- 1127,1131 ----
<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>
***************
*** 1196,1200 ****
</interface>
. . .]]></eg>
! </example><p>The <code>property</code> element specifies which property is to be set. By setting the <code>value</code> element, a toolkit processing this WSDL 2.0 document is informed that the securityLevel property must be set to 5. The particular meanings of any such values are up to the implementations of the modules/bindings that use them. The <code>property</code> element can be placed at many different levels in a WSDL document (see "Property Composition Model", section 2.8.1.1 in WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/>).
</p><p>It is also possible to provide a <emph>constraint</emph> on the value space for a given property. This allows the author of the WSDL 2.0 document to indicate that several valid values for the property are possible for a given scope, limiting the value space already described in the specification that defined the property. Let's extend our example to make this clearer.</p><p>The security feature specification defines securityLevel as an integer with values between 1 and 10, each of which indicates, according to the spec, a progressively higher level of security. The GreatH service authors, having read the relevant specifications, have decided that any security level between 3 and 7 will be supported by their infrastructure. Levels less than 3 are deemed unsafe for GreatH's purposes, and levels greater than 7 require too much in the way of resources to make it worthwhile. We can express this in WSDL 2.0 as follows:</p><example id="example-fp-def-prop-constraints">
<head>Defining Property Constraints</head>
--- 1196,1200 ----
</interface>
. . .]]></eg>
! </example><p>The <code>property</code> element specifies which property is to be set. By setting the <code>value</code> element, a toolkit processing this WSDL 2.0 document is informed that the securityLevel property must be set to 5. The particular meanings of any such values are up to the implementations of the modules/bindings that use them. The <code>property</code> element can be placed at many different levels in a WSDL 2.0 document (see "Property Composition Model", section 2.8.1.1 in WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/>).
</p><p>It is also possible to provide a <emph>constraint</emph> on the value space for a given property. This allows the author of the WSDL 2.0 document to indicate that several valid values for the property are possible for a given scope, limiting the value space already described in the specification that defined the property. Let's extend our example to make this clearer.</p><p>The security feature specification defines securityLevel as an integer with values between 1 and 10, each of which indicates, according to the spec, a progressively higher level of security. The GreatH service authors, having read the relevant specifications, have decided that any security level between 3 and 7 will be supported by their infrastructure. Levels less than 3 are deemed unsafe for GreatH's purposes, and levels greater than 7 require too much in the way of resources to make it worthwhile. We can express this in WSDL 2.0 as follows:</p><example id="example-fp-def-prop-constraints">
<head>Defining Property Constraints</head>
***************
*** 1371,1375 ****
<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. WSDL 2.0 limits a wsdl:service to a single wsdl:interface, and does not provide any mechanisms to formally indicate this kind of relationship between interfaces. How can service providers indicate a relationship between services? Conventions outside of the WSDL 2.0 language can be used, but since they are outside of the WSDL 2.0 language (and therefore neither endorsed nor forbidden by the WSDL 2.0 specification) the WSDL 2.0 specification cannot define or standardize their semantics. With that caveat in mind, 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 i 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 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 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 identiy 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>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>
--- 1371,1375 ----
<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. WSDL 2.0 limits a wsdl:service to a single wsdl:interface, and does not provide any mechanisms to formally indicate this kind of relationship between interfaces. How can service providers indicate a relationship between services? Conventions outside of the WSDL 2.0 language can be used, but since they are outside of the WSDL 2.0 language (and therefore neither endorsed nor forbidden by the WSDL 2.0 specification) the WSDL 2.0 specification cannot define or standardize their semantics. With that caveat in mind, 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 i 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 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 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>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>
***************
*** 1645,1649 ****
which are the Web service analogs of document
hyperlinks.
! This will be illustrated by expanding the GreatH example already discussed.</p>
<div3 id="reservationDetails"><head>The Reservation Details Web Service</head>
--- 1645,1649 ----
which are the Web service analogs of document
hyperlinks.
! </p><p>One may wonder, from a Web architectural point of view, why anything more than a URI would be needed to reference a Web service. Indeed, a service reference does make use of a URI to indicate the endpoint address of a service. However, it may also include additional metadata about that service, such as the WSDL 2.0 interface and binding that the service supports.</p><p>Services references will be illustrated by expanding the GreatH example already discussed.</p>
<div3 id="reservationDetails"><head>The Reservation Details Web Service</head>
***************
*** 1907,1912 ****
<head>
Response from the Reservation List Web
! Service
! </head>
<eg>
<![CDATA[<?xml version="1.0" encoding="UTF-8"?>
--- 1907,1911 ----
<head>
Response from the Reservation List Web
! Service</head>
<eg>
<![CDATA[<?xml version="1.0" encoding="UTF-8"?>
***************
*** 1975,1983 ****
wdetails:reservationDetailsSOAPBinding
</code>
! . These QNames identify WSLD Interface and
Binding components that are defined in a WSDL
! document. This example shows the use of the
<code>wsdli:wsdlLocation</code>
! attribute to locate the WSDL document. The
address of each endpoint is the URI assigned to
each reservation.
--- 1974,1982 ----
wdetails:reservationDetailsSOAPBinding
</code>
! . These QNames identify WSDL 2.0 Interface and
Binding components that are defined in a WSDL
! 2.0 document. This example shows the use of the
<code>wsdli:wsdlLocation</code>
! attribute to locate the WSDL 2.0 document. The
address of each endpoint is the URI assigned to
each reservation.
***************
*** 2085,2089 ****
</example>
! <p><specref ref="reservationList.xsd"/>Shows the schema for the messages used in the Reservation List Web service.</p>
<example id="reservationList.xsd">
<head>The Reservation List Schema: reservationList.xsd</head>
--- 2084,2088 ----
</example>
! <p><specref ref="reservationList.xsd"/> shows the schema for the messages used in the Reservation List Web service.</p>
<example id="reservationList.xsd">
<head>The Reservation List Schema: reservationList.xsd</head>
***************
*** 2142,2159 ****
</example>
</div3>
! </div2>
<div2 id="adv-multiple-inline-schemas">
! <head>Multiple In-Line Schemas</head>
! <p>@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@</p><ednote>
<name>Arthur</name>
<date>20050329</date>
! <edtext>
! The cited discussion thread is about Schemas in
! imported WSDL, not Multiple In-Line Schemas. I
! will therefore include an example that addresses
! that topic of the thread, and an example that
! addresses the section title. BTW, I find the
resolution of the thread to be very
unsatisfactory since it doesn't nail down the
--- 2141,2272 ----
</example>
</div3>
! <div3 id="reservationDetails_HTTP"><head>Reservation Details Web Service Using HTTP Transfer</head><p>This section presents a variation on the example in <specref ref="reservationDetails"/>. It illustrates the use of HTTP transfer operations, GET and PUT, to retrieve and update GreatH hotel reservation details using the Representational State Transfer (REST) architectural style described by Roy Fielding @@bibref@@. REST is a distillation of the architectural properties that Dr. Fielding identified as being vital to the Web's robustness and enormous scalabilty. </p><p>Since each reservation in our example will have a distinct URI, the Reservation Details Web
! service can be offered using HTTP GET and HTTP PUT. The binding would be modified as follows:</p><example id="reservationDetails_HTTP_example">
! <head>
! Reservation Details Web Service Using HTTP Transfer</head>
! <ednote><name>dbooth</name><date>2005-04-15</date><edtext>ToDo: Check/fix this example. Shouldn't it specify what protocol to use?</edtext></ednote><eg>
! <![CDATA[. . .
! <binding name="reservationDetailsHTTPBinding"
! interface="tns:reservationDetailsInterface" >
!
! <operation ref="tns:retrieve"
! whttp:method="GET" />
!
! <operation ref="tns:update"
! whttp:method="PUT" />
!
! </binding>
! . . .]]>
! </eg>
! </example><p>As with the example in <specref ref="reservationDetails"/>, service and endpoint elements are not
! provided because the Reservation List Web service provides the
! endpoints. </p></div3><div3 id="reservationList_HTTP_GET"><head>Reservation List Web Service Using HTTP GET</head><p>This section continues the REST-style example of <specref ref="reservationDetails_HTTP"/> by modifying the example of <specref ref="reservationList"/> to use HTTP GET.</p><p>The SOAP version of the Reservation List Web service above offers four different search
! operations. These can also be expressed as various parameters in a URI
! used by HTTP GET:</p><example id="example_reservationList_HTTP_GET">
! <head>
! Reservation List Web Service Using HTTP GET</head>
! <ednote><name>dbooth</name><date>2005-04-15</date><edtext>ToDo: Check/fix this example. Shouldn't it specify what protocol to use?</edtext></ednote><eg>
! <![CDATA[. . .
! <binding name="reservationListHTTPBinding"
! interface="tns:reservationListInterface"
! whttp:methodDefault="GET">
!
! <operation ref="tns:retrieve"
! whttp:location="" />
!
! <operation ref="tns:retrieveByConfirmationNumber"
! whttp:location="/ConfirmationNumber/{confirmationNumber/}" />
!
! <operation ref="tns:retrieveByCheckInDate"
! whttp:location="/CheckInDate/{checkInDate/}" />
!
! <operation ref="tns:retrieveByCheckOutDate"
! whttp:location="/CheckOutDate/{checkOutDate/}" />
! </binding>
! . . .
! <service . . . >
!
! <endpoint name="reservationListEndpoint"
! binding="tns:reservationListHTTPBinding"
! address="http://greath.example.com/2004/reservationList" />
! . . .
! </service>
! . . .]]>
! </eg>
! </example><p>A retrieval by Confirmation Number URI would look like:
! <code>http://greath.example.com/2004/reservationList/ConfirmationNumber/HSG635 .</code></p><p>Alternatively, a single query type may be provided. This query type is
! a sequence of optional items. Any items in the sequence are serialized
! into the URI query string. A query sequence for any of
! ConfirmationNumber, checkInDate, checkOutDate would look like this:</p><example id="example_reservationList_HTTP_GET_single">
! <head>Query Sequence Using a Single Query Type</head>
! <eg>
! <![CDATA[<element name="reservationQuery">
! <annotation>
! <documentation>
! A reservation contains the confirmation number, check-in
! and check-out dates, and a reference to a Reservation
! Details Web service.
! </documentation>
! </annotation>
! <complexType>
! <sequence>
! <element ref="details:confirmationNumber" minOccurs="0"/>
! <element ref="details:checkInDate" minOccurs="0"/>/>
! <element ref="details:checkOutDate" minOccurs="0"/>/>
! </sequence>
! </sequence>
! </complexType>
! </element>]]>
! </eg>
! </example><p>The WSDL service that offers this type serialized as a parameter would look like this:</p><example id="example_reservationList_HTTP_GET_single_wsdl">
! <head>WSDL for Using a Single Query Type</head>
! <ednote><name>dbooth</name><date>2005-04-15</date><edtext>ToDo: Check/fix this example. Shouldn't it specify what protocol to use?</edtext></ednote><eg>
! <![CDATA[. . .
! <interface name="reservationListInterfaceWithQuery">
!
! <operation name="retrieveByReservationQuery"
! pattern="http://www.w3.org/2004/03/wsdl/in-out">
! <input messageLabel="In"
! element="details:ReservationQuery" />
! <output messageLabel="Out"
! element="list:reservationList" />
! </operation>
!
! </interface>
!
! <binding name="reservationListQueryHTTPBinding"
! interface="tns:reservationListInterfaceWithQuery"
! whttp:methodDefault="GET">
!
! <operation ref="tns:retrieveByReservationQuery"
! whttp:location="/{ReservationQuery}}" />
!
! </binding>
!
! . . .
! <endpoint name="reservationListEndpoint"
! binding="tns:reservationListHTTPBinding"
! address="http://greath.example.com/2004/reservationList" />
! . . .]]>
! </eg>
! </example><p>Various URIs would be:
!
! <code>http://greath.example.com/2004/reservationList/ReservationQuery?confirmationNumber=HSG635</code>
!
! <code>http://greath.example.com/2004/reservationList/ReservationQuery?checkInDate=06-06-05</code>
!
!
!
! .</p><p>It is important to observe that using the URI serialization can result
! in very flexible queries and few operations. The previous discrete SOAP
! operations are collapsed into one "parameterized" operation.</p></div3></div2>
<div2 id="adv-multiple-inline-schemas">
! <head>Importing Schemas</head>
! <ednote>
<name>Arthur</name>
<date>20050329</date>
! <edtext>I find the
resolution of the thread to be very
unsatisfactory since it doesn't nail down the
***************
*** 2166,2176 ****
</edtext>
</ednote>
! <p>
! [Need to explain that this can be done. See
! http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0109.html
! http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0126.html
! http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0130.html
! ]
! </p>
<p>
WSDL 2.0 documents may contain one or more XML
--- 2279,2283 ----
</edtext>
</ednote>
!
<p>
WSDL 2.0 documents may contain one or more XML
***************
*** 2190,2198 ****
is defined in the
<code>retrieveDetails.wsdl</code>
! WSDL document, along with a schema for the
message format. The updating Web service is
defined in the
<code>updateDetails.wsdl</code>
! WSDL document which imports the first document
and refers to both WSDL and schema definitions
contained in the imported document.
--- 2297,2305 ----
is defined in the
<code>retrieveDetails.wsdl</code>
! WSDL 2.0 document, along with a schema for the
message format. The updating Web service is
defined in the
<code>updateDetails.wsdl</code>
! WSDL 2.0 document which imports the first document
and refers to both WSDL and schema definitions
contained in the imported document.
***************
*** 2206,2210 ****
http://greath.example.com/2004/services/retrieveDetails
</code>
! namespace. This WSDL document also
contains an inline schema that describes the
reservation detail in the
--- 2313,2317 ----
http://greath.example.com/2004/services/retrieveDetails
</code>
! namespace. This WSDL 2.0 document also
contains an inline schema that describes the
reservation detail in the
***************
*** 2324,2328 ****
<code>retrieveDetails.wsdl</code>
document which contains the imported namespace
! in an inline schema so it should not any hints.
However, this behavior depends on
the implementation of the processor and so
--- 2431,2435 ----
<code>retrieveDetails.wsdl</code>
document which contains the imported namespace
! in an inline schema so it should not need any hints.
However, this behavior depends on
the implementation of the processor and so
***************
*** 2330,2334 ****
</p>
<p>
! Although the WSDL document may validly omit the
<code>schemaLocation</code> attribute, it is a best practice to either provide a
reliable value for
--- 2437,2441 ----
</p>
<p>
! Although the WSDL 2.0 document may validly omit the
<code>schemaLocation</code> attribute, it is a best practice to either provide a
reliable value for
***************
*** 2341,2345 ****
and
<code>updateDetails.wsdl</code>. In general, schemas that are expected to be
! referenced from more than one WSDL document
should be defined in a separate schema document
rather than be inlined.
--- 2448,2452 ----
and
<code>updateDetails.wsdl</code>. In general, schemas that are expected to be
! referenced from more than one WSDL 2.0 document
should be defined in a separate schema document
rather than be inlined.
***************
*** 2389,2395 ****
<div3>
! <head>Multiple Inline Schemas on One Document</head>
<p>
! A WSDL document may define multiple inline
schemas in its
<code>types</code>
--- 2496,2502 ----
<div3>
! <head>Multiple Inline Schemas in One Document</head>
<p>
! A WSDL 2.0 document may define multiple inline
schemas in its
<code>types</code>
***************
*** 2508,2547 ****
</div3>
! </div2>
! <div2 id="adv-schema-location">
! <head>The schemaLocation Attribute</head>
! <ednote>
! <name>Arthur</name>
! <date>20050329</date>
! <edtext>Here is my input.</edtext>
! </ednote>
! <p>
! [ACTION: 2003-11-13: David to add discussion /
! example(s) re: @schemaLocation for embedded schemas
! to the primer. See discussion in
! http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0135.html
! and thread called "Schemas in imported WSDL" in
! http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/thread.html
! ]
! </p>
<p>
! In the preceeding examples, schemas were defined inline in WSDL documents. This section discusses the correct way to specify a <code>schemaLocation</code>
attribute on a schema <code>import</code> element to provide a processor with a hint for locating these schemas.
</p>
<p>
! <specref ref="updateDetails.wsdl"/> shows how one WSDL document imports a schema defined in another, i.e. <specref ref="retrieveDetails.wsdl"/>.
! Similarly, <specref ref="retrieveItems.wsdl"/> shows how one schema in a WSDL document imports another schema defined in the same document.
In both of these examples, the <code>schemaLocation</code> attribute was omitted since the WSDL processor was assumed to know how to locate the imported
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 explictly 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>
! <div3>
! <head>
! Using the id Attribute to Identify Inline
! Schemas
! </head>
! <p>
<specref ref="schemaIds.wsdl"/>
shows the use of the
--- 2615,2633 ----
</div3>
! <div3 id="adv-schema-location"><head>The schemaLocation Attribute</head>
<p>
! In the preceding examples, schemas were defined inline in WSDL 2.0 documents. This section discusses the correct way to specify a <code>schemaLocation</code>
attribute on a schema <code>import</code> element to provide a processor with a hint for locating these schemas.
</p>
<p>
! <specref ref="updateDetails.wsdl"/> shows how one WSDL 2.0 document imports a schema defined in another, i.e. <specref ref="retrieveDetails.wsdl"/>.
! Similarly, <specref ref="retrieveItems.wsdl"/> shows how one schema in a WSDL 2.0 document imports another schema defined in the same document.
In both of these examples, the <code>schemaLocation</code> attribute was omitted since the WSDL processor was assumed to know how to locate the imported
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 explictly 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>
<specref ref="schemaIds.wsdl"/>
shows the use of the
***************
*** 2619,2630 ****
</interface>
! </description>]]></eg></example>
!
! </div3>
! </div2>
<div2 id="adv-rdf-mapping">
<head>Mapping to RDF and Semantic Web</head>
! </div2>
<!-- **********************************NotesOnURIs***************** --><div2 id="adv-notes-on-uris"><head>Notes on URIs</head><p>This section does not directly contribute to the
specification, but provides background that may be useful when
--- 2705,2714 ----
</interface>
! </description>]]></eg></example></div4></div3></div2>
!
<div2 id="adv-rdf-mapping">
<head>Mapping to RDF and Semantic Web</head>
! <p>@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@</p></div2>
<!-- **********************************NotesOnURIs***************** --><div2 id="adv-notes-on-uris"><head>Notes on URIs</head><p>This section does not directly contribute to the
specification, but provides background that may be useful when
***************
*** 2644,2648 ****
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 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
--- 2728,2732 ----
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
Index: wsdl20-primer.html
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.html,v
retrieving revision 1.37
retrieving revision 1.38
diff -C2 -d -r1.37 -r1.38
*** wsdl20-primer.html 18 Apr 2005 04:09:17 -0000 1.37
--- wsdl20-primer.html 18 Apr 2005 07:39:22 -0000 1.38
***************
*** 277,287 ****
href="#more-interfaces-op-attr">Operation Attributes</a><br />
        5.4.2 <a
! href="#id5208362">Operation Message References</a><br />
            5.4.2.1
! <a href="#id5208415">The messageLabel Attribute</a><br />
            5.4.2.2
! <a href="#id5208450">The element Attribute</a><br />
            5.4.2.3
! <a href="#id5208515">Multiple infault or outfault
Elements</a><br />
        5.4.3 <a
--- 277,287 ----
href="#more-interfaces-op-attr">Operation Attributes</a><br />
        5.4.2 <a
! href="#id5208368">Operation Message References</a><br />
            5.4.2.1
! <a href="#id5208421">The messageLabel Attribute</a><br />
            5.4.2.2
! <a href="#id5208457">The element Attribute</a><br />
            5.4.2.3
! <a href="#id5208521">Multiple infault or outfault
Elements</a><br />
        5.4.3 <a
***************
*** 308,312 ****
Binding Extension</a><br />
        6.6.1 <a
! href="#id5209850">Explanation of Example</a><br />
    6.7 <a href="#adv-get-vs-post">HTTP GET
Versus POST: Which to Use?</a><br />
--- 308,312 ----
Binding Extension</a><br />
        6.6.1 <a
! href="#id5209857">Explanation of Example</a><br />
    6.7 <a href="#adv-get-vs-post">HTTP GET
Versus POST: Which to Use?</a><br />
***************
*** 357,382 ****
        7.9.2 <a
href="#reservationList">The Reservation List Web Service</a><br />
    7.10 <a
! href="#adv-multiple-inline-schemas">Multiple In-Line
! Schemas</a><br />
        7.10.1 <a
! href="#id5213108">Schemas in Imported Documents</a><br />
        7.10.2 <a
! href="#id5213409">Multiple Inline Schemas on One Document</a><br />
!     7.11 <a href="#adv-schema-location">The
! schemaLocation Attribute</a><br />
!         7.11.1 <a
! href="#id5213717">Using the id Attribute to Identify Inline
Schemas</a><br />
!     7.12 <a href="#adv-rdf-mapping">Mapping to
RDF and Semantic Web</a><br />
!     7.13 <a href="#adv-notes-on-uris">Notes on
URIs</a><br />
!         7.13.1 <a
href="#adv-namespaces-and-schema-locations">XML Namespaces and
Schema Locations</a><br />
!         7.13.2 <a
href="#adv-relative-uris">Relative URIs</a><br />
!         7.13.3 <a
href="#adv-generating-uris">Generating Temporary URIs</a><br />
8. <a href="#References">References</a><br />
--- 357,387 ----
        7.9.2 <a
href="#reservationList">The Reservation List Web Service</a><br />
+         7.9.3 <a
+ href="#reservationDetails_HTTP">Reservation Details Web Service
+ Using HTTP Transfer</a><br />
+         7.9.4 <a
+ href="#reservationList_HTTP_GET">Reservation List Web Service Using
+ HTTP GET</a><br />
    7.10 <a
! href="#adv-multiple-inline-schemas">Importing Schemas</a><br />
        7.10.1 <a
! href="#id5213403">Schemas in Imported Documents</a><br />
        7.10.2 <a
! href="#id5213708">Multiple Inline Schemas in One Document</a><br />
!         7.10.3 <a
! href="#adv-schema-location">The schemaLocation Attribute</a><br />
!             7.10.3.1
! <a href="#id5213891">Using the id Attribute to Identify Inline
Schemas</a><br />
!     7.11 <a href="#adv-rdf-mapping">Mapping to
RDF and Semantic Web</a><br />
!     7.12 <a href="#adv-notes-on-uris">Notes on
URIs</a><br />
!         7.12.1 <a
href="#adv-namespaces-and-schema-locations">XML Namespaces and
Schema Locations</a><br />
!         7.12.2 <a
href="#adv-relative-uris">Relative URIs</a><br />
!         7.12.3 <a
href="#adv-generating-uris">Generating Temporary URIs</a><br />
8. <a href="#References">References</a><br />
***************
*** 709,717 ****
<p>The value of the WSDL target namespace MUST be an absolute URI.
! Furthermore, it SHOULD be dereferenceable to a WSDL document that
! describes the Web service that the WSDL target namespace is used to
! describe. For example, the GreatH owners SHOULD make the WSDL
! document available from this URI. (And if a WSDL description is
! split into multiple documents, then the WSDL target namespace
should resolve to a master document that includes all the WSDL
documents needed for that service description.) However, there is
--- 714,722 ----
<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 master document that includes all the WSDL
documents needed for that service description.) However, there is
***************
*** 734,738 ****
id="example-empty-shell"
name="example-empty-shell"></a><i><span>Example 2-2.</span> An
! Initial Empty WSDL Document</i></p>
<div class="exampleInner">
--- 739,743 ----
id="example-empty-shell"
name="example-empty-shell"></a><i><span>Example 2-2.</span> An
! Initial Empty WSDL 2.0 Document</i></p>
<div class="exampleInner">
***************
*** 1054,1062 ****
<p>Interfaces are declared directly inside the
<code>description</code> element. In this example, we are declaring
! only one interface, but in general a WSDL document may declare more
! than one interface. Thus, each interface must be given a name that
! is unique within the set of interfaces defined in this WSDL target
! namespace. Interface names are tokens that must not contain a space
! or colon (":").</p>
</dd>
--- 1059,1067 ----
<p>Interfaces are declared directly inside the
<code>description</code> element. In this example, we are declaring
! only one interface, but in general a WSDL 2.0 document may declare
! more than one interface. Thus, each interface must be given a name
! that is unique within the set of interfaces defined in this WSDL
! target namespace. Interface names are tokens that must not contain
! a space or colon (":").</p>
</dd>
***************
*** 1227,1235 ****
Framework</a></cite>] and HTTP 1.1 [<cite><a href="#RFC2616">IETF
RFC 2616</a></cite>] as predefined extensions, so that SOAP 1.2 or
! HTTP 1.1 bindings can be easily defined in WSDL documents. However,
! other specifications could define new binding extensions that could
! also be used to define bindings. (As with any extension, other WSDL
! processors would have to know about the new constructs in order to
! make use of them.)</p>
<p>For the GreatH service, we will use SOAP 1.2 as our concrete
--- 1232,1240 ----
Framework</a></cite>] and HTTP 1.1 [<cite><a href="#RFC2616">IETF
RFC 2616</a></cite>] as predefined extensions, so that SOAP 1.2 or
! HTTP 1.1 bindings can be easily defined in WSDL 2.0 documents.
! However, other specifications could define new binding extensions
! that could also be used to define bindings. (As with any extension,
! other WSDL processors would have to know about the new constructs
! in order to make use of them.)</p>
<p>For the GreatH service, we will use SOAP 1.2 as our concrete
***************
*** 1562,1570 ****
<p>The <code>documentation</code> element allows the WSDL author to
! include some human-readable documentation inside a WSDL document.
! It is also a convenient place to reference any additional external
! documentation that a client developer may need in order to use the
! service. It can appear in a number of places in a WSDL 2.0 document
! (see <a href="#wsdl-infoset-diagram"><b>3.1 WSDL 2.0
Infoset</b></a>), though in this example we have only demonstrated
its use at the beginning.</p>
--- 1567,1575 ----
<p>The <code>documentation</code> element allows the WSDL author to
! include some human-readable documentation inside a WSDL 2.0
! document. It is also a convenient place to reference any additional
! external documentation that a client developer may need in order to
! use the service. It can appear in a number of places in a WSDL 2.0
! document (see <a href="#wsdl-infoset-diagram"><b>3.1 WSDL 2.0
Infoset</b></a>), though in this example we have only demonstrated
its use at the beginning.</p>
***************
*** 1859,1863 ****
<p>The WSDL 2.0 <code>types</code> element provides a mechanism for
! enclosing message schemas in a WSDL document. Because WSDL 2.0
directly supports schemas written in XML Schema [<cite><a
href="#XMLSchemaP1">XML Schema: Structures</a></cite>], we will
--- 1864,1868 ----
<p>The WSDL 2.0 <code>types</code> element provides a mechanism for
! enclosing message schemas in a WSDL 2.0 document. Because WSDL 2.0
directly supports schemas written in XML Schema [<cite><a
href="#XMLSchemaP1">XML Schema: Structures</a></cite>], we will
***************
*** 1945,1951 ****
points here.</p>
! <p>When XML Schema is embedded directly in a WSDL document, it uses
! the existing top-level <code>xs:schema</code> element defined by
! XML Schema [<cite><a href="#XMLSchemaP1">XML Schema:
Structures</a></cite>] to do so, as though the schema had been
copied and pasted into the <code>types</code> element. The schema
--- 1950,1956 ----
points here.</p>
! <p>When XML Schema is embedded directly in a WSDL 2.0 document, it
! uses the existing top-level <code>xs:schema</code> element defined
! by XML Schema [<cite><a href="#XMLSchemaP1">XML Schema:
Structures</a></cite>] to do so, as though the schema had been
copied and pasted into the <code>types</code> element. The schema
***************
*** 3388,3392 ****
<p>WSDL 2.0 provides two extensibility mechanisms: an open content
model, which allows XML elements and attributes from other
! (non-WSDL 2.0) XML namespaces to be interspersed into a WSDL
document; and <a
href="http://www.w3.org/TR/2004/WD-wsdl20-20040803#Feature">Features</a>
--- 3393,3397 ----
<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 <a
href="http://www.w3.org/TR/2004/WD-wsdl20-20040803#Feature">Features</a>
***************
*** 3697,3701 ****
any such values are up to the implementations of the
modules/bindings that use them. The <code>property</code> element
! can be placed at many different levels in a WSDL document (see
"Property Composition Model", section 2.8.1.1 in WSDL 2.0 Part 1
[<cite><a href="#WSDL-PART1">WSDL 2.0 Core
--- 3702,3706 ----
any such values are up to the implementations of the
modules/bindings that use them. The <code>property</code> element
! can be placed at many different levels in a WSDL 2.0 document (see
"Property Composition Model", section 2.8.1.1 in WSDL 2.0 Part 1
[<cite><a href="#WSDL-PART1">WSDL 2.0 Core
***************
*** 3971,3975 ****
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 document.</p>
</li>
--- 3976,3980 ----
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>
</li>
***************
*** 4568,4573 ****
useful. It is therefore natural to apply this capability to Web
services. This section describes <em>service references</em>, which
! are the Web service analogs of document hyperlinks. This will be
! illustrated by expanding the GreatH example already discussed.</p>
<div class="div3">
--- 4573,4587 ----
useful. It is therefore natural to apply this capability to Web
services. This section describes <em>service references</em>, which
! are the Web service analogs of document hyperlinks.</p>
!
! <p>One may wonder, from a Web architectural point of view, why
! anything more than a URI would be needed to reference a Web
! service. Indeed, a service reference does make use of a URI to
! indicate the endpoint address of a service. However, it may also
! include additional metadata about that service, such as the WSDL
! 2.0 interface and binding that the service supports.</p>
!
! <p>Services references will be illustrated by expanding the GreatH
! example already discussed.</p>
<div class="div3">
***************
*** 4890,4896 ****
<code>wdetails:reservationDetailsInterface</code> and
<code>wdetails:reservationDetailsSOAPBinding</code> . These QNames
! identify WSLD Interface and Binding components that are defined in
! a WSDL document. This example shows the use of the
! <code>wsdli:wsdlLocation</code> attribute to locate the WSDL
document. The address of each endpoint is the URI assigned to each
reservation.</p>
--- 4904,4910 ----
<code>wdetails:reservationDetailsInterface</code> and
<code>wdetails:reservationDetailsSOAPBinding</code> . These QNames
! identify WSDL 2.0 Interface and Binding components that are defined
! in a WSDL 2.0 document. This example shows the use of the
! <code>wsdli:wsdlLocation</code> attribute to locate the WSDL 2.0
document. The address of each endpoint is the URI assigned to each
reservation.</p>
***************
*** 4999,5003 ****
</div>
! <p><a href="#reservationList.xsd">Example 7-18</a>Shows the schema
for the messages used in the Reservation List Web service.</p>
--- 5013,5017 ----
</div>
! <p><a href="#reservationList.xsd">Example 7-18</a> shows the schema
for the messages used in the Reservation List Web service.</p>
***************
*** 5065,5078 ****
</div>
</div>
</div>
<div class="div2">
<h3><a id="adv-multiple-inline-schemas"
! name="adv-multiple-inline-schemas"></a>7.10 Multiple In-Line
! Schemas</h3>
!
! <p>@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
! @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
! @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@</p>
<table border="1" summary="Editorial note: Arthur">
--- 5079,5325 ----
</div>
</div>
+
+ <div class="div3">
+ <h4><a id="reservationDetails_HTTP"
+ name="reservationDetails_HTTP"></a>7.9.3 Reservation Details Web
+ Service Using HTTP Transfer</h4>
+
+ <p>This section presents a variation on the example in <a
+ href="#reservationDetails"><b>7.9.1 The Reservation Details Web
+ Service</b></a>. It illustrates the use of HTTP transfer
+ operations, GET and PUT, to retrieve and update GreatH hotel
+ reservation details using the Representational State Transfer
+ (REST) architectural style described by Roy Fielding @@bibref@@.
+ REST is a distillation of the architectural properties that Dr.
+ Fielding identified as being vital to the Web's robustness and
+ enormous scalabilty.</p>
+
+ <p>Since each reservation in our example will have a distinct URI,
+ the Reservation Details Web service can be offered using HTTP GET
+ and HTTP PUT. The binding would be modified as follows:</p>
+
+ <div class="exampleOuter">
+ <p style="text-align: left" class="exampleHead"><a
+ id="reservationDetails_HTTP_example"
+ name="reservationDetails_HTTP_example"></a><i><span>Example
+ 7-19.</span> Reservation Details Web Service Using HTTP
+ Transfer</i></p>
+
+ <table border="1" summary="Editorial note: dbooth">
+ <tr>
+ <td align="left" valign="top" width="50%"><b>Editorial note:
+ dbooth</b></td>
+ <td align="right" valign="top" width="50%">2005-04-15</td>
+ </tr>
+
+ <tr>
+ <td colspan="2" align="left" valign="top">ToDo: Check/fix this
+ example. Shouldn't it specify what protocol to use?</td>
+ </tr>
+ </table>
+
+ <div class="exampleInner">
+ <pre>
+ . . .
+ <binding name="reservationDetailsHTTPBinding"
+ interface="tns:reservationDetailsInterface" >
+
+ <operation ref="tns:retrieve"
+ whttp:method="GET" />
+
+ <operation ref="tns:update"
+ whttp:method="PUT" />
+
+ </binding>
+ . . .
+
+ </pre>
+ </div>
+ </div>
+
+ <p>As with the example in <a href="#reservationDetails"><b>7.9.1
+ The Reservation Details Web Service</b></a>, service and endpoint
+ elements are not provided because the Reservation List Web service
+ provides the endpoints.</p>
+ </div>
+
+ <div class="div3">
+ <h4><a id="reservationList_HTTP_GET"
+ name="reservationList_HTTP_GET"></a>7.9.4 Reservation List Web
+ Service Using HTTP GET</h4>
+
+ <p>This section continues the REST-style example of <a
+ href="#reservationDetails_HTTP"><b>7.9.3 Reservation Details Web
+ Service Using HTTP Transfer</b></a> by modifying the example of <a
+ href="#reservationList"><b>7.9.2 The Reservation List Web
+ Service</b></a> to use HTTP GET.</p>
+
+ <p>The SOAP version of the Reservation List Web service above
+ offers four different search operations. These can also be
+ expressed as various parameters in a URI used by HTTP GET:</p>
+
+ <div class="exampleOuter">
+ <p style="text-align: left" class="exampleHead"><a
+ id="example_reservationList_HTTP_GET"
+ name="example_reservationList_HTTP_GET"></a><i><span>Example
+ 7-20.</span> Reservation List Web Service Using HTTP GET</i></p>
+
+ <table border="1" summary="Editorial note: dbooth">
+ <tr>
+ <td align="left" valign="top" width="50%"><b>Editorial note:
+ dbooth</b></td>
+ <td align="right" valign="top" width="50%">2005-04-15</td>
+ </tr>
+
+ <tr>
+ <td colspan="2" align="left" valign="top">ToDo: Check/fix this
+ example. Shouldn't it specify what protocol to use?</td>
+ </tr>
+ </table>
+
+ <div class="exampleInner">
+ <pre>
+ . . .
+ <binding name="reservationListHTTPBinding"
+ interface="tns:reservationListInterface"
+ whttp:methodDefault="GET">
+
+ <operation ref="tns:retrieve"
+ whttp:location="" />
+
+ <operation ref="tns:retrieveByConfirmationNumber"
+ whttp:location="/ConfirmationNumber/{confirmationNumber/}" />
+
+ <operation ref="tns:retrieveByCheckInDate"
+ whttp:location="/CheckInDate/{checkInDate/}" />
+
+ <operation ref="tns:retrieveByCheckOutDate"
+ whttp:location="/CheckOutDate/{checkOutDate/}" />
+ </binding>
+ . . .
+ <service . . . >
+
+ <endpoint name="reservationListEndpoint"
+ binding="tns:reservationListHTTPBinding"
+ address="http://greath.example.com/2004/reservationList" />
+ . . .
+ </service>
+ . . .
+
+ </pre>
+ </div>
+ </div>
+
+ <p>A retrieval by Confirmation Number URI would look like:
+ <code>http://greath.example.com/2004/reservationList/ConfirmationNumber/HSG635
+ .</code></p>
+
+ <p>Alternatively, a single query type may be provided. This query
+ type is a sequence of optional items. Any items in the sequence are
+ serialized into the URI query string. A query sequence for any of
+ ConfirmationNumber, checkInDate, checkOutDate would look like
+ this:</p>
+
+ <div class="exampleOuter">
+ <p style="text-align: left" class="exampleHead"><a
+ id="example_reservationList_HTTP_GET_single"
+ name="example_reservationList_HTTP_GET_single"></a><i><span>Example
+ 7-21.</span> Query Sequence Using a Single Query Type</i></p>
+
+ <div class="exampleInner">
+ <pre>
+ <element name="reservationQuery">
+ <annotation>
+ <documentation>
+ A reservation contains the confirmation number, check-in
+ and check-out dates, and a reference to a Reservation
+ Details Web service.
+ </documentation>
+ </annotation>
+ <complexType>
+ <sequence>
+ <element ref="details:confirmationNumber" minOccurs="0"/>
+ <element ref="details:checkInDate" minOccurs="0"/>/>
+ <element ref="details:checkOutDate" minOccurs="0"/>/>
+ </sequence>
+ </sequence>
+ </complexType>
+ </element>
+
+ </pre>
+ </div>
+ </div>
+
+ <p>The WSDL service that offers this type serialized as a parameter
+ would look like this:</p>
+
+ <div class="exampleOuter">
+ <p style="text-align: left" class="exampleHead"><a
+ id="example_reservationList_HTTP_GET_single_wsdl"
+ name="example_reservationList_HTTP_GET_single_wsdl"></a><i><span>Example
+ 7-22.</span> WSDL for Using a Single Query Type</i></p>
+
+ <table border="1" summary="Editorial note: dbooth">
+ <tr>
+ <td align="left" valign="top" width="50%"><b>Editorial note:
+ dbooth</b></td>
+ <td align="right" valign="top" width="50%">2005-04-15</td>
+ </tr>
+
+ <tr>
+ <td colspan="2" align="left" valign="top">ToDo: Check/fix this
+ example. Shouldn't it specify what protocol to use?</td>
+ </tr>
+ </table>
+
+ <div class="exampleInner">
+ <pre>
+ . . .
+ <interface name="reservationListInterfaceWithQuery">
+
+ <operation name="retrieveByReservationQuery"
+ pattern="http://www.w3.org/2004/03/wsdl/in-out">
+ <input messageLabel="In"
+ element="details:ReservationQuery" />
+ <output messageLabel="Out"
+ element="list:reservationList" />
+ </operation>
+
+ </interface>
+
+ <binding name="reservationListQueryHTTPBinding"
+ interface="tns:reservationListInterfaceWithQuery"
+ whttp:methodDefault="GET">
+
+ <operation ref="tns:retrieveByReservationQuery"
+ whttp:location="/{ReservationQuery}}" />
+
+ </binding>
+
+ . . .
+ <endpoint name="reservationListEndpoint"
+ binding="tns:reservationListHTTPBinding"
+ address="http://greath.example.com/2004/reservationList" />
+ . . .
+
+ </pre>
+ </div>
+ </div>
+
+ <p>Various URIs would be:
+ <code>http://greath.example.com/2004/reservationList/ReservationQuery?confirmationNumber=HSG635</code>
+ <code>http://greath.example.com/2004/reservationList/ReservationQuery?checkInDate=06-06-05</code>
+ .</p>
+
+ <p>It is important to observe that using the URI serialization can
+ result in very flexible queries and few operations. The previous
+ discrete SOAP operations are collapsed into one "parameterized"
+ operation.</p>
+ </div>
</div>
<div class="div2">
<h3><a id="adv-multiple-inline-schemas"
! name="adv-multiple-inline-schemas"></a>7.10 Importing Schemas</h3>
<table border="1" summary="Editorial note: Arthur">
***************
*** 5084,5106 ****
<tr>
! <td colspan="2" align="left" valign="top">The cited discussion
! thread is about Schemas in imported WSDL, not Multiple In-Line
! Schemas. I will therefore include an example that addresses that
! topic of the thread, and an example that addresses the section
! title. BTW, I find the resolution of the thread to be very
! unsatisfactory since it doesn't nail down the expected behavior of
! a WSDL processor when the schemaLocation is omitted. I'd prefer the
! spec to say that a WSDL processor that encounters an inline schema
! MUST remember that fact and use it to locate the schema should it
! appear in an import element without a schemaLocation.</td>
</tr>
</table>
- <p>[Need to explain that this can be done. See
- http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0109.html
- http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0126.html
- http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0130.html
- ]</p>
-
<p>WSDL 2.0 documents may contain one or more XML schemas defined
within the <code>wsdl:types</code> element. This section
--- 5331,5344 ----
<tr>
! <td colspan="2" align="left" valign="top">I find the resolution of
! the thread to be very unsatisfactory since it doesn't nail down the
! expected behavior of a WSDL processor when the schemaLocation is
! omitted. I'd prefer the spec to say that a WSDL processor that
! encounters an inline schema MUST remember that fact and use it to
! locate the schema should it appear in an import element without a
! schemaLocation.</td>
</tr>
</table>
<p>WSDL 2.0 documents may contain one or more XML schemas defined
within the <code>wsdl:types</code> element. This section
***************
*** 5113,5127 ****
<p>In this example, we consider some GreatH Hotel Web services that
retrieve and update reservation details. The retrieval Web service
! is defined in the <code>retrieveDetails.wsdl</code> WSDL document,
! along with a schema for the message format. The updating Web
! service is defined in the <code>updateDetails.wsdl</code> WSDL
! document which imports the first document and refers to both WSDL
! and schema definitions contained in the imported document.</p>
! <p><a href="#retrieveDetails.wsdl">Example 7-19</a> shows the
definition of the retrieval Web service in the
<code>http://greath.example.com/2004/services/retrieveDetails</code>
! namespace. This WSDL document also contains an inline schema that
! describes the reservation detail in the
<code>http://greath.example.com/2004/schemas/reservationDetails</code>
namespace. This schema is visible to the
--- 5351,5365 ----
<p>In this example, we consider some GreatH Hotel Web services that
retrieve and update reservation details. The retrieval Web service
! is defined in the <code>retrieveDetails.wsdl</code> WSDL 2.0
! document, along with a schema for the message format. The updating
! Web service is defined in the <code>updateDetails.wsdl</code> WSDL
! 2.0 document which imports the first document and refers to both
! WSDL and schema definitions contained in the imported document.</p>
! <p><a href="#retrieveDetails.wsdl">Example 7-23</a> shows the
definition of the retrieval Web service in the
<code>http://greath.example.com/2004/services/retrieveDetails</code>
! namespace. This WSDL 2.0 document also contains an inline schema
! that describes the reservation detail in the
<code>http://greath.example.com/2004/schemas/reservationDetails</code>
namespace. This schema is visible to the
***************
*** 5133,5137 ****
<p style="text-align: left" class="exampleHead"><a
id="retrieveDetails.wsdl"
! name="retrieveDetails.wsdl"></a><i><span>Example 7-19.</span> The
Retrieve Reservation Details Web Service:
retrieveDetails.wsdl</i></p>
--- 5371,5375 ----
<p style="text-align: left" class="exampleHead"><a
id="retrieveDetails.wsdl"
! name="retrieveDetails.wsdl"></a><i><span>Example 7-23.</span> The
Retrieve Reservation Details Web Service:
retrieveDetails.wsdl</i></p>
***************
*** 5187,5191 ****
</div>
! <p><a href="#updateDetails.wsdl">Example 7-20</a> shows the
definition of the updating Web service in the
<code>http://greath.example.com/2004/services/updateDetails</code>
--- 5425,5429 ----
</div>
! <p><a href="#updateDetails.wsdl">Example 7-24</a> shows the
definition of the updating Web service in the
<code>http://greath.example.com/2004/services/updateDetails</code>
***************
*** 5214,5222 ****
namespace. However, the WSDL processor has already processed the
<code>retrieveDetails.wsdl</code> document which contains the
! imported namespace in an inline schema so it should not any hints.
! However, this behavior depends on the implementation of the
processor and so cannot be relied on.</p>
! <p>Although the WSDL document may validly omit the
<code>schemaLocation</code> attribute, it is a best practice to
either provide a reliable value for it or move the inline schema
--- 5452,5460 ----
namespace. However, the WSDL processor has already processed the
<code>retrieveDetails.wsdl</code> document which contains the
! imported namespace in an inline schema so it should not need any
! hints. However, this behavior depends on the implementation of the
processor and so cannot be relied on.</p>
! <p>Although the WSDL 2.0 document may validly omit the
<code>schemaLocation</code> attribute, it is a best practice to
either provide a reliable value for it or move the inline schema
***************
*** 5225,5230 ****
<code>retrieveDetails.wsdl</code> and
<code>updateDetails.wsdl</code>. In general, schemas that are
! expected to be referenced from more than one WSDL document should
! be defined in a separate schema document rather than be
inlined.</p>
--- 5463,5468 ----
<code>retrieveDetails.wsdl</code> and
<code>updateDetails.wsdl</code>. In general, schemas that are
! expected to be referenced from more than one WSDL 2.0 document
! should be defined in a separate schema document rather than be
inlined.</p>
***************
*** 5232,5236 ****
<p style="text-align: left" class="exampleHead"><a
id="updateDetails.wsdl"
! name="updateDetails.wsdl"></a><i><span>Example 7-20.</span> The
Update Reservation Details Web Service: updateDetails.wsdl</i></p>
--- 5470,5474 ----
<p style="text-align: left" class="exampleHead"><a
id="updateDetails.wsdl"
! name="updateDetails.wsdl"></a><i><span>Example 7-24.</span> The
Update Reservation Details Web Service: updateDetails.wsdl</i></p>
***************
*** 5279,5285 ****
<div class="div3">
! <h4>7.10.2 Multiple Inline Schemas on One Document</h4>
! <p>A WSDL document may define multiple inline schemas in its
<code>types</code> element. The two or more schemas may have the
same target namespace provided that they do not define the same
--- 5517,5523 ----
<div class="div3">
! <h4>7.10.2 Multiple Inline Schemas in One Document</h4>
! <p>A WSDL 2.0 document may define multiple inline schemas in its
<code>types</code> element. The two or more schemas may have the
same target namespace provided that they do not define the same
***************
*** 5296,5300 ****
<p>To illustrate this, consider <a
! href="#retrieveItems.wsdl">Example 7-21</a> which contains two
inline schemas. The
<code>http://greath.example.com/2004/schemas/reservationItems</code>
--- 5534,5538 ----
<p>To illustrate this, consider <a
! href="#retrieveItems.wsdl">Example 7-25</a> which contains two
inline schemas. The
<code>http://greath.example.com/2004/schemas/reservationItems</code>
***************
*** 5314,5318 ****
<p style="text-align: left" class="exampleHead"><a
id="retrieveItems.wsdl"
! name="retrieveItems.wsdl"></a><i><span>Example 7-21.</span>
Multiple Inline Schemas: retrieveItems.wsdl</i></p>
--- 5552,5556 ----
<p style="text-align: left" class="exampleHead"><a
id="retrieveItems.wsdl"
! name="retrieveItems.wsdl"></a><i><span>Example 7-25.</span>
Multiple Inline Schemas: retrieveItems.wsdl</i></p>
***************
*** 5380,5420 ****
</div>
</div>
- </div>
-
- <div class="div2">
- <h3><a id="adv-schema-location" name="adv-schema-location"></a>7.11
- The schemaLocation Attribute</h3>
! <table border="1" summary="Editorial note: Arthur">
! <tr>
! <td align="left" valign="top" width="50%"><b>Editorial note:
! Arthur</b></td>
! <td align="right" valign="top" width="50%">20050329</td>
! </tr>
!
! <tr>
! <td colspan="2" align="left" valign="top">Here is my input.</td>
! </tr>
! </table>
!
! <p>[ACTION: 2003-11-13: David to add discussion / example(s) re:
! @schemaLocation for embedded schemas to the primer. See discussion
! in
! http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0135.html
! and thread called "Schemas in imported WSDL" in
! http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/thread.html
! ]</p>
! <p>In the preceeding examples, schemas were defined inline in WSDL
! documents. This section discusses the correct way to specify a
<code>schemaLocation</code> attribute on a schema
<code>import</code> element to provide a processor with a hint for
locating these schemas.</p>
! <p><a href="#updateDetails.wsdl">Example 7-20</a> shows how one
! WSDL document imports a schema defined in another, i.e. <a
! href="#retrieveDetails.wsdl">Example 7-19</a>. Similarly, <a
! href="#retrieveItems.wsdl">Example 7-21</a> shows how one schema in
! a WSDL document imports another schema defined in the same
document. In both of these examples, the
<code>schemaLocation</code> attribute was omitted since the WSDL
--- 5618,5638 ----
</div>
</div>
! <div class="div3">
! <h4><a id="adv-schema-location"
! name="adv-schema-location"></a>7.10.3 The schemaLocation
! Attribute</h4>
! <p>In the preceding examples, schemas were defined inline in WSDL
! 2.0 documents. This section discusses the correct way to specify a
<code>schemaLocation</code> attribute on a schema
<code>import</code> element to provide a processor with a hint for
locating these schemas.</p>
! <p><a href="#updateDetails.wsdl">Example 7-24</a> shows how one
! WSDL 2.0 document imports a schema defined in another, i.e. <a
! href="#retrieveDetails.wsdl">Example 7-23</a>. Similarly, <a
! href="#retrieveItems.wsdl">Example 7-25</a> shows how one schema in
! a WSDL 2.0 document imports another schema defined in the same
document. In both of these examples, the
<code>schemaLocation</code> attribute was omitted since the WSDL
***************
*** 5429,5436 ****
XPointer can also be used.</p>
! <div class="div3">
! <h4>7.11.1 Using the id Attribute to Identify Inline Schemas</h4>
! <p><a href="#schemaIds.wsdl">Example 7-22</a> shows the use of the
<code>id</code> attribute. Both of the inline schemas have
<code>id</code> attributes. The id of the
--- 5647,5654 ----
XPointer can also be used.</p>
! <div class="div4">
! <h5>7.10.3.1 Using the id Attribute to Identify Inline Schemas</h5>
! <p><a href="#schemaIds.wsdl">Example 7-26</a> shows the use of the
<code>id</code> attribute. Both of the inline schemas have
<code>id</code> attributes. The id of the
***************
*** 5449,5453 ****
<p style="text-align: left" class="exampleHead"><a
id="schemaIds.wsdl" name="schemaIds.wsdl"></a><i><span>Example
! 7-22.</span> Using Ids in Inline Schemas: schemaIds.wsdl</i></p>
<div class="exampleInner">
--- 5667,5671 ----
<p style="text-align: left" class="exampleHead"><a
id="schemaIds.wsdl" name="schemaIds.wsdl"></a><i><span>Example
! 7-26.</span> Using Ids in Inline Schemas: schemaIds.wsdl</i></p>
<div class="exampleInner">
***************
*** 5518,5529 ****
</div>
</div>
<div class="div2">
! <h3><a id="adv-rdf-mapping" name="adv-rdf-mapping"></a>7.12 Mapping
to RDF and Semantic Web</h3>
</div>
<div class="div2">
! <h3><a id="adv-notes-on-uris" name="adv-notes-on-uris"></a>7.13
Notes on URIs</h3>
--- 5736,5752 ----
</div>
</div>
+ </div>
<div class="div2">
! <h3><a id="adv-rdf-mapping" name="adv-rdf-mapping"></a>7.11 Mapping
to RDF and Semantic Web</h3>
+
+ <p>@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@</p>
</div>
<div class="div2">
! <h3><a id="adv-notes-on-uris" name="adv-notes-on-uris"></a>7.12
Notes on URIs</h3>
***************
*** 5534,5538 ****
<div class="div3">
<h4><a id="adv-namespaces-and-schema-locations"
! name="adv-namespaces-and-schema-locations"></a>7.13.1 XML
Namespaces and Schema Locations</h4>
--- 5757,5761 ----
<div class="div3">
<h4><a id="adv-namespaces-and-schema-locations"
! name="adv-namespaces-and-schema-locations"></a>7.12.1 XML
Namespaces and Schema Locations</h4>
***************
*** 5552,5556 ****
<div class="div3">
! <h4><a id="adv-relative-uris" name="adv-relative-uris"></a>7.13.2
Relative URIs</h4>
--- 5775,5779 ----
<div class="div3">
! <h4><a id="adv-relative-uris" name="adv-relative-uris"></a>7.12.2
Relative URIs</h4>
***************
*** 5565,5576 ****
<div class="div3">
<h4><a id="adv-generating-uris"
! name="adv-generating-uris"></a>7.13.3 Generating Temporary
URIs</h4>
! <p>In general, when a WSDL 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
--- 5788,5799 ----
<div class="div3">
<h4><a id="adv-generating-uris"
! name="adv-generating-uris"></a>7.12.3 Generating Temporary
URIs</h4>
! <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
Received on Monday, 18 April 2005 07:39:27 UTC