- From: David Booth via cvs-syncmail <cvsmail@w3.org>
- Date: Mon, 18 Apr 2005 04:09:19 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20 In directory hutz:/tmp/cvs-serv10628 Modified Files: wsdl20-primer.xml wsdl20-primer.html Log Message: Finished editing/updating through sec 7.9 (Service References). Index: wsdl20-primer.xml =================================================================== RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v retrieving revision 1.55 retrieving revision 1.56 diff -C2 -d -r1.55 -r1.56 *** wsdl20-primer.xml 18 Apr 2005 03:25:11 -0000 1.55 --- wsdl20-primer.xml 18 Apr 2005 04:09:17 -0000 1.56 *************** *** 411,415 **** </xspecref>.) </p> ! </def></gitem><gitem><label><code>wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response"></code></label><def><p>This attribute is also specific to WSDL 2.0's SOAP binding extension. It specifies the SOAP message exchange pattern that will be used to implement the abstract WSDL 2.0 message exchange pattern (<xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref>) that was specified when the <code>opCheckAvailability</code> operation was defined. </p></def></gitem><gitem><label><code><fault ref="tns:invalidDataFault"</code></label><def><p>As with a binding operation, this is not declaring a new fault; rather, it is referencing a fault (<code>invalidDataFault</code>) that was previously defined in the <code>opCheckAvailability</code> interface, in order to specify binding details for it.</p></def></gitem><gitem><label><code>wsoap:code="soap:Sender"/></code></label><def><p>This attribute is also specific to WSDL 2.0's SOAP binding extension. This specifies the SOAP 1.2 fault code that will cause this fault message to be sent. If desired, a list of subcodes can also be specified using the optional <att>wsoap:subcodes</att> attribute.</p></def></gitem></glist></div3></div2><div2 id="basics-service"><head>Defining a Service</head><p>Now that our binding has specified <emph>how</emph> messages will be transmitted, we are ready to specify <emph>where</emph> the service can be accessed, by use of the <code>service</code> element. </p><p>A WSDL 2.0 <emph>service</emph> specifies a single interface that the service will support, and a list of <emph>endpoint</emph> locations where that service can be accessed. Each endpoint must also reference a previously defined binding to indicate what protocols and transmission formats are to be used at that endpoint. A service is only permitted to have one interface. (See <specref ref="adv-multiple-docs-describing-same-service"/> for further discussion of this limitation.) </p><p>Here is a definition fo our GreatH service.</p><example id="example-initial-service"> <head>GreatH Service Definition</head> <eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?> --- 411,415 ---- </xspecref>.) </p> ! </def></gitem><gitem><label><code>wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response"></code></label><def><p>This attribute is also specific to WSDL 2.0's SOAP binding extension. It specifies the SOAP message exchange pattern (MEP) that will be used to implement the abstract WSDL 2.0 message exchange pattern (<xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref>) that was specified when the <code>opCheckAvailability</code> operation was defined. </p><p>When HTTP is used as the underlying transport protocol (as in this example) the <code>wsoap:mep</code> attribute also controls whether GET or POST will be used as the underlying HTTP method. See also <specref ref="adv-get-vs-post"/>.</p></def></gitem><gitem><label><code><fault ref="tns:invalidDataFault"</code></label><def><p>As with a binding operation, this is not declaring a new fault; rather, it is referencing a fault (<code>invalidDataFault</code>) that was previously defined in the <ode>opCheckAvailability</code> interface, in order to specify binding details for it.</p></def></gitem><gitem><label><code>wsoap:code="soap:Sender"/></code></label><def><p>This attribute is also specific to WSDL 2.0's SOAP binding extension. This specifies the SOAP 1.2 fault code that will cause this fault message to be sent. If desired, a list of subcodes can also be specified using the optional <att>wsoap:subcodes</att> attribute.</p></def></gitem></glist></div3></div2><div2 id="basics-service"><head>Defining a Service</head><p>Now that our binding has specified <emph>how</emph> messages will be transmitted, we are ready to specify <emph>where</emph> the service can be accessed, by use of the <code>service</code> element. </p><p>A WSDL 2.0 <emph>service</emph> specifies a single interface that the service will support, and a list of <emph>endpoint</emph> locations where that service can be accessed. Each endpoint must also reference a previously defined binding to indicate what protocols an transmission formats are to be used at that endpoint. A service is only permitted to have one interface. (See <specref ref="adv-multiple-docs-describing-same-service"/> for further discussion of this limitation.) </p><p>Here is a definition for our GreatH service.</p><example id="example-initial-service"> <head>GreatH Service Definition</head> <eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?> *************** *** 982,993 **** - <ednote> - <name>KevinL</name> - <date>20050310</date> - <edtext>Incoporated contribution from Asir. Need to check back this section for integration with rest of document. - </edtext> - </ednote> ! <p>The WSDL 2.0 SOAP Binding Extension (see WSDL 2.0 Part 2 <bibref ref="WSDL-PART2"/>) was primarily designed to support the features of SOAP 1.2 <bibref ref="SOAP12-PART1"/>. However, for backwards compatibility, it also provides some support for SOAP 1.1 <bibref ref="SOAP11"/>. </p><p>An example using the WSDL 2.0 SOAP binding extension was already presented in <specref ref="basics-binding"/>, but some additional points are worth mentioning:<ulist><item><p>Because the same binding extension is used for both SOAP 1.2 and SOAP 1.1, a <code>wsoap:version</code> attribute is provided to allow you to indicate which version of SOAP you want. If this attribute is not specified, it defaults to SOAP 1.2.</p></item><item><p>The WSDL 2.0 SOAP binding extension defines a set of default rules, so that bindings can be specified at the interface level or at the operation level (or both), with the operation level taking precedence. However, it does not define default binding rules for faults. Thus, if a iven interface defines any faults, then corresponding binding infomation must be explicitly provided for each such fault.</p></item></ulist></p><p>Here is an example that illustrates both a SOAP 1.2 binding (as seen before) and a SOAP 1.1 binding.</p><example id="example-binding-soap"> <head>SOAP 1.2 and SOAP 1.1 Bindings</head> --- 982,988 ---- ! ! <p>The WSDL 2.0 SOAP Binding Extension (see WSDL 2.0 Part 2 <bibref ref="WSDL-PART2"/>) was primarily designed to support the features of SOAP 1.2 <bibref ref="SOAP12-PART1"/>. However, for backwards compatibility, it also provides some support for SOAP 1.1 <bibref ref="SOAP11"/>. </p><p>An example using the WSDL 2.0 SOAP binding extension was already presented in <specref ref="basics-binding"/>, but some additional points are worth mentioning:<ulist><item><p>Because the same binding extension is used for both SOAP 1.2 and SOAP 1.1, a <code>wsoap:version</code> attribute is provided to allow you to indicate which version of SOAP you want. If this attribute is not specified, it defaults to SOAP 1.2.</p></item><item><p>The WSDL 2.0 SOAP binding extension defines a set of default rules, so that bindings can be specified at the interface level or at the operation level (or both), with the operation level taking precedence. However, it does not define default binding rules for faults. Thus, if a iven interface defines any faults, then corresponding binding infomation must be explicitly provided for each such fault.</p></item><item><p>If HTTP is used as the underlying protocol, then the binding can (and should) control whether each operation will use HTTP GET or POST. (See <specref ref="adv-get-vs-post"/>.)</p></item></ulist></p><p>Here is an example that illustrates both a SOAP 1.2 binding (as seen before) and a SOAP 1.1 binding.</p><example id="example-binding-soap"> <head>SOAP 1.2 and SOAP 1.1 Bindings</head> *************** *** 1061,1065 **** ! <div3 id="more-bindings-soap-example-explanation"><head>Explanation of Example</head><p>Most of this example is the same as previously explained in <specref ref="basics-binding"/>, so we'll only point out lines that are demonstrating something new.<glist><gitem><label><code>xmlns:soap11="http://schemas.xmlsoap.org/soap/envelope/"></code></label><def><p>This is the namespace for terms defined within the SOAP 1.1 specification <bibref ref="SOAP11"/>.</p></def></gitem><gitem><label><code>wsoap:version="1.1"</code></label><def><p>This line indicates that this binding uses SOAP 1.1, rather than SOAP 1.2.</p></def></gitem><gitem><label><code>wsoap:protocol="http://www.w3.org/@@@@/@@/soap11/bindings/HTTP"></code></label><def><p>This line specifies that HTTP should be used as the underlying transmission protocol.</p></def></gitem><gitem><label><code>wsoap:code="soap11:Client"/></code></label><def><p>This line specifies the SOAP 1.1 fault code that will be used in transmitting invalidDataFault.</p></df></gitem></glist></p> </div3></div2> --- 1056,1060 ---- ! <div3 id="more-bindings-soap-example-explanation"><head>Explanation of Example</head><p>Most of this example is the same as previously explained in <specref ref="basics-binding"/>, so we'll only point out lines that are demonstrating something new.<glist><gitem><label><code>xmlns:soap11="http://schemas.xmlsoap.org/soap/envelope/"></code></label><def><p>This is the namespace for terms defined within the SOAP 1.1 specification <bibref ref="SOAP11"/>.</p></def></gitem><gitem><label><code>wsoap:version="1.1"</code></label><def><p>This line indicates that this binding uses SOAP 1.1, rather than SOAP 1.2.</p></def></gitem><gitem><label><code>wsoap:protocol="http://www.w3.org/@@@@/@@/soap11/bindings/HTTP"></code></label><def><p>This line specifies that HTTP should be used as the underlying transmission protocol. See also <specref ref="adv-get-vs-post"/>.</p></def></gitem><gitem><label><code>wsoap:code="soap11:Client"/></code></label><def><p>This line specifies the SOAP 1.1 fault code that will be ued in transmitting invalidDataFault.</p></def></gitem></glist></p> </div3></div2> *************** *** 1117,1121 **** This would instead serialize to a request URI such as: <code>http://greath.example.com/2004/bycheckInDate/5-5-5</code></p></div3></div2> ! </div1> --- 1112,1118 ---- This would instead serialize to a request URI such as: <code>http://greath.example.com/2004/bycheckInDate/5-5-5</code></p></div3></div2> ! <div2 id="adv-get-vs-post"><head>HTTP GET Versus POST: Which to Use?</head> ! <p> When a binding using HTTP is specified for an operation, the WSDL 2.0 author must decide which HTTP method is appropriate to use -- usually a choice between GET and POST. In the context of the Web as a whole (rather than specifically Web services), the W3C Technical Architecture Group (TAG) has address the question of when it is appropriate to use GET, versus when to use POST, in a finding entitled <emph>URIs, Addressability, and the use of HTTP GET and POST</emph> @@bibref@@. From the abstract:</p><p><quote><emph>. . . designers should adopt [GET] for safe operations such as simple queries. POST is appropriate for other types of applications where a user request has the potential to change the state of the resource (or of related resources). The finding explains how to choose between HTTP GET and POST for an application taking into account architectural, security, and practical considerations.</emph></quote></p><p>Recall that the concept of a safe operation (i.e., invocation does not causenew obligations) was discussed in <specref ref="more-interfaces-op-attr"/>. Although the <code>safe</code> attribute of an interface operation indicates that the abstract operation is safe, it does not automatically cause GET to be used at the HTTP level when the binding is specified. The choice of GET or POST is determined at the binding level: </p><ulist><item><p>If the WSDL 2.0 SOAP binding extension is used (<specref ref="more-bindings-soap"/>), with HTTP as the underlying transport protocol, then GET may be specified by setting:<glist><gitem><label><code>wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP"</code></label><def><p>on the <code>binding</code> element (to indicate the use of HTTP as the underlying protocol); and</p></def></gitem><gitem><label><code>wsoap:mep="http://www.w3.org/2003/05/soap/mep/soap-response/"</code></label><def><p>on the binding <code>operation</code> element, which causes GET to be used by default.</p></def></gitem></glist> </p></item><item><p>If the WSDL 2.0 TTP binding extension is used directly (<specref ref="more-bindings-http"/>), GET may be specified by setting either:<glist><gitem><label><code>whttp:methodDefault="GET"</code></label><def><p>on the <code>binding</code> element; or</p></def></gitem><gitem><label><code>whttp:method="GET"</code></label><def><p>on the binding <code>operation</code> element, which overrides <code>whttp:methodDefault</code> if set on the <code>binding</code> element.</p></def></gitem></glist></p></item></ulist> ! </div2></div1> *************** *** 1632,1651 **** <ulist><item><p><b>Use unique top-level elements</b>, i.e., ensure that the top-level elements declared in the message schemas are different for different operations. This is probably the most general solution, since it is guaranteed to provide a way to perform dispatch, without preventing toolkits from potentially using other dispatch techniques.</p></item><item><p><b>Include a required extension</b> that enables a particular dispatching convention. This approach makes the dispatching convention explicit, although it may not be supported by every WSDL toolkit. However, as explained in <specref ref="adv-optional-versus-required"/>, toolkits that do not natively support the extension could seek manual input, thus permitting a client developer to supply an appropriate module that implements the necessary extension. This strategy has thus permits future WSDL toolkits to support and process the extension automatically, while also ensuring that the extension will be handled properly by toolkits that re not yet able to process it automatically.</p></item></ulist> <p>To ensure that client and service implementations can easily determine the interface operation under which a received message was sent (even though not every client or service may need to make such a determination), it is considered good practice to follow one of the above strategies when authoring WSDL 2.0 documents.</p> - </div2><div2 id="adv-get-vs-post"><head>GET Versus POST: Which to Use?</head> - <p> When a binding using HTTP is specified for an operation, the WSDL 2.0 author must decide which HTTP method is appropriate to use -- usually a choice between GET and POST. In the context of the Web as a whole (rather than specifically Web services), the W3C Technical Architecture Group (TAG) has address the question of when it is appropriate to use GET, versus when to use POST, in a finding entitled <emph>URIs, Addressability, and the use of HTTP GET and POST</emph> @@bibref@@. From the abstract:</p><p><quote><emph>. . . designers should adopt [GET] for safe operations such as simple queries. POST is appropriate for other types of applications where a user request has the potential to change the state of the resource (or of related resources). The finding explains how to choose between HTTP GET and POST for an application taking into account architectural, security, and practical considerations.</emph></quote></p><p>Recall that the concept of a safe operation (i.e., invocation does not causenew obligations) was discussed in <specref ref="more-interfaces-op-attr"/>. Although the <code>safe</code> attribute of an interface operation indicates that the abstract operation is safe, it does not automatically cause GET to be used at the HTTP level when the binding is specified. The choice of GET or POST is determined at the binding level: </p><ulist><item><p>If the WSDL 2.0 SOAP binding extension is used (<specref ref="more-bindings-soap"/>), with HTTP as the underlying transport protocol, then GET may be specified by setting:<glist><gitem><label><code>wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP"</code></label><def><p>on the <code>binding</code> element (to indicate the use of HTTP as the underlying protocol); and</p></def></gitem><gitem><label><code>wsoap:mep="http://www.w3.org/2003/05/soap/mep/soap-response/"</code></label><def><p>on the binding <code>operation</code> element, which causes GET to be used by default.</p></def></gitem></glist> </p></item><item><p>If the WSDL 2.0 TTP binding extension is used directly (<specref ref="more-bindings-http"/>), GET may be specified by setting either:<glist><gitem><label><code>whttp:methodDefault="GET"</code></label><def><p>on the <code>binding</code> element; or</p></def></gitem><gitem><label><code>whttp:method="GET"</code></label><def><p>on the binding <code>operation</code> element, which overrides <code>whttp:methodDefault</code> if set on the <code>binding</code> element.</p></def></gitem></glist></p></item></ulist><p> </p> </div2> <div2 id="adv-service-references"> <head>Service References</head> ! <ednote> ! <name>Arthur</name> ! <date>20050326</date> ! <edtext> ! This is the first draft. Please review. ! The source for all the examples is in the test suite. ! See <loc href="http://dev.w3.org/cvsweb/2002/ws/desc/test-suite/documents/good/ServiceReference-1G/">ServiceReference-1G</loc>. ! </edtext> ! </ednote> ! <p>[Use http://lists.w3.org/Archives/Public/www-ws-desc/2003Oct/0345.html as a starting point. Also example(s) from Roberto per the resolution at the end of http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0061.html ]</p> <p> --- 1629,1638 ---- <ulist><item><p><b>Use unique top-level elements</b>, i.e., ensure that the top-level elements declared in the message schemas are different for different operations. This is probably the most general solution, since it is guaranteed to provide a way to perform dispatch, without preventing toolkits from potentially using other dispatch techniques.</p></item><item><p><b>Include a required extension</b> that enables a particular dispatching convention. This approach makes the dispatching convention explicit, although it may not be supported by every WSDL toolkit. However, as explained in <specref ref="adv-optional-versus-required"/>, toolkits that do not natively support the extension could seek manual input, thus permitting a client developer to supply an appropriate module that implements the necessary extension. This strategy has thus permits future WSDL toolkits to support and process the extension automatically, while also ensuring that the extension will be handled properly by toolkits that re not yet able to process it automatically.</p></item></ulist> <p>To ensure that client and service implementations can easily determine the interface operation under which a received message was sent (even though not every client or service may need to make such a determination), it is considered good practice to follow one of the above strategies when authoring WSDL 2.0 documents.</p> </div2> <div2 id="adv-service-references"> <head>Service References</head> ! ! <p> *************** *** 1655,1668 **** natural to apply this capability to Web services. This section describes ! <emph>service references</emph> which are the Web service analogs of document hyperlinks. ! </p> ! <p>@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@</p><div3 id="reservationDetails"><head>The Reservation Details Web Service</head> <p> When designing a Web application it is natural to ! give each important concept a URI. In the hotel reservation system, the important concepts are reservations, so we begin our design by assigning a --- 1642,1655 ---- natural to apply this capability to Web services. This section describes ! <emph>service references</emph>, 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> <p> When designing a Web application it is natural to ! give each important concept a URI. In the GreatH hotel reservation system, the important concepts are reservations, so we begin our design by assigning a *************** *** 1966,1971 **** </reservation> ! </reservationList>]]> ! </eg> </example> --- 1953,1957 ---- </reservation> ! </reservationList>]]></eg> </example> *************** *** 2158,2167 **** </div2> ! <div2 id="adv-xml-schema-examples"><head>XML Schema Examples</head> ! <p>[Add Paul Downey's contribution at http://lists.w3.org/Archives/Public/www-ws-desc/2004May/0007.html ]</p> ! </div2> <div2 id="adv-multiple-inline-schemas"> <head>Multiple In-Line Schemas</head> ! <ednote> <name>Arthur</name> <date>20050329</date> --- 2144,2151 ---- </div2> ! <div2 id="adv-multiple-inline-schemas"> <head>Multiple In-Line Schemas</head> ! <p>@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@</p><ednote> <name>Arthur</name> <date>20050329</date> Index: wsdl20-primer.html =================================================================== RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.html,v retrieving revision 1.36 retrieving revision 1.37 diff -C2 -d -r1.36 -r1.37 *** wsdl20-primer.html 18 Apr 2005 03:25:11 -0000 1.36 --- wsdl20-primer.html 18 Apr 2005 04:09:17 -0000 1.37 *************** *** 277,287 **** href="#more-interfaces-op-attr">Operation Attributes</a><br />         5.4.2 <a ! href="#id5208344">Operation Message References</a><br />             5.4.2.1 ! <a href="#id5208397">The messageLabel Attribute</a><br />             5.4.2.2 ! <a href="#id5208433">The element Attribute</a><br />             5.4.2.3 ! <a href="#id5208497">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="#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 *************** *** 308,312 **** Binding Extension</a><br />         6.6.1 <a ! href="#id5209846">Explanation of Example</a><br /> 7. <a href="#advanced-topic_ii">Advanced Topics</a><br />     7.1 <a --- 308,314 ---- 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 /> 7. <a href="#advanced-topic_ii">Advanced Topics</a><br />     7.1 <a *************** *** 348,384 **** href="#adv-message-dispatch">Enabling Easy Message Dispatch</a><br /> !     7.9 <a href="#adv-get-vs-post">GET Versus ! POST: Which to Use?</a><br /> !     7.10 <a href="#adv-service-references">Service References</a><br /> !         7.10.1 <a href="#reservationDetails">The Reservation Details Web Service</a><br /> !         7.10.2 <a href="#reservationList">The Reservation List Web Service</a><br /> !     7.11 <a href="#adv-xml-schema-examples">XML ! Schema Examples</a><br /> !     7.12 <a href="#adv-multiple-inline-schemas">Multiple In-Line Schemas</a><br /> !         7.12.1 <a ! href="#id5213157">Schemas in Imported Documents</a><br /> !         7.12.2 <a ! href="#id5213460">Multiple Inline Schemas on One Document</a><br /> !     7.13 <a href="#adv-schema-location">The schemaLocation Attribute</a><br /> !         7.13.1 <a ! href="#id5213768">Using the id Attribute to Identify Inline Schemas</a><br /> !     7.14 <a href="#adv-rdf-mapping">Mapping to RDF and Semantic Web</a><br /> !     7.15 <a href="#adv-notes-on-uris">Notes on URIs</a><br /> !         7.15.1 <a href="#adv-namespaces-and-schema-locations">XML Namespaces and Schema Locations</a><br /> !         7.15.2 <a href="#adv-relative-uris">Relative URIs</a><br /> !         7.15.3 <a href="#adv-generating-uris">Generating Temporary URIs</a><br /> 8. <a href="#References">References</a><br /> --- 350,382 ---- href="#adv-message-dispatch">Enabling Easy Message Dispatch</a><br /> !     7.9 <a href="#adv-service-references">Service References</a><br /> !         7.9.1 <a href="#reservationDetails">The Reservation Details Web Service</a><br /> !         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 /> *************** *** 1390,1399 **** <dd> <p>This attribute is also specific to WSDL 2.0's SOAP binding ! extension. It specifies the SOAP message exchange pattern that will ! be used to implement the abstract WSDL 2.0 message exchange pattern ! (<a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out"> in-out</a>) that was specified when the <code>opCheckAvailability</code> operation was defined.</p> </dd> --- 1388,1403 ---- <dd> <p>This attribute is also specific to WSDL 2.0's SOAP binding ! extension. It specifies the SOAP message exchange pattern (MEP) ! that will be used to implement the abstract WSDL 2.0 message ! exchange pattern (<a href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out"> in-out</a>) that was specified when the <code>opCheckAvailability</code> operation was defined.</p> + + <p>When HTTP is used as the underlying transport protocol (as in + this example) the <code>wsoap:mep</code> attribute also controls + whether GET or POST will be used as the underlying HTTP method. See + also <a href="#adv-get-vs-post"><b>6.7 HTTP GET Versus POST: Which + to Use?</b></a>.</p> </dd> *************** *** 2953,2970 **** The SOAP Binding Extension</h3> - <table border="1" summary="Editorial note: KevinL"> - <tr> - <td align="left" valign="top" width="50%"><b>Editorial note: - KevinL</b></td> - <td align="right" valign="top" width="50%">20050310</td> - </tr> - - <tr> - <td colspan="2" align="left" valign="top">Incoporated contribution - from Asir. Need to check back this section for integration with - rest of document.</td> - </tr> - </table> - <p>The WSDL 2.0 SOAP Binding Extension (see WSDL 2.0 Part 2 [<cite><a href="#WSDL-PART2">WSDL 2.0 Adjuncts</a></cite>]) was --- 2957,2960 ---- *************** *** 2997,3000 **** --- 2987,2997 ---- each such fault.</p> </li> + + <li> + <p>If HTTP is used as the underlying protocol, then the binding can + (and should) control whether each operation will use HTTP GET or + POST. (See <a href="#adv-get-vs-post"><b>6.7 HTTP GET Versus POST: + Which to Use?</b></a>.)</p> + </li> </ul> *************** *** 3103,3107 **** <dd> <p>This line specifies that HTTP should be used as the underlying ! transmission protocol.</p> </dd> --- 3100,3105 ---- <dd> <p>This line specifies that HTTP should be used as the underlying ! transmission protocol. See also <a href="#adv-get-vs-post"><b>6.7 ! HTTP GET Versus POST: Which to Use?</b></a>.</p> </dd> *************** *** 3296,3299 **** --- 3294,3379 ---- </div> </div> + + <div class="div2"> + <h3><a id="adv-get-vs-post" name="adv-get-vs-post"></a>6.7 HTTP GET + Versus POST: Which to Use?</h3> + + <p>When a binding using HTTP is specified for an operation, the + WSDL 2.0 author must decide which HTTP method is appropriate to use + -- usually a choice between GET and POST. In the context of the Web + as a whole (rather than specifically Web services), the W3C + Technical Architecture Group (TAG) has address the question of when + it is appropriate to use GET, versus when to use POST, in a finding + entitled <em>URIs, Addressability, and the use of HTTP GET and + POST</em> @@bibref@@. From the abstract:</p> + + <p>"<em>. . . designers should adopt [GET] for safe operations such + as simple queries. POST is appropriate for other types of + applications where a user request has the potential to change the + state of the resource (or of related resources). The finding + explains how to choose between HTTP GET and POST for an application + taking into account architectural, security, and practical + considerations.</em>"</p> + + <p>Recall that the concept of a safe operation (i.e., invocation + does not cause new obligations) was discussed in <a + href="#more-interfaces-op-attr"><b>5.4.1 Operation + Attributes</b></a>. Although the <code>safe</code> attribute of an + interface operation indicates that the abstract operation is safe, + it does not automatically cause GET to be used at the HTTP level + when the binding is specified. The choice of GET or POST is + determined at the binding level:</p> + + <ul> + <li> + <p>If the WSDL 2.0 SOAP binding extension is used (<a + href="#more-bindings-soap"><b>6.5 The SOAP Binding + Extension</b></a>), with HTTP as the underlying transport protocol, + then GET may be specified by setting:</p> + + <dl> + <dt class="label"> + <code>wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP"</code></dt> + + <dd> + <p>on the <code>binding</code> element (to indicate the use of HTTP + as the underlying protocol); and</p> + </dd> + + <dt class="label"> + <code>wsoap:mep="http://www.w3.org/2003/05/soap/mep/soap-response/"</code></dt> + + <dd> + <p>on the binding <code>operation</code> element, which causes GET + to be used by default.</p> + </dd> + </dl> + + <p></p> + </li> + + <li> + <p>If the WSDL 2.0 HTTP binding extension is used directly (<a + href="#more-bindings-http"><b>6.6 The HTTP Binding + Extension</b></a>), GET may be specified by setting either:</p> + + <dl> + <dt class="label"><code>whttp:methodDefault="GET"</code></dt> + + <dd> + <p>on the <code>binding</code> element; or</p> + </dd> + + <dt class="label"><code>whttp:method="GET"</code></dt> + + <dd> + <p>on the binding <code>operation</code> element, which overrides + <code>whttp:methodDefault</code> if set on the <code>binding</code> + element.</p> + </dd> + </dl> + </li> + </ul> + </div> </div> *************** *** 4481,4611 **** <div class="div2"> - <h3><a id="adv-get-vs-post" name="adv-get-vs-post"></a>7.9 GET - Versus POST: Which to Use?</h3> - - <p>When a binding using HTTP is specified for an operation, the - WSDL 2.0 author must decide which HTTP method is appropriate to use - -- usually a choice between GET and POST. In the context of the Web - as a whole (rather than specifically Web services), the W3C - Technical Architecture Group (TAG) has address the question of when - it is appropriate to use GET, versus when to use POST, in a finding - entitled <em>URIs, Addressability, and the use of HTTP GET and - POST</em> @@bibref@@. From the abstract:</p> - - <p>"<em>. . . designers should adopt [GET] for safe operations such - as simple queries. POST is appropriate for other types of - applications where a user request has the potential to change the - state of the resource (or of related resources). The finding - explains how to choose between HTTP GET and POST for an application - taking into account architectural, security, and practical - considerations.</em>"</p> - - <p>Recall that the concept of a safe operation (i.e., invocation - does not cause new obligations) was discussed in <a - href="#more-interfaces-op-attr"><b>5.4.1 Operation - Attributes</b></a>. Although the <code>safe</code> attribute of an - interface operation indicates that the abstract operation is safe, - it does not automatically cause GET to be used at the HTTP level - when the binding is specified. The choice of GET or POST is - determined at the binding level:</p> - - <ul> - <li> - <p>If the WSDL 2.0 SOAP binding extension is used (<a - href="#more-bindings-soap"><b>6.5 The SOAP Binding - Extension</b></a>), with HTTP as the underlying transport protocol, - then GET may be specified by setting:</p> - - <dl> - <dt class="label"> - <code>wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP"</code></dt> - - <dd> - <p>on the <code>binding</code> element (to indicate the use of HTTP - as the underlying protocol); and</p> - </dd> - - <dt class="label"> - <code>wsoap:mep="http://www.w3.org/2003/05/soap/mep/soap-response/"</code></dt> - - <dd> - <p>on the binding <code>operation</code> element, which causes GET - to be used by default.</p> - </dd> - </dl> - - <p></p> - </li> - - <li> - <p>If the WSDL 2.0 HTTP binding extension is used directly (<a - href="#more-bindings-http"><b>6.6 The HTTP Binding - Extension</b></a>), GET may be specified by setting either:</p> - - <dl> - <dt class="label"><code>whttp:methodDefault="GET"</code></dt> - - <dd> - <p>on the <code>binding</code> element; or</p> - </dd> - - <dt class="label"><code>whttp:method="GET"</code></dt> - - <dd> - <p>on the binding <code>operation</code> element, which overrides - <code>whttp:methodDefault</code> if set on the <code>binding</code> - element.</p> - </dd> - </dl> - </li> - </ul> - - <p></p> - </div> - - <div class="div2"> <h3><a id="adv-service-references" ! name="adv-service-references"></a>7.10 Service References</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%">20050326</td> ! </tr> ! ! <tr> ! <td colspan="2" align="left" valign="top">This is the first draft. ! Please review. The source for all the examples is in the test ! suite. See <a ! href="http://dev.w3.org/cvsweb/2002/ws/desc/test-suite/documents/good/ServiceReference-1G/"> ! ServiceReference-1G</a>.</td> ! </tr> ! </table> ! ! <p>[Use ! http://lists.w3.org/Archives/Public/www-ws-desc/2003Oct/0345.html ! as a starting point. Also example(s) from Roberto per the ! resolution at the end of ! http://lists.w3.org/Archives/Public/www-ws-desc/2003Nov/0061.html ! ]</p> <p>Hyperlinking is one of the defining characteristics of the Web. The ability to navigate from one Web page to another is extremely 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>@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ ! @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ ! @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@</p> <div class="div3"> ! <h4><a id="reservationDetails" name="reservationDetails"></a>7.10.1 The Reservation Details Web Service</h4> <p>When designing a Web application it is natural to give each ! important concept a URI. In the hotel reservation system, the ! important concepts are reservations, so we begin our design by assigning a URI to each reservation. Since each reservation has a unique confirmation number, e.g OMX736, we create a URI for each --- 4561,4581 ---- <div class="div2"> <h3><a id="adv-service-references" ! name="adv-service-references"></a>7.9 Service References</h3> <p>Hyperlinking is one of the defining characteristics of the Web. The ability to navigate from one Web page to another is extremely 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"> ! <h4><a id="reservationDetails" name="reservationDetails"></a>7.9.1 The Reservation Details Web Service</h4> <p>When designing a Web application it is natural to give each ! important concept a URI. In the GreatH hotel reservation system, ! the important concepts are reservations, so we begin our design by assigning a URI to each reservation. Since each reservation has a unique confirmation number, e.g OMX736, we create a URI for each *************** *** 4823,4827 **** <div class="div3"> ! <h4><a id="reservationList" name="reservationList"></a>7.10.2 The Reservation List Web Service</h4> --- 4793,4797 ---- <div class="div3"> ! <h4><a id="reservationList" name="reservationList"></a>7.9.2 The Reservation List Web Service</h4> *************** *** 4908,4912 **** </reservationList> - </pre> </div> --- 4878,4881 ---- *************** *** 5099,5115 **** <div class="div2"> - <h3><a id="adv-xml-schema-examples" - name="adv-xml-schema-examples"></a>7.11 XML Schema Examples</h3> - - <p>[Add Paul Downey's contribution at - http://lists.w3.org/Archives/Public/www-ws-desc/2004May/0007.html - ]</p> - </div> - - <div class="div2"> <h3><a id="adv-multiple-inline-schemas" ! name="adv-multiple-inline-schemas"></a>7.12 Multiple In-Line Schemas</h3> <table border="1" summary="Editorial note: Arthur"> <tr> --- 5068,5079 ---- <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"> <tr> *************** *** 5145,5149 **** <div class="div3"> ! <h4>7.12.1 Schemas in Imported Documents</h4> <p>In this example, we consider some GreatH Hotel Web services that --- 5109,5113 ---- <div class="div3"> ! <h4>7.10.1 Schemas in Imported Documents</h4> <p>In this example, we consider some GreatH Hotel Web services that *************** *** 5315,5319 **** <div class="div3"> ! <h4>7.12.2 Multiple Inline Schemas on One Document</h4> <p>A WSDL document may define multiple inline schemas in its --- 5279,5283 ---- <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 *************** *** 5419,5423 **** <div class="div2"> ! <h3><a id="adv-schema-location" name="adv-schema-location"></a>7.13 The schemaLocation Attribute</h3> --- 5383,5387 ---- <div class="div2"> ! <h3><a id="adv-schema-location" name="adv-schema-location"></a>7.11 The schemaLocation Attribute</h3> *************** *** 5466,5470 **** <div class="div3"> ! <h4>7.13.1 Using the id Attribute to Identify Inline Schemas</h4> <p><a href="#schemaIds.wsdl">Example 7-22</a> shows the use of the --- 5430,5434 ---- <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 *************** *** 5556,5565 **** <div class="div2"> ! <h3><a id="adv-rdf-mapping" name="adv-rdf-mapping"></a>7.14 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.15 Notes on URIs</h3> --- 5520,5529 ---- <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> *************** *** 5570,5574 **** <div class="div3"> <h4><a id="adv-namespaces-and-schema-locations" ! name="adv-namespaces-and-schema-locations"></a>7.15.1 XML Namespaces and Schema Locations</h4> --- 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> *************** *** 5588,5592 **** <div class="div3"> ! <h4><a id="adv-relative-uris" name="adv-relative-uris"></a>7.15.2 Relative URIs</h4> --- 5552,5556 ---- <div class="div3"> ! <h4><a id="adv-relative-uris" name="adv-relative-uris"></a>7.13.2 Relative URIs</h4> *************** *** 5601,5605 **** <div class="div3"> <h4><a id="adv-generating-uris" ! name="adv-generating-uris"></a>7.15.3 Generating Temporary URIs</h4> --- 5565,5569 ---- <div class="div3"> <h4><a id="adv-generating-uris" ! name="adv-generating-uris"></a>7.13.3 Generating Temporary URIs</h4>
Received on Monday, 18 April 2005 04:09:19 UTC