- From: Kevin Liu via cvs-syncmail <cvsmail@w3.org>
- Date: Fri, 29 Apr 2005 23:39:12 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20
In directory hutz:/tmp/cvs-serv12142/ws/desc/wsdl20
Modified Files:
wsdl20-primer.html wsdl20-primer.xml
Log Message:
fixed bib placeholders in doc
Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.72
retrieving revision 1.73
diff -C2 -d -r1.72 -r1.73
*** wsdl20-primer.xml 29 Apr 2005 06:19:52 -0000 1.72
--- wsdl20-primer.xml 29 Apr 2005 23:39:10 -0000 1.73
***************
*** 491,495 ****
<head>WSDL 2.0 Schema and Element Ordering</head>
! <p>The WSDL 2.0 specification supplies a normative WSDL 2.0 schema @@ToDo: add reference to wsdl schema when publish@@, defined in XML Schema <bibref ref="XMLSchemaP1"/> <bibref ref="XMLSchemaP2"/>, which can be used as an aid in validating WSDL 2.0 documents. Although the WSDL 2.0 schema does not indicate the required ordering of elements, the WSDL 2.0 specification (WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> "<xspecref href="http://www.w3.org/TR/wsdl20-primer#Description_XMLRep">XML Representation of Description Component</xspecref>") clearly states a set of constraints about how the children elements of the <code>description</code> element should be ordered. Thus, the order of the WSDL 2.0 elements matters, in spite of what the WSDL 2.0 schema says. </p><p>The following is a pseudo-content model of <code>description</code>.</p>
<eg xml:space="preserve">
--- 491,504 ----
<head>WSDL 2.0 Schema and Element Ordering</head>
! <p>The WSDL 2.0 specification supplies a <xspecref href="http://www.w3.org/2004/08/wsdl">normative WSDL 2.0 schema</xspecref>, defined in XML Schema <bibref ref="XMLSchemaP1"/> <bibref ref="XMLSchemaP2"/>, which can be used as an aid in validating WSDL 2.0 documents.
! <ednote>
! <name>KevinL</name>
! <date>20050428</date>
! <edtext>
! ToDo: update link to wsdl2.0 schema when final uri is available
! </edtext>
! </ednote>
!
! Although the WSDL 2.0 schema does not indicate the required ordering of elements, the WSDL 2.0 specification (WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> "<xspecref href="http://www.w3.org/TR/wsdl20-primer#Description_XMLRep">XML Representation of Description Component</xspecref>") clearly states a set of constraints about how the children elements of the <code>description</code> element should be ordered. Thus, the order of the WSDL 2.0 elements matters, in spite of what the WSDL 2.0 schema says. </p><p>The following is a pseudo-content model of <code>description</code>.</p>
<eg xml:space="preserve">
***************
*** 906,915 ****
operation-specific and fault-specific binding details. Endpoints can later refer to a reusable binding in the same manner as for a non-reusable binding. Thus, a reusable binding becomes associated with a particular interface when it is referenced from an endpoint, because an endpoint is part of a service, and the service specifies a particular interface that it implements. Since a reusable binding does not specify an interface, reusable bindings cannot specify operation-specific details. Therefore, reusable bindings can only be defined using binding extensions that have suitable defaulting rules, such that the binding information only needs to be explicitly supplied at the interface level.</p></div2><div2 id="more-bindings-faults">
<head>Binding Faults</head>
-
-
-
-
-
-
<p>A binding <code>fault</code> associates a concrete message format with an abstract fault
of an interface. It describes how faults that occur within a message exchange of an operation will be formatted, since the fault does not occur by itself. Rather, a fault occurs as part of a message
--- 915,918 ----
***************
*** 1067,1071 ****
This would instead serialize to a request URI such as: <code>http://greath.example.com/2004/bycheckInDate/5-5-5</code></p></div3></div2>
<div2 id="adv-get-vs-post"><head>HTTP GET Versus POST: Which to Use?</head>
! <p> When a binding using HTTP is specified for an operation, the WSDL 2.0 author must decide which HTTP method is appropriate to use -- usually a choice between GET and POST. In the context of the Web as a whole (rather than specifically Web services), the W3C Technical Architecture Group (TAG) has addressed the question of when it is appropriate to use GET, versus when to use POST, in a finding entitled <emph>URIs, Addressability, and the use of HTTP GET and POST</emph> @@bibref@@. From the abstract:</p><p><quote><emph>. . . designers should adopt [GET] for safe operations such as simple queries. POST is appropriate for other types of applications where a user request has the potential to change the state of the resource (or of related resources). The finding explains how to choose between HTTP GET and POST for an application taking into account architectural, security, and practical considerations.</emph></quote></p><p>Recall that the concept of a safe operation was discussed in <specref ref=more-interfaces-op-attr"/>. (Briefly, a safe operation is one that does not cause the invoker to incur new obligations.) Although the <code>safe</code> attribute of an interface operation indicates that the abstract operation is safe, it does not automatically cause GET to be used at the HTTP level when the binding is specified. The choice of GET or POST is determined at the binding level: </p><ulist><item><p>If the WSDL 2.0 SOAP binding extension is used (<specref ref="more-bindings-soap"/>), with HTTP as the underlying transport protocol, then GET may be specified by setting:<glist><gitem><label><code>wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP"</code></label><def><p>on the <code>binding</code> element (to indicate the use of HTTP as the underlying protocol); and</p></def></gitem><gitem><label><code>wsoap:mep="http://www.w3.org/2003/05/soap/mep/soap-response/"</code></label><def><p>on the binding <code>operation</code> element, which causes GET to be used by default.</p></def></gitem><glist> </p></item><item><p>If the WSDL 2.0 HTTP binding extension is used directly (<specref ref="more-bindings-http"/>), GET may be specified by setting either:<glist><gitem><label><code>whttp:methodDefault="GET"</code></label><def><p>on the <code>binding</code> element; or</p></def></gitem><gitem><label><code>whttp:method="GET"</code></label><def><p>on the binding <code>operation</code> element, which overrides <code>whttp:methodDefault</code> if set on the <code>binding</code> element.</p></def></gitem></glist></p></item></ulist>
</div2></div1>
--- 1070,1074 ----
This would instead serialize to a request URI such as: <code>http://greath.example.com/2004/bycheckInDate/5-5-5</code></p></div3></div2>
<div2 id="adv-get-vs-post"><head>HTTP GET Versus POST: Which to Use?</head>
! <p> When a binding using HTTP is specified for an operation, the WSDL 2.0 author must decide which HTTP method is appropriate to use -- usually a choice between GET and POST. In the context of the Web as a whole (rather than specifically Web services), the W3C Technical Architecture Group (TAG) has addressed the question of when it is appropriate to use GET, versus when to use POST, in a finding entitled <emph>URIs, Addressability, and the use of HTTP GET and POST</emph> (<bibref ref="TAG-whenToUseGET"/>). From the abstract:</p><p><quote><emph>. . . designers should adopt [GET] for safe operations such as simple queries. POST is appropriate for other types of applications where a user request has the potential to change the state of the resource (or of related resources). The finding explains how to choose between HTTP GET and POST for an application taking into account architectural, security, and practical considerations.</emph></quote></p><p>Recall that the concept of a safe operation was disussed in <specref ref="more-interfaces-op-attr"/>. (Briefly, a safe operation is one that does not cause the invoker to incur new obligations.) Although the <code>safe</code> attribute of an interface operation indicates that the abstract operation is safe, it does not automatically cause GET to be used at the HTTP level when the binding is specified. The choice of GET or POST is determined at the binding level: </p><ulist><item><p>If the WSDL 2.0 SOAP binding extension is used (<specref ref="more-bindings-soap"/>), with HTTP as the underlying transport protocol, then GET may be specified by setting:<glist><gitem><label><code>wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP"</code></label><def><p>on the <code>binding</code> element (to indicate the use of HTTP as the underlying protocol); and</p></def></gitem><gitem><label><code>wsoap:mep="http://www.w3.org/2003/05/soap/mep/soap-response/"</code></label><def><p>on the binding <code>operation</code> element, which causes GET to be used by defalt.</p></def></gitem></glist> </p></item><item><p>If the WSDL 2.0 HTTP binding extension is used directly (<specref ref="more-bindings-http"/>), GET may be specified by setting either:<glist><gitem><label><code>whttp:methodDefault="GET"</code></label><def><p>on the <code>binding</code> element; or</p></def></gitem><gitem><label><code>whttp:method="GET"</code></label><def><p>on the binding <code>operation</code> element, which overrides <code>whttp:methodDefault</code> if set on the <code>binding</code> element.</p></def></gitem></glist></p></item></ulist>
</div2></div1>
***************
*** 1335,1345 ****
there are three activities within the W3C that are directly relevant
to versioning of Web services description:</p>
!
! <ednote><edtext>ToDo: Add bibliography entries for several documents mentioned in this section, and fill in appropriate @@ bibrefs @@.</edtext></ednote><ulist><item><p>The <loc href="http://www.w3.org/2001/tag/">Technical Architecture Group (TAG)</loc> has published guidance on
! the extensibility and versioning of data formats in its Web Architecture document <bibref ref="webarch"/>. There is also a more wide ranging draft finding on Versioning
! and Extensibility @@bibref@@. Both of these works build
! upon the technical note on Web Architecture: Extensible Languages @@bibref@@.</p></item><item><p>The <loc href="http://www.w3.org/XML/Schema">XML Schema Working Group</loc> is collecting a series of use cases
! for schema versioning as a part of the Schema 1.1 activity. See XML Schema Versioning Use Cases @@bibref@@.</p></item><item><p>The <loc href="http://www.w3.org/2001/sw/BestPractices/">Semantic Web Best Practices and Deployments Working Group</loc> is
! examining how vocabularies may evolve. See @@bibref: http://esw.w3.org/topic/VocabManagementNote @@</p></item></ulist><p>While incomplete, these activities all agree in one important
respect: that versioning is difficult, but you SHOULD
anticipate and plan for change.</p><p>The draft finding on Versioning and Extensibility details two key
--- 1338,1347 ----
there are three activities within the W3C that are directly relevant
to versioning of Web services description:</p>
!
! <ulist><item><p>The <loc href="http://www.w3.org/2001/tag/">Technical Architecture Group (TAG)</loc> has published guidance on the extensibility and versioning of data formats in its Web Architecture document <bibref ref="webarch"/>. There is also a more wide ranging draft finding on Versioning
! and Extensibility <bibref ref="TAG-versioning"/>. Both of these works build
! upon the technical note on Web Architecture: Extensible Languages <bibref ref="web-extensible"/>.</p></item><item><p>The <loc href="http://www.w3.org/XML/Schema">XML Schema Working Group</loc> is collecting a series of use cases
! for schema versioning as a part of the Schema 1.1 activity. See XML Schema Versioning Use Cases <bibref ref="xsd-versioning"/>.</p></item><item><p>The <loc href="http://www.w3.org/2001/sw/BestPractices/">Semantic Web Best Practices and Deployments Working Group</loc> is
! examining how vocabularies may evolve. See <bibref ref="sw-vocabulary"/></p></item></ulist><p>While incomplete, these activities all agree in one important
respect: that versioning is difficult, but you SHOULD
anticipate and plan for change.</p><p>The draft finding on Versioning and Extensibility details two key
***************
*** 1359,1366 ****
How the messages themselves may change within a description depends to
a large extent upon the type system being used to describe the message
! contents. RelaxNG @@bibref@@ has good support for describing vocabularies that
! ignore unknown XML, as does OWL/RDF @@bibref@@. XML Schema 1.0 has limited
support for extending the description of a message via the <code>xs:any</code> and
! <code>xs:anyAttribute</code> constructs. XML Schema 1.1 @@bibref@@ has been chartered to
provide "changes necessary to provide better support for versioning of
schemas", and it is anticipated that this will include improved support
--- 1361,1368 ----
How the messages themselves may change within a description depends to
a large extent upon the type system being used to describe the message
! contents. RelaxNG <bibref ref="relax-ng"/> has good support for describing vocabularies that
! ignore unknown XML, as does OWL/RDF. XML Schema 1.0 has limited
support for extending the description of a message via the <code>xs:any</code> and
! <code>xs:anyAttribute</code> constructs. XML Schema 1.1 has been chartered to
provide "changes necessary to provide better support for versioning of
schemas", and it is anticipated that this will include improved support
***************
*** 1559,1565 ****
element child of both input and output elements. This indicates that the reservation system may change the room type
requested based on availability. </p><p>The reservation service also returns a rate type for the reservation, such as "rack rate". The return value for the method is designated as the
! "rate" element.</p><ednote><name>dbooth</name><date>2005-04-15</date><edtext>ToDo: Add a bib entry for JAX RPC 1.1 - Java(TM) API for XML-based RPC JAX-RPC 1.1
! (http://java.sun.com/xml/downloads/jaxrpc.html) - and fill in the @@bibref@@ below.</edtext></ednote><p>Based on the value of the <code>wrpc:signature</code> attribute, the method signature would be obtained following the order of the parameters. A sample
! mapping is provided below for the Java(TM) language. This example was created using JAX RPC 1.1 @@bibref@@
for mapping simple types to Java types and
designated inout and output parameters by using Holder classes.</p><example id="example-rpc-style-java-sig">
--- 1561,1566 ----
element child of both input and output elements. This indicates that the reservation system may change the room type
requested based on availability. </p><p>The reservation service also returns a rate type for the reservation, such as "rack rate". The return value for the method is designated as the
! "rate" element.</p><p>Based on the value of the <code>wrpc:signature</code> attribute, the method signature would be obtained following the order of the parameters. A sample
! mapping is provided below for the Java(TM) language. This example was created using JAX RPC 1.1 <bibref ref="jaxrpc"/>
for mapping simple types to Java types and
designated inout and output parameters by using Holder classes.</p><example id="example-rpc-style-java-sig">
***************
*** 2095,2099 ****
</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 scalability. </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>
--- 2096,2100 ----
</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 ref="rest"/>. REST is a distillation of the architectural properties that Dr. Fielding identified as being vital to the Web's robustness and enormous scalability. </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>
***************
*** 2667,2672 ****
<div2 id="adv-rdf-mapping">
<head>Mapping to RDF and Semantic Web</head>
<p>WSDL 2.0 is a language designed primarily with XML syntax. While XML is
! almost universally understood, it has several issues: </p><ulist><item><p><?xm-replace_text {p}?></p></item><item><p>The ability to compose two XML documents into one depends on the languages of those documents. WSDL 2.0 does not permit Web service descriptions
in different targetNamespaces to be merged into a single (physical) XML document. </p></item><item><p>The ability to extend XML languages with other XML languages depends on the
languages again. WSDL 2.0 is extremely extensible, but the meaning
--- 2668,2684 ----
<div2 id="adv-rdf-mapping">
<head>Mapping to RDF and Semantic Web</head>
+
+ <ednote>
+ <name>KevinL</name>
+ <date>20050429</date>
+ <edtext>
+ This section might be removed - pending on the availability of the RDF mapping note. </edtext>
+ </ednote>
+
+
<p>WSDL 2.0 is a language designed primarily with XML syntax. While XML is
! almost universally understood, it has several issues: </p>
!
! <ulist><item><p>The ability to compose two XML documents into one depends on the languages of those documents. WSDL 2.0 does not permit Web service descriptions
in different targetNamespaces to be merged into a single (physical) XML document. </p></item><item><p>The ability to extend XML languages with other XML languages depends on the
languages again. WSDL 2.0 is extremely extensible, but the meaning
***************
*** 2682,2691 ****
specification. While an interface element could form a single XML
document, it is not a WSDL 2.0 document, so its meaning is largely undefined. </p></item></ulist><p>Applications that require such levels of composability (or
! decomposability) are increasingly being based on RDF @@bibref@@, a graph-based
! knowledge representation language, and Web Ontology Language (OWL) @@bibref@@,
which can be thought of as an advanced schema language for RDF. Effectively,
a WSDL 2.0 document represented in RDF can be more easily extended with arbitrary
RDF assertions and the WSDL 2.0 information can be more easily associated with
! arbitrary other knowledge. </p><div3 id="adv-rdf-rep-wsdl"><head>RDF Representation of WSDL 2.0</head><p><emph>WSDL 2.0: Mapping to RDF</emph> @@bibref@@ describes how WSDL 2.0 constructs can be
expressed in RDF using classes of resources (described with an ontology
expressed in OWL) and assertions over individual resources. As RDF represents knowledge using resources and relationships between
--- 2694,2707 ----
specification. While an interface element could form a single XML
document, it is not a WSDL 2.0 document, so its meaning is largely undefined. </p></item></ulist><p>Applications that require such levels of composability (or
! decomposability) are increasingly being based on RDF <bibref ref="rdf"/>, a graph-based
! knowledge representation language, and Web Ontology Language (OWL) <bibref ref="owl"/>,
which can be thought of as an advanced schema language for RDF. Effectively,
a WSDL 2.0 document represented in RDF can be more easily extended with arbitrary
RDF assertions and the WSDL 2.0 information can be more easily associated with
! arbitrary other knowledge. </p>
!
! <div3 id="adv-rdf-rep-wsdl"><head>RDF Representation of WSDL 2.0</head>
!
! <p><emph>WSDL 2.0: Mapping to RDF</emph> @@bibref@@ describes how WSDL 2.0 constructs can be
expressed in RDF using classes of resources (described with an ontology
expressed in OWL) and assertions over individual resources. As RDF represents knowledge using resources and relationships between
***************
*** 3039,3057 ****
http://www.w3.org/TR/xptr-framework/.
</bibl>
! <!--
! <bibl key="WSD Usage Scenarios"
!
!
! href="http://www.w3.org/TR/2002/WD-ws-desc-usecases-20020604/"
! id="WSDReqs"> <titleref>Web Services Description Usage
! Scenarios</titleref>, W. Sadiq, S. Kumar, Editors. World Wide Web
! Consortium, 4 June 2002. This version of the Web Services
! Usage Scenarios document is
! http://www.w3.org/TR/2002/WD-ws-desc-usecases-20020604. The
! <loc href='http://www.w3.org/TR/ws-desc-usecases/'>latest
! version of Web Services Usage Scenarios</loc> is available at
! http://www.w3.org/TR/ws-desc-usecases.
! </bibl>
! -->
</blist>
</div2>
--- 3055,3105 ----
http://www.w3.org/TR/xptr-framework/.
</bibl>
!
! <bibl key="W3C TAG Finding: Use of HTTP GET" href="http://www.w3.org/2001/tag/doc/whenToUseGet.html" id="TAG-whenToUseGET">
! <titleref>URIs, Addressability, and the use of HTTP GET and POST</titleref>, Ian Jacobs, Editor. World Wide Web
! Consortium, 21 March 2004. This version of TAG finding is available at
! http://www.w3.org/2001/tag/doc/whenToUseGet.html
! </bibl>
!
!
! <bibl key="W3C TAG Finding: Versioning" href="http://www.w3.org/2001/tag/doc/versioning.html" id="TAG-versioning">
! <titleref>Versioning XML Languages</titleref> David Orchard, Norman Walsh. Proposed TAG Finding 16 November 2003. Available at
! http://www.w3.org/2001/tag/doc/versioning.html
! </bibl>
!
!
! <bibl key="WebArch: Extensible Languages" href="http://www.w3.org/TR/NOTE-webarch-extlang" id="web-extensible">
! <titleref>Web Architecture: Extensible Languages</titleref> , Tim Berners-Lee, Dan Connolly, Authors. W3C Note 10 Feb 1998. Available at http://www.w3.org/TR/NOTE-webarch-extlang
! </bibl>
!
! <bibl key="XML Schema: Versioning Use-Cases" href="http://www.w3.org/XML/2005/xsd-versioning-use-cases/" id="xsd-versioning">
! <titleref>XML Schema Versioning Use Cases</titleref> , Hoylen Sue. W3C XML Schema Working Group Draft, 15 April 2005. Available at http://www.w3.org/XML/2005/xsd-versioning-use-cases/
! </bibl>
!
! <bibl key="SW VocabManagementNote" href="http://esw.w3.org/topic/VocabManagementNote" id="sw-vocabulary">
! <titleref>Vocabulary Management</titleref> , Thomas Baker, et al. Semantic Web Best Practices and Deployment Working Group Note, 8 Feb 2005. Available at
! http://esw.w3.org/topic/VocabManagementNote
!
! </bibl>
! <bibl key="RELAX NG" href="http://www.oasis-open.org/committees/relax-ng/spec-20011203.html" id="relax-ng">
! <titleref>RELAX NG Specification</titleref>, James Clark, MURATA Makoto, Editors. OASIS Committee Specification, 3 December 2001. Available at http://www.oasis-open.org/committees/relax-ng/spec-20011203.html
! </bibl>
!
! <bibl key="JAX RPC 1.1" href="http://java.sun.com/xml/downloads/jaxrpc.html" id="jaxrpc">
! <titleref>Java(TM) API for XML-based Remote Procedure Call (JAX-RPC) Specification, version 1.1</titleref>, Roberto Chinnici,et al. 14 October, 2003. Available at http://java.sun.com/xml/downloads/jaxrpc.html
! </bibl>
!
!
! <bibl key="REST" href="http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm" id="rest">
! <titleref>Representational State Transfer (REST)</titleref>, Roy Thomas Fielding, Author. 2000. Available at http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
! </bibl>
!
! <bibl key="RDF" href="http://www.w3.org/TR/rdf-concepts/" id="rdf">
! <titleref>Resource Description Framework (RDF): Concepts and Abstract Syntax</titleref>, Graham Klyne, Jeremy J. Carroll, Editors. W3C Recommendation, 10 February 2004. Available at http://www.w3.org/TR/rdf-concepts/
! </bibl>
!
! <bibl key="OWL" href="http://www.w3.org/TR/owl-ref/" id="owl">
! <titleref>OWL Web Ontology Language Reference</titleref>, Mike Dean,Guus Schreiber, Editors. W3C Recommendation 10 February 2004 . Available at http://www.w3.org/TR/owl-ref/
! </bibl>
</blist>
</div2>
Index: wsdl20-primer.html
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.html,v
retrieving revision 1.52
retrieving revision 1.53
diff -C2 -d -r1.52 -r1.53
*** wsdl20-primer.html 29 Apr 2005 06:19:52 -0000 1.52
--- wsdl20-primer.html 29 Apr 2005 23:39:10 -0000 1.53
***************
*** 94,99 ****
<hr><div class="toc">
<h2><a name="shortcontents">Short Table of Contents</a></h2><p class="toc">1. <a href="#Introduction">Introduction</a><br>2. <a href="#basics">WSDL 2.0 Basics</a><br>3. <a href="#wsdl-xml-representation">WSDL 2.0 Infoset, Schema and Component Model</a><br>4. <a href="#more-types">More on Message Types</a><br>5. <a href="#more-interfaces">More on Interfaces</a><br>6. <a href="#more-bindings">More on Bindings</a><br>7. <a href="#advanced-topic_ii">Advanced Topics</a><br>8. <a href="#References">References</a><br></p></div><hr><div class="toc">
! <h2><a name="contents">Table of Contents</a></h2><p class="toc">1. <a href="#Introduction">Introduction</a><br> 1.1 <a href="#Prerequisites">Prerequisites</a><br> 1.2 <a href="#PrimerStructure">Structure of this Primer</a><br> 1.3 <a href="#notation">Notational Conventions</a><br>2. <a href="#basics">WSDL 2.0 Basics</a><br> 2.1 <a href="#basics-greath-scenario">Example Scenario: The GreatH Hotel Reservation Service</a><br> 2.2 <a href="#basics-getting-started">Getting Started: Defining a WSDL Target Namespace</a><br> 2.2.1 <a href="#example-empty-shell-explanation">Explanation of Example</a><br> 2.3 <a href="#basics-types">Defining Message Types</a><br> 2.3.1 <a href="#example-initial-types-explanation">Explanation of Example</a><br> 2.4 <a href="#basics-nterface">Defining an Interface</a><br> 2.4.1 <a href="#example-initial-interface-explanation">Explanation of Example</a><br> 2.5 <a href="#basics-binding">Defining a Binding</a><br> 2.5.1 <a href="#example-initial-binding-explanation">Explanation of Example</a><br> 2.6 <a href="#basics-service">Defining a Service</a><br> 2.6.1 <a href="#example-initial-service-explanation">Explanation of Example</a><br> 2.7 <a href="#basics-documentation">Documenting the Service</a><br> 2.7.1 <a href="#example-initial-documentation-explanation">Explanation of Example</a><br>3. <a href="#wsdl-xml-representation">WSDL 2.0 Infoset, Schema and Component Model</a><br> 3.1 <a href="#wsdl-infoset-diagram">WSDL 2.0 Infoset</a><br> 3. <a href="#wsdl-schema">WSDL 2.0 Schema and Element Ordering</a><br> 3.3 <a href="#component-model">WSDL 2.0 Component Model</a><br>4. <a href="#more-types">More on Message Types</a><br> 4.1 <a href="#more-types-schema-embed">Embedding XML Schema</a><br> 4.2 <a href="#more-types-schema-import">Importing XML Schema</a><br> 4.3 <a href="#more-types-import-include-summary">Summary of Import and Include Mechanisms</a><br>5. <a href="#more-interfaces">More on Interfaces</a><br> 5.1 <a href="#more-interfaces-interfaces">Interface Syntax </a><br> 5.2 <a href="#more-interfaces-inheritance">Interface Inheritance</a><br> 5.3 <a href="#more-interfaces-faults">Interface Faults</a><br> 5.4 <a href="#more-interfaces-operations">Interface Operations</a><br> 5.4.1 <a href="#more-interfaces-op-att">Operation Attributes</a><br> 5.4.2 <a href="#N108C7">Operation Message References</a><br> 5.4.2.1 <a href="#N108E4">The messageLabel Attribute</a><br> 5.4.2.2 <a href="#N108F8">The element Attribute</a><br> 5.4.2.3 <a href="#N1091F">Multiple infault or outfault Elements</a><br> 5.4.3 <a href="#more-interfaces-meps">Understanding Message Exchange Patterns (MEPs)</a><br> 5.4.4 <a href="#more-interfaces-defining-meps">Defining New Message Exchange Patterns (MEPs)</a><br>6. <a href="#more-bindings">More on Bindings</a><br> 6.1 <a href="#more-bindings-wsdl">Syntax Summary for Bindings</a><br> 6.2 <a href="#more-bindins-reusable">Reusable Bindings</a><br> 6.3 <a href="#more-bindings-faults">Binding Faults</a><br> 6.4 <a href="#bindingOperations">Binding Operations</a><br> 6.5 <a href="#more-bindings-soap">The SOAP Binding Extension</a><br> 6.5.1 <a href="#more-bindings-soap-example-explanation">Explanation of Example</a><br> 6.6 <a href="#more-bindings-http">The HTTP Binding Extension</a><br> 6.6.1 <a href="#N10AE3">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 href="#adv-extensibility">Extensibility</a><br> 7.1.1 <a href="#adv-optional-versus-required">Optional Versus Required Extensions</a><br> 7.1.2 <a href="#adv-scope-of-wsdl-required">Scoping of the wsdl:required Attribute</a><br> 7.2 <a href="#adv-FP">Features and Properties</a><br> 7.2.1 <a href="#adv-FP-soap-modules">SOAP Modules</a><br> 7.2.2 <a href="#adv-FP-abstract-features">Abstract Features</a><br> 7.2.3 <a href="#adv-fp-properties">Properties</a><br> 7.3 <a href="#adv-import-and-authoring">Import mechanism and authoring stye</a><br> 7.4 <a href="#adv-multiple-docs-describing-same-service">Multiple Interfaces for the Same Service</a><br> 7.5 <a href="#adv-versioning">Web Service Versioning</a><br> 7.5.1 <a href="#adv-versioning-compatible-evolution">Compatible Evolution</a><br> 7.5.2 <a href="#adv-versioning-big-bang">Big Bang</a><br> 7.5.3 <a href="#adv-versioning-combined">Combined Approaches</a><br> 7.6 <a href="#adv-MTOM">MTOM Support</a><br> 7.7 <a href="#adv-RPCstyle">RPC Style</a><br> 7.8 <a 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>nbsp; 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="#N10FF3">Schemas in Imported Documents</a><br> 7.10.2 <a href="#N1107E">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="#N110DB">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.11.1 <a href="#adv-rdf-rep-wsdl">RDF Representation of WSDL 2.0</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> 8.1 <a href="#Normative-References">Normative References</a><br> 8.2 <a href="#Informative-References">Informative References</a><br></p></div><hr><div class="body">
--- 94,99 ----
<hr><div class="toc">
<h2><a name="shortcontents">Short Table of Contents</a></h2><p class="toc">1. <a href="#Introduction">Introduction</a><br>2. <a href="#basics">WSDL 2.0 Basics</a><br>3. <a href="#wsdl-xml-representation">WSDL 2.0 Infoset, Schema and Component Model</a><br>4. <a href="#more-types">More on Message Types</a><br>5. <a href="#more-interfaces">More on Interfaces</a><br>6. <a href="#more-bindings">More on Bindings</a><br>7. <a href="#advanced-topic_ii">Advanced Topics</a><br>8. <a href="#References">References</a><br></p></div><hr><div class="toc">
! <h2><a name="contents">Table of Contents</a></h2><p class="toc">1. <a href="#Introduction">Introduction</a><br> 1.1 <a href="#Prerequisites">Prerequisites</a><br> 1.2 <a href="#PrimerStructure">Structure of this Primer</a><br> 1.3 <a href="#notation">Notational Conventions</a><br>2. <a href="#basics">WSDL 2.0 Basics</a><br> 2.1 <a href="#basics-greath-scenario">Example Scenario: The GreatH Hotel Reservation Service</a><br> 2.2 <a href="#basics-getting-started">Getting Started: Defining a WSDL Target Namespace</a><br> 2.2.1 <a href="#example-empty-shell-explanation">Explanation of Example</a><br> 2.3 <a href="#basics-types">Defining Message Types</a><br> 2.3.1 <a href="#example-initial-types-explanation">Explanation of Example</a><br> 2.4 <a href="#basics-nterface">Defining an Interface</a><br> 2.4.1 <a href="#example-initial-interface-explanation">Explanation of Example</a><br> 2.5 <a href="#basics-binding">Defining a Binding</a><br> 2.5.1 <a href="#example-initial-binding-explanation">Explanation of Example</a><br> 2.6 <a href="#basics-service">Defining a Service</a><br> 2.6.1 <a href="#example-initial-service-explanation">Explanation of Example</a><br> 2.7 <a href="#basics-documentation">Documenting the Service</a><br> 2.7.1 <a href="#example-initial-documentation-explanation">Explanation of Example</a><br>3. <a href="#wsdl-xml-representation">WSDL 2.0 Infoset, Schema and Component Model</a><br> 3.1 <a href="#wsdl-infoset-diagram">WSDL 2.0 Infoset</a><br> 3. <a href="#wsdl-schema">WSDL 2.0 Schema and Element Ordering</a><br> 3.3 <a href="#component-model">WSDL 2.0 Component Model</a><br>4. <a href="#more-types">More on Message Types</a><br> 4.1 <a href="#more-types-schema-embed">Embedding XML Schema</a><br> 4.2 <a href="#more-types-schema-import">Importing XML Schema</a><br> 4.3 <a href="#more-types-import-include-summary">Summary of Import and Include Mechanisms</a><br>5. <a href="#more-interfaces">More on Interfaces</a><br> 5.1 <a href="#more-interfaces-interfaces">Interface Syntax </a><br> 5.2 <a href="#more-interfaces-inheritance">Interface Inheritance</a><br> 5.3 <a href="#more-interfaces-faults">Interface Faults</a><br> 5.4 <a href="#more-interfaces-operations">Interface Operations</a><br> 5.4.1 <a href="#more-interfaces-op-att">Operation Attributes</a><br> 5.4.2 <a href="#N108DB">Operation Message References</a><br> 5.4.2.1 <a href="#N108F8">The messageLabel Attribute</a><br> 5.4.2.2 <a href="#N1090C">The element Attribute</a><br> 5.4.2.3 <a href="#N10933">Multiple infault or outfault Elements</a><br> 5.4.3 <a href="#more-interfaces-meps">Understanding Message Exchange Patterns (MEPs)</a><br> 5.4.4 <a href="#more-interfaces-defining-meps">Defining New Message Exchange Patterns (MEPs)</a><br>6. <a href="#more-bindings">More on Bindings</a><br> 6.1 <a href="#more-bindings-wsdl">Syntax Summary for Bindings</a><br> 6.2 <a href="#more-bindins-reusable">Reusable Bindings</a><br> 6.3 <a href="#more-bindings-faults">Binding Faults</a><br> 6.4 <a href="#bindingOperations">Binding Operations</a><br> 6.5 <a href="#more-bindings-soap">The SOAP Binding Extension</a><br> 6.5.1 <a href="#more-bindings-soap-example-explanation">Explanation of Example</a><br> 6.6 <a href="#more-bindings-http">The HTTP Binding Extension</a><br> 6.6.1 <a href="#N10AF7">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 href="#adv-extensibility">Extensibility</a><br> 7.1.1 <a href="#adv-optional-versus-required">Optional Versus Required Extensions</a><br> 7.1.2 <a href="#adv-scope-of-wsdl-required">Scoping of the wsdl:required Attribute</a><br> 7.2 <a href="#adv-FP">Features and Properties</a><br> 7.2.1 <a href="#adv-FP-soap-modules">SOAP Modules</a><br> 7.2.2 <a href="#adv-FP-abstract-features">Abstract Features</a><br> 7.2.3 <a href="#adv-fp-properties">Properties</a><br> 7.3 <a href="#adv-import-and-authoring">Import mechanism and authoring stye</a><br> 7.4 <a href="#adv-multiple-docs-describing-same-service">Multiple Interfaces for the Same Service</a><br> 7.5 <a href="#adv-versioning">Web Service Versioning</a><br> 7.5.1 <a href="#adv-versioning-compatible-evolution">Compatible Evolution</a><br> 7.5.2 <a href="#adv-versioning-big-bang">Big Bang</a><br> 7.5.3 <a href="#adv-versioning-combined">Combined Approaches</a><br> 7.6 <a href="#adv-MTOM">MTOM Support</a><br> 7.7 <a href="#adv-RPCstyle">RPC Style</a><br> 7.8 <a 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>nbsp; 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="#N11014">Schemas in Imported Documents</a><br> 7.10.2 <a href="#N1109F">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="#N110FC">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.11.1 <a href="#adv-rdf-rep-wsdl">RDF Representation of WSDL 2.0</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> 8.1 <a href="#Normative-References">Normative References</a><br> 8.2 <a href="#Informative-References">Informative References</a><br></p></div><hr><div class="body">
***************
*** 528,532 ****
<h3><a name="wsdl-schema"></a>3.2 WSDL 2.0 Schema and Element Ordering</h3>
! <p>The WSDL 2.0 specification supplies a normative WSDL 2.0 schema @@ToDo: add reference to wsdl schema when publish@@, defined in XML Schema [<cite><a href="#XMLSchemaP1">XML Schema: Structures</a></cite>] [<cite><a href="#XMLSchemaP2">XML Schema: Datatypes</a></cite>], which can be used as an aid in validating WSDL 2.0 documents. Although the WSDL 2.0 schema does not indicate the required ordering of elements, the WSDL 2.0 specification (WSDL 2.0 Part 1 [<cite><a href="#WSDL-PART1">WSDL 2.0 Core Language</a></cite>] "<a href="http://www.w3.org/TR/wsdl20-primer#Description_XMLRep">XML Representation of Description Component</a>") clearly states a set of constraints about how the children elements of the <code>description</code> element should be ordered. Thus, the order of the WSDL 2.0 elements matters, in spite of what the WSDL 2.0 schema says. </p><p>The following is a pseudo-content model of <code>description</code>.</p>
<div class="exampleInner"><pre>
--- 528,537 ----
<h3><a name="wsdl-schema"></a>3.2 WSDL 2.0 Schema and Element Ordering</h3>
! <p>The WSDL 2.0 specification supplies a <a href="http://www.w3.org/2004/08/wsdl">normative WSDL 2.0 schema</a>, defined in XML Schema [<cite><a href="#XMLSchemaP1">XML Schema: Structures</a></cite>] [<cite><a href="#XMLSchemaP2">XML Schema: Datatypes</a></cite>], which can be used as an aid in validating WSDL 2.0 documents.
! <table border="1" summary="Editorial note: KevinL"><tr><td width="50%" valign="top" align="left"><b>Editorial note: KevinL</b></td><td width="50%" valign="top" align="right">20050428</td></tr><tr><td valign="top" align="left" colspan="2">
! ToDo: update link to wsdl2.0 schema when final uri is available
! </td></tr></table>
!
! Although the WSDL 2.0 schema does not indicate the required ordering of elements, the WSDL 2.0 specification (WSDL 2.0 Part 1 [<cite><a href="#WSDL-PART1">WSDL 2.0 Core Language</a></cite>] "<a href="http://www.w3.org/TR/wsdl20-primer#Description_XMLRep">XML Representation of Description Component</a>") clearly states a set of constraints about how the children elements of the <code>description</code> element should be ordered. Thus, the order of the WSDL 2.0 elements matters, in spite of what the WSDL 2.0 schema says. </p><p>The following is a pseudo-content model of <code>description</code>.</p>
<div class="exampleInner"><pre>
***************
*** 862,870 ****
</li>
</ul></div><div class="div3">
! <h4><a name="N108C7"></a>5.4.2 Operation Message References</h4><p>An <code>operation</code> will also have <code>input</code>, <code>output</code>,<code>infault</code>, and/or <code>outfault</code> element children that specify the ordinary and fault message types to be used by that operation. The MEP specified by the <code>pattern</code> attribute determines which of these elements should be included, since each MEP has placeholders for the message types involved in its pattern. </p><p>Since operations were already discussed in <a href="#basics-interface"><b>2.4 Defining an Interface</b></a>, this section will merely comment on additional capabilities that were not previously explained.</p>
<div class="div4">
! <h5><a name="N108E4"></a>5.4.2.1 The messageLabel Attribute</h5><p>The <code>messageLabel</code> attribute of the <code>input</code> and <code>output</code> elements is optional: it is not necessary to explicitly set the <code>messageLabel</code> when the MEP in use is one of the eight MEPs predefined in WSDL 2.0 Part 2 [<cite><a href="#WSDL-PART2">WSDL 2.0 Adjuncts</a></cite>] and it has only one message with a given direction. </p></div><div class="div4">
! <h5><a name="N108F8"></a>5.4.2.2 The element Attribute</h5><p>The <code>element</code> attribute of the <code>input</code> and <code>output</code> elements is used to specify the message content schema (a/k/a payload schema) when the content model is defined using XML Schema. As we have seen already, it can specify the QName of an element schema that was defined in the <code>types</code> section. However, alternatively it can specify one of the following tokens: </p><dl><dt class="label"><code>#any</code></dt><dd><p>The message content is any single element.</p></dd><dt class="label"><code>#none</code></dt><dd><p>There is no message content, i.e., the message payload is empty.</p></dd></dl><p>The <code>element</code> attribute is also optional. If it is not specified, then @@@@. <table border="1" summary="Editorial note"><tr><td width="50%" valign="top" align="left"><b>Editorial note</b></td><td width="50%" valign="top" align="right"> </td></tr><tr><td valign="top" align="left" colspan="2">ToDo: ay what happens if the element attribute is not specified, after issue LC99 is resolved. See http://www.w3.org/2002/ws/desc/4/lc-issues/issues.html#LC99 </td></tr></table></p></div><div class="div4">
! <h5><a name="N1091F"></a>5.4.2.3 Multiple infault or outfault Elements</h5><p>When <code>infault</code> and/or <code>outfault</code> occur multiple times within an <code>operation</code>, they define alternative fault messages. </p></div></div>
--- 867,875 ----
</li>
</ul></div><div class="div3">
! <h4><a name="N108DB"></a>5.4.2 Operation Message References</h4><p>An <code>operation</code> will also have <code>input</code>, <code>output</code>,<code>infault</code>, and/or <code>outfault</code> element children that specify the ordinary and fault message types to be used by that operation. The MEP specified by the <code>pattern</code> attribute determines which of these elements should be included, since each MEP has placeholders for the message types involved in its pattern. </p><p>Since operations were already discussed in <a href="#basics-interface"><b>2.4 Defining an Interface</b></a>, this section will merely comment on additional capabilities that were not previously explained.</p>
<div class="div4">
! <h5><a name="N108F8"></a>5.4.2.1 The messageLabel Attribute</h5><p>The <code>messageLabel</code> attribute of the <code>input</code> and <code>output</code> elements is optional: it is not necessary to explicitly set the <code>messageLabel</code> when the MEP in use is one of the eight MEPs predefined in WSDL 2.0 Part 2 [<cite><a href="#WSDL-PART2">WSDL 2.0 Adjuncts</a></cite>] and it has only one message with a given direction. </p></div><div class="div4">
! <h5><a name="N1090C"></a>5.4.2.2 The element Attribute</h5><p>The <code>element</code> attribute of the <code>input</code> and <code>output</code> elements is used to specify the message content schema (a/k/a payload schema) when the content model is defined using XML Schema. As we have seen already, it can specify the QName of an element schema that was defined in the <code>types</code> section. However, alternatively it can specify one of the following tokens: </p><dl><dt class="label"><code>#any</code></dt><dd><p>The message content is any single element.</p></dd><dt class="label"><code>#none</code></dt><dd><p>There is no message content, i.e., the message payload is empty.</p></dd></dl><p>The <code>element</code> attribute is also optional. If it is not specified, then @@@@. <table border="1" summary="Editorial note"><tr><td width="50%" valign="top" align="left"><b>Editorial note</b></td><td width="50%" valign="top" align="right"> </td></tr><tr><td valign="top" align="left" colspan="2">ToDo: ay what happens if the element attribute is not specified, after issue LC99 is resolved. See http://www.w3.org/2002/ws/desc/4/lc-issues/issues.html#LC99 </td></tr></table></p></div><div class="div4">
! <h5><a name="N10933"></a>5.4.2.3 Multiple infault or outfault Elements</h5><p>When <code>infault</code> and/or <code>outfault</code> occur multiple times within an <code>operation</code>, they define alternative fault messages. </p></div></div>
***************
*** 964,973 ****
<h3><a name="more-bindings-faults"></a>6.3 Binding Faults</h3>
-
-
-
-
-
-
<p>A binding <code>fault</code> associates a concrete message format with an abstract fault
of an interface. It describes how faults that occur within a message exchange of an operation will be formatted, since the fault does not occur by itself. Rather, a fault occurs as part of a message
--- 969,972 ----
***************
*** 1104,1108 ****
</div>
<div class="div3">
! <h4><a name="N10AE3"></a>6.6.1 Explanation of
Example</h4><table border="1" summary="Editorial note: dbooth"><tr><td width="50%" valign="top" align="left"><b>Editorial note: dbooth</b></td><td width="50%" valign="top" align="right">2005-04-15</td></tr><tr><td valign="top" align="left" colspan="2">ToDo: Check this section. I'm not sure I got it all right, particularly regarding whttp:location. Is the first sample request URI correct? Shouldn't instance data for tCheckAvailability be in the path component? What happens if a non-leaf element type is specified, such as tCheckAvailability?</td></tr></table><p></p><dl>
<dt class="label"><code>type="http://www.w3.org/@@@@/@@/wsdl/http"</code></dt>
--- 1103,1107 ----
</div>
<div class="div3">
! <h4><a name="N10AF7"></a>6.6.1 Explanation of
Example</h4><table border="1" summary="Editorial note: dbooth"><tr><td width="50%" valign="top" align="left"><b>Editorial note: dbooth</b></td><td width="50%" valign="top" align="right">2005-04-15</td></tr><tr><td valign="top" align="left" colspan="2">ToDo: Check this section. I'm not sure I got it all right, particularly regarding whttp:location. Is the first sample request URI correct? Shouldn't instance data for tCheckAvailability be in the path component? What happens if a non-leaf element type is specified, such as tCheckAvailability?</td></tr></table><p></p><dl>
<dt class="label"><code>type="http://www.w3.org/@@@@/@@/wsdl/http"</code></dt>
***************
*** 1131,1135 ****
<div class="div2">
<h3><a 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 addressed 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 was discussed in <a href="#more-interfaces-op-attr"<b>5.4.1 Operation Attributes</b></a>. (Briefly, a safe operation is one that does not cause the invoker to incur new obligations.) Although the <code>safe</code> attribute of an interface operation indicates that the abstract operation is safe, it does not automatically cause GET to be used at the HTTP level when the binding is specified. The choice of GET or POST is determined at the binding level: </p><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 ued 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><p></p></li></ul>
</div></div>
--- 1130,1134 ----
<div class="div2">
<h3><a 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 addressed 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> ([<cite><a href="#TAG-whenToUseGET">W3C TAG Finding: Use of HTTP GET</a></cite>]). 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 o a safe operation was discussed in <a href="#more-interfaces-op-attr"><b>5.4.1 Operation Attributes</b></a>. (Briefly, a safe operation is one that does not cause the invoker to incur new obligations.) Although the <code>safe</code> attribute of an interface operation indicates that the abstract operation is safe, it does not automatically cause GET to be used at the HTTP level when the binding is specified. The choice of GET or POST is determined at the binding level: </p><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>o 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><p></p></li></ul>
</div></div>
***************
*** 1410,1420 ****
there are three activities within the W3C that are directly relevant
to versioning of Web services description:</p>
!
! <table border="1" summary="Editorial note"><tr><td width="50%" valign="top" align="left"><b>Editorial note</b></td><td width="50%" valign="top" align="right"> </td></tr><tr><td valign="top" align="left" colspan="2">ToDo: Add bibliography entries for several documents mentioned in this section, and fill in appropriate @@ bibrefs @@.</td></tr></table><ul><li><p>The <a href="http://www.w3.org/2001/tag/">Technical Architecture Group (TAG)</a> has published guidance on
! the extensibility and versioning of data formats in its Web Architecture document [<cite><a href="#webarch">Web Architecture</a></cite>]. There is also a more wide ranging draft finding on Versioning
! and Extensibility @@bibref@@. Both of these works build
! upon the technical note on Web Architecture: Extensible Languages @@bibref@@.</p></li><li><p>The <a href="http://www.w3.org/XML/Schema">XML Schema Working Group</a> is collecting a series of use cases
! for schema versioning as a part of the Schema 1.1 activity. See XML Schema Versioning Use Cases @@bibref@@.</p></li><li><p>The <a href="http://www.w3.org/2001/sw/BestPractices/">Semantic Web Best Practices and Deployments Working Group</a> is
! examining how vocabularies may evolve. See @@bibref: http://esw.w3.org/topic/VocabManagementNote @@</p></li></ul><p>While incomplete, these activities all agree in one important
respect: that versioning is difficult, but you SHOULD
anticipate and plan for change.</p><p>The draft finding on Versioning and Extensibility details two key
--- 1409,1418 ----
there are three activities within the W3C that are directly relevant
to versioning of Web services description:</p>
!
! <ul><li><p>The <a href="http://www.w3.org/2001/tag/">Technical Architecture Group (TAG)</a> has published guidance on the extensibility and versioning of data formats in its Web Architecture document [<cite><a href="#webarch">Web Architecture</a></cite>]. There is also a more wide ranging draft finding on Versioning
! and Extensibility [<cite><a href="#TAG-versioning">W3C TAG Finding: Versioning</a></cite>]. Both of these works build
! upon the technical note on Web Architecture: Extensible Languages [<cite><a href="#web-extensible">WebArch: Extensible Languages</a></cite>].</p></li><li><p>The <a href="http://www.w3.org/XML/Schema">XML Schema Working Group</a> is collecting a series of use cases
! for schema versioning as a part of the Schema 1.1 activity. See XML Schema Versioning Use Cases [<cite><a href="#xsd-versioning">XML Schema: Versioning Use-Cases</a></cite>].</p></li><li><p>The <a href="http://www.w3.org/2001/sw/BestPractices/">Semantic Web Best Practices and Deployments Working Group</a> is
! examining how vocabularies may evolve. See [<cite><a href="#sw-vocabulary">SW VocabManagementNote</a></cite>]</p></li></ul><p>While incomplete, these activities all agree in one important
respect: that versioning is difficult, but you SHOULD
anticipate and plan for change.</p><p>The draft finding on Versioning and Extensibility details two key
***************
*** 1435,1442 ****
How the messages themselves may change within a description depends to
a large extent upon the type system being used to describe the message
! contents. RelaxNG @@bibref@@ has good support for describing vocabularies that
! ignore unknown XML, as does OWL/RDF @@bibref@@. XML Schema 1.0 has limited
support for extending the description of a message via the <code>xs:any</code> and
! <code>xs:anyAttribute</code> constructs. XML Schema 1.1 @@bibref@@ has been chartered to
provide "changes necessary to provide better support for versioning of
schemas", and it is anticipated that this will include improved support
--- 1433,1440 ----
How the messages themselves may change within a description depends to
a large extent upon the type system being used to describe the message
! contents. RelaxNG [<cite><a href="#relax-ng">RELAX NG</a></cite>] has good support for describing vocabularies that
! ignore unknown XML, as does OWL/RDF. XML Schema 1.0 has limited
support for extending the description of a message via the <code>xs:any</code> and
! <code>xs:anyAttribute</code> constructs. XML Schema 1.1 has been chartered to
provide "changes necessary to provide better support for versioning of
schemas", and it is anticipated that this will include improved support
***************
*** 1639,1645 ****
element child of both input and output elements. This indicates that the reservation system may change the room type
requested based on availability. </p><p>The reservation service also returns a rate type for the reservation, such as "rack rate". The return value for the method is designated as the
! "rate" element.</p><table border="1" summary="Editorial note: dbooth"><tr><td width="50%" valign="top" align="left"><b>Editorial note: dbooth</b></td><td width="50%" valign="top" align="right">2005-04-15</td></tr><tr><td valign="top" align="left" colspan="2">ToDo: Add a bib entry for JAX RPC 1.1 - Java(TM) API for XML-based RPC JAX-RPC 1.1
! (http://java.sun.com/xml/downloads/jaxrpc.html) - and fill in the @@bibref@@ below.</td></tr></table><p>Based on the value of the <code>wrpc:signature</code> attribute, the method signature would be obtained following the order of the parameters. A sample
! mapping is provided below for the Java(TM) language. This example was created using JAX RPC 1.1 @@bibref@@
for mapping simple types to Java types and
designated inout and output parameters by using Holder classes.</p><div class="exampleOuter">
--- 1637,1642 ----
element child of both input and output elements. This indicates that the reservation system may change the room type
requested based on availability. </p><p>The reservation service also returns a rate type for the reservation, such as "rack rate". The return value for the method is designated as the
! "rate" element.</p><p>Based on the value of the <code>wrpc:signature</code> attribute, the method signature would be obtained following the order of the parameters. A sample
! mapping is provided below for the Java(TM) language. This example was created using JAX RPC 1.1 [<cite><a href="#jaxrpc">JAX RPC 1.1</a></cite>]
for mapping simple types to Java types and
designated inout and output parameters by using Holder classes.</p><div class="exampleOuter">
***************
*** 2176,2180 ****
</div>
<div class="div3">
! <h4><a 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 scalability. </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 class="exampleHead" style="text-align: left"><a name="reservationDetails_HTTP_example"></a><i><span>Example 7-19. </span>
--- 2173,2177 ----
</div>
<div class="div3">
! <h4><a 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 [<cite><a href="#rest">REST</a></cite>]. REST is a distillation of the architectural properties that Dr. Fielding identified as being vital to the Web's robustness and enormous scalability. </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 class="exampleHead" style="text-align: left"><a name="reservationDetails_HTTP_example"></a><i><span>Example 7-19. </span>
***************
*** 2327,2331 ****
<div class="div3">
! <h4><a name="N10FF3"></a>7.10.1 Schemas in Imported Documents</h4>
<p>
In this example, we consider some GreatH Hotel
--- 2324,2328 ----
<div class="div3">
! <h4><a name="N11014"></a>7.10.1 Schemas in Imported Documents</h4>
<p>
In this example, we consider some GreatH Hotel
***************
*** 2534,2538 ****
<div class="div3">
! <h4><a name="N1107E"></a>7.10.2 Multiple Inline Schemas in One Document</h4>
<p>
A WSDL 2.0 document may define multiple inline
--- 2531,2535 ----
<div class="div3">
! <h4><a name="N1109F"></a>7.10.2 Multiple Inline Schemas in One Document</h4>
<p>
A WSDL 2.0 document may define multiple inline
***************
*** 2668,2672 ****
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><div class="div4">
! <h5><a name="N110DB"></a>7.10.3.1 Using the id Attribute to Identify Inline
Schemas</h5><p>
<a href="#schemaIds.wsdl">Example 7-26</a>
--- 2665,2669 ----
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><div class="div4">
! <h5><a name="N110FC"></a>7.10.3.1 Using the id Attribute to Identify Inline
Schemas</h5><p>
<a href="#schemaIds.wsdl">Example 7-26</a>
***************
*** 2751,2756 ****
<h3><a name="adv-rdf-mapping"></a>7.11 Mapping to RDF and Semantic Web</h3>
<p>WSDL 2.0 is a language designed primarily with XML syntax. While XML is
! almost universally understood, it has several issues: </p><ul><li><p></p></li><li><p>The ability to compose two XML documents into one depends on the languages of those documents. WSDL 2.0 does not permit Web service descriptions
in different targetNamespaces to be merged into a single (physical) XML document. </p></li><li><p>The ability to extend XML languages with other XML languages depends on the
languages again. WSDL 2.0 is extremely extensible, but the meaning
--- 2748,2760 ----
<h3><a name="adv-rdf-mapping"></a>7.11 Mapping to RDF and Semantic Web</h3>
+
+ <table border="1" summary="Editorial note: KevinL"><tr><td width="50%" valign="top" align="left"><b>Editorial note: KevinL</b></td><td width="50%" valign="top" align="right">20050429</td></tr><tr><td valign="top" align="left" colspan="2">
+ This section might be removed - pending on the availability of the RDF mapping note. </td></tr></table>
+
+
<p>WSDL 2.0 is a language designed primarily with XML syntax. While XML is
! almost universally understood, it has several issues: </p>
!
! <ul><li><p>The ability to compose two XML documents into one depends on the languages of those documents. WSDL 2.0 does not permit Web service descriptions
in different targetNamespaces to be merged into a single (physical) XML document. </p></li><li><p>The ability to extend XML languages with other XML languages depends on the
languages again. WSDL 2.0 is extremely extensible, but the meaning
***************
*** 2766,2776 ****
specification. While an interface element could form a single XML
document, it is not a WSDL 2.0 document, so its meaning is largely undefined. </p></li></ul><p>Applications that require such levels of composability (or
! decomposability) are increasingly being based on RDF @@bibref@@, a graph-based
! knowledge representation language, and Web Ontology Language (OWL) @@bibref@@,
which can be thought of as an advanced schema language for RDF. Effectively,
a WSDL 2.0 document represented in RDF can be more easily extended with arbitrary
RDF assertions and the WSDL 2.0 information can be more easily associated with
! arbitrary other knowledge. </p><div class="div3">
! <h4><a name="adv-rdf-rep-wsdl"></a>7.11.1 RDF Representation of WSDL 2.0</h4><p><em>WSDL 2.0: Mapping to RDF</em> @@bibref@@ describes how WSDL 2.0 constructs can be
expressed in RDF using classes of resources (described with an ontology
expressed in OWL) and assertions over individual resources. As RDF represents knowledge using resources and relationships between
--- 2770,2784 ----
specification. While an interface element could form a single XML
document, it is not a WSDL 2.0 document, so its meaning is largely undefined. </p></li></ul><p>Applications that require such levels of composability (or
! decomposability) are increasingly being based on RDF [<cite><a href="#rdf">RDF</a></cite>], a graph-based
! knowledge representation language, and Web Ontology Language (OWL) [<cite><a href="#owl">OWL</a></cite>],
which can be thought of as an advanced schema language for RDF. Effectively,
a WSDL 2.0 document represented in RDF can be more easily extended with arbitrary
RDF assertions and the WSDL 2.0 information can be more easily associated with
! arbitrary other knowledge. </p>
!
! <div class="div3">
! <h4><a name="adv-rdf-rep-wsdl"></a>7.11.1 RDF Representation of WSDL 2.0</h4>
!
! <p><em>WSDL 2.0: Mapping to RDF</em> @@bibref@@ describes how WSDL 2.0 constructs can be
expressed in RDF using classes of resources (described with an ontology
expressed in OWL) and assertions over individual resources. As RDF represents knowledge using resources and relationships between
***************
*** 3059,3063 ****
http://www.w3.org/TR/xptr-framework/.
</dd>
!
</dl>
</div>
--- 3067,3117 ----
http://www.w3.org/TR/xptr-framework/.
</dd>
!
! <dt class="label"><a name="TAG-whenToUseGET"></a>[W3C TAG Finding: Use of HTTP GET] </dt><dd>
! <cite><a href="http://www.w3.org/2001/tag/doc/whenToUseGet.html">URIs, Addressability, and the use of HTTP GET and POST</a></cite>, Ian Jacobs, Editor. World Wide Web
! Consortium, 21 March 2004. This version of TAG finding is available at
! http://www.w3.org/2001/tag/doc/whenToUseGet.html
! </dd>
!
!
! <dt class="label"><a name="TAG-versioning"></a>[W3C TAG Finding: Versioning] </dt><dd>
! <cite><a href="http://www.w3.org/2001/tag/doc/versioning.html">Versioning XML Languages</a></cite> David Orchard, Norman Walsh. Proposed TAG Finding 16 November 2003. Available at
! http://www.w3.org/2001/tag/doc/versioning.html
! </dd>
!
!
! <dt class="label"><a name="web-extensible"></a>[WebArch: Extensible Languages] </dt><dd>
! <cite><a href="http://www.w3.org/TR/NOTE-webarch-extlang">Web Architecture: Extensible Languages</a></cite> , Tim Berners-Lee, Dan Connolly, Authors. W3C Note 10 Feb 1998. Available at http://www.w3.org/TR/NOTE-webarch-extlang
! </dd>
!
! <dt class="label"><a name="xsd-versioning"></a>[XML Schema: Versioning Use-Cases] </dt><dd>
! <cite><a href="http://www.w3.org/XML/2005/xsd-versioning-use-cases/">XML Schema Versioning Use Cases</a></cite> , Hoylen Sue. W3C XML Schema Working Group Draft, 15 April 2005. Available at http://www.w3.org/XML/2005/xsd-versioning-use-cases/
! </dd>
!
! <dt class="label"><a name="sw-vocabulary"></a>[SW VocabManagementNote] </dt><dd>
! <cite><a href="http://esw.w3.org/topic/VocabManagementNote">Vocabulary Management</a></cite> , Thomas Baker, et al. Semantic Web Best Practices and Deployment Working Group Note, 8 Feb 2005. Available at
! http://esw.w3.org/topic/VocabManagementNote
!
! </dd>
! <dt class="label"><a name="relax-ng"></a>[RELAX NG] </dt><dd>
! <cite><a href="http://www.oasis-open.org/committees/relax-ng/spec-20011203.html">RELAX NG Specification</a></cite>, James Clark, MURATA Makoto, Editors. OASIS Committee Specification, 3 December 2001. Available at http://www.oasis-open.org/committees/relax-ng/spec-20011203.html
! </dd>
!
! <dt class="label"><a name="jaxrpc"></a>[JAX RPC 1.1] </dt><dd>
! <cite><a href="http://java.sun.com/xml/downloads/jaxrpc.html">Java(TM) API for XML-based Remote Procedure Call (JAX-RPC) Specification, version 1.1</a></cite>, Roberto Chinnici,et al. 14 October, 2003. Available at http://java.sun.com/xml/downloads/jaxrpc.html
! </dd>
!
!
! <dt class="label"><a name="rest"></a>[REST] </dt><dd>
! <cite><a href="http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm">Representational State Transfer (REST)</a></cite>, Roy Thomas Fielding, Author. 2000. Available at http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
! </dd>
!
! <dt class="label"><a name="rdf"></a>[RDF] </dt><dd>
! <cite><a href="http://www.w3.org/TR/rdf-concepts/">Resource Description Framework (RDF): Concepts and Abstract Syntax</a></cite>, Graham Klyne, Jeremy J. Carroll, Editors. W3C Recommendation, 10 February 2004. Available at http://www.w3.org/TR/rdf-concepts/
! </dd>
!
! <dt class="label"><a name="owl"></a>[OWL] </dt><dd>
! <cite><a href="http://www.w3.org/TR/owl-ref/">OWL Web Ontology Language Reference</a></cite>, Mike Dean,Guus Schreiber, Editors. W3C Recommendation 10 February 2004 . Available at http://www.w3.org/TR/owl-ref/
! </dd>
</dl>
</div>
Received on Friday, 29 April 2005 23:39:23 UTC