- From: David Booth via cvs-syncmail <cvsmail@w3.org>
- Date: Sun, 17 Apr 2005 02:42:42 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20
In directory hutz:/tmp/cvs-serv13346
Modified Files:
wsdl20-primer.xml wsdl20-primer.html
Log Message:
Finished updating/editing through sec 6; deleted sec 7 ("More on Endpoints")
because it is now redundant and unnecessary.
Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.49
retrieving revision 1.50
diff -C2 -d -r1.49 -r1.50
*** wsdl20-primer.xml 16 Apr 2005 17:23:43 -0000 1.49
--- wsdl20-primer.xml 17 Apr 2005 02:42:40 -0000 1.50
***************
*** 1061,1112 ****
! <div3 id="more-bindings-soap-example-explanation"><head>Explanation of Example</head><p><glist><gitem><label><code>xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"</code></label><def><p>This is the namespace for the WSDL 2.0 SOAP binding extension defined in WSDL 2.0 Part 3 <bibref ref="SOAP12-PART1"/>. </p></def></gitem><gitem><label><code>xmlns:soap="http://www.w3.org/2003/05/soap-envelope"</code></label><def><p>This is the namespace for terms defined within the SOAP 1.2 specification <bibref ref="SOAP12-PART1"/>.</p></def></gitem><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></labl><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></def></gitem></glist></p>
</div3></div2>
<div2 id="more-bindings-http">
! <head>Extensions for HTTP Binding</head>
! <example id="example-bindings-http">
! <head>HTTP Binding example placeholder - to be completed</head>
<eg xml:space="preserve">
! <description
! targetNamespace= "http://greath.example.com/2004/wsdl/resSvc"
! xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc"
! xmlns = "http://www.w3.org/2004/08/wsdl"
! xmlns:xs="http://www.w3.org/2001/XMLSchema">
! </description>
! </eg>
</example>
! </div2>
! </div1>
! <!-- **********************************Service************************** -->
! <!-- **********************************Service************************** -->
! <div1 id="more-service">
! <head>More on Service Endpoints </head>
! <ednote><name>dbooth</name><edtext>This section now seems largely redundant. Perhaps we should reduce or eliminate it.</edtext></ednote><p>As described previously, the <code>service</code> construct specifies a set of alternate endpoints at which a service is available. Zero or more <code>services</code> can be defined within a <code>description</code> element. However, each service is limited to a single interface. The XML syntax of <code>service</code> is summarized below:</p>
! <eg xml:space="preserve">
! <description targetNamespace="<emph>xs:anyURI</emph>" >
! <service name="<emph>xs:NCName</emph>" interface="<emph>xs:QName</emph>"
! <documentation />?
! <endpoint name="<emph>xs:NCName</emph>" binding="<emph>xs:QName</emph>" >
! <documentation />?
! </endpoint>+
! </service>*
! </description>
! </eg>
! <p>A <code>service</code> has a required <att>name</att> attribute (also see section @@@@ for service reference). Each <code>service</code> within a same namespace must be named uniquely. A <code>service</code> can only implement one single interface, and it must specify the single interface it implements via the <att>interface</att> attribute. </p>
! <p>A <code>service</code> may contain one or more alternate <code>endpoints</code>. An <code>endpoint</code> defines the particulars of a specific endpoint at which a given service is available.</p>
! <p>An <code>endpoint</code> has two required attributes: <att>name</att> and <att>binding</att>. All <code>endpoints</code> within a <code>service</code> must be named uniquely via the <att>name</att> attribute. The required <att>binding</att> attribute refers to, via QName, a <code>binding</code> definition. Note that if the refered <code>binding</code> specifies a particular interface, that interface MUST be the same as the one implmented by the parent <code>service</code>. </p>
! <p>Like the WSDL binding constructs explained in section @@@@, the WSDL <code>endpoint</code> construct is also like an anchor for hosting extension elements that are used to provide information specific to a
! particular endpoint in a server. The semantics of such extensions are defined by the specification for those extensions. Such specifications are expected to annotate the WSDL <code>endpoint</code>
! construct with additional properties and specify the mapping between
! those properties and the XML representation. For example, the SOAP and
! HTTP binding extensions defined in WSDL 2.0 Part 2
! <bibref ref="WSDL-PART2"/> also provide extensions to be used under a service <code>endpoint</code>. </p>
! </div1>
--- 1061,1123 ----
! <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>
<div2 id="more-bindings-http">
! <head>The HTTP Binding Extension</head>
! <p>In addition to the WSDL 2.0 SOAP binding extension described above, WSDL 2.0 Part 2 <bibref ref="WSDL-PART2"/> defines a binding extension for HTTP 1.1 <bibref ref="RFC2616"/> and HTTPS <bibref ref="RFC2818"/>, so that these protocols can be used natively to send and receive messages, without first encoding them in SOAP.</p><p>The HTTP binding extension provides many features to control:<ulist><item><p> Which HTTP operation will be used. (GET, PUT, POST, DELETE, and other HTTP operations are supported.)</p></item><item><p>Input, output and fault serialization</p></item><item><p>Transfer codings</p></item><item><p>Authentication requirements</p></item><item><p>Cookies</p></item><item><p>HTTP over TLS (https)</p></item></ulist></p><p>As with the WSDL 2.0 SOAP binding extension, the HTTP binding extension also provides defaulting rules to permit binding information to be specified at the interface level and used by default for each operation in the affected interface, however, defaulting rules are nt provided for binding faults.</p><p>Here is an example of using the HTTP binding extension to check hotel room
! availability at GreatH.</p><example id="example-bindings-http">
! <head>HTTP Binding Extension</head>
<eg xml:space="preserve">
! <![CDATA[<?xml version="1.0" encoding="utf-8" ?>
! <description xmlns="http://www.w3.org/2004/08/wsdl"
! . . .
! xmlns:whttp="http://www.w3.org/@@@@/@@/wsdl/http" >
! . . .
! <binding name="reservationHTTPBinding"
! interface="tns:reservationInterface"
! whttp:methodDefault="GET">
!
! <operation ref="tns:opCheckAvailability"
! whttp:location="{tCheckAvailability}" >
! </binding>
!
! <service name="reservationService"
! interface="tns:reservationInterface">
!
! <!-- HTTP 1.1 GET End Point -->
! <endpoint name="reservationEndpoint"
! binding="tns:reservationHTTPBinding"
! address="http://greath.example.com/2004/"/>
!
! </service>
! . . .
! </description>]]></eg>
</example>
! <div3><head>Explanation of Example</head><p><glist><gitem><label><code>xmlns:whttp="http://www.w3.org/@@@@/@@/wsdl/http" ></code></label><def><p>This defines the namespace prefix for elements and attributes defined by the WSDL 2.0 HTTP binding extension.</p></def></gitem><gitem><label><code>whttp:methodDefault="GET"></code></label><def><p>The default method for operations in this interface will be HTTP GET.</p></def></gitem><gitem><label><code>whttp:location="{tCheckAvailability}" ></code></label><def><ednote><name>dbooth</name><date>2005-04-15</date><edtext>ToDo: Check this section. I'm not sure I got it all right. In particular, is the first sample request URI correct? Shouldn't values be in the path component?</edtext></ednote><p>The <code>whttp:location</code> attribute specifies a pattern for serializing input message instance data into the path component of the request URI. The default binding rules for HTTP specify that the default input
! serialization for GET is <code>application/x-www-form-urlencoded</code>. Curly braces are used to specify the name of a schema type in the input message schema, which determines what input instance data will be inserted into the path component of the request URI. The curly brace-enclosed name will be replaced with instance data in constructing the path component. Remaining input instance data (not specified by <code>whttp:location</code>) will either be serialized into the query string portion of the URI or into the message body, as follows: if a "/" is appended to a curly brace-enclosed type name, then any remaining input message instance data will be serialized into the message body. Otherwise it will be serialized into query parameters.</p><p>Thus, in this example, each of the elements in the <code>tCheckAvailability</code> type will be serialized into
! the query parameters.
! A sample
! resulting URI for would therefore be
! <code>http://greath.example.com/2004/?checkInDate=5-5-5&checkOutDate=6-6-5&roomType=foo</code>
! . </p></def></gitem></glist></p><p>Here is an alternate example that serializes appends "/" to the type name in order to serialize the remaining instance data into the message body:</p><example id="example-bindings-http-path-subsset">
! <head>Serializing a Subset of Types in the Path</head>
! <eg xml:space="preserve">
! <![CDATA[
! . . .
! <operation ref="tns:opCheckAvailability"
! whttp:location="bycheckInDate/{checkInDate/}" >
! . . .
! ]]></eg>
! </example><p>
!
! This would instead serialize to a request URI such as: <code>http://greath.example.com/2004/bycheckInDate/5-5-5</code></p></div3></div2>
! </div1>
!
***************
*** 1114,1118 ****
<!-- **********************************AdvancedTopics***************** -->
<div1 id="advanced-topic_ii">
! <head>Advanced Topics - TBD</head>
<ednote>
<name>KevinL</name>
--- 1125,1129 ----
<!-- **********************************AdvancedTopics***************** -->
<div1 id="advanced-topic_ii">
! <head>Advanced Topics</head>
<ednote>
<name>KevinL</name>
***************
*** 1125,1129 ****
<div2 id="adv-extensibility">
<head>Extensibility</head>
! <p>WSDL 2.0 provides two extensibility mechanisms: an open content model, which allows XML elements and attributes from other (non-WSDL 2.0) XML namespaces to be interspersed into a WSDL document; and <xspecref href="&w3c-designation-part1;#Feature">Features</xspecref> and <xspecref href="&w3c-designation-part1;#Property">Properties</xspecref>. Both mechanisms use URIs to identify the semantics of the extensions. For extension XML elements and attributes, the namespace URI of the extension element or attribute acts as an unambiguous name for the semantics of that extension. For Features and Properties, the Feature or Property is named by a URI.</p><p>In either case, the URI that identifies the semantics of an extension SHOULD be dereferenceable to a document that describes the semantics of that extension. As of this writing, there is no generally accepted standard for what kind of document that should be. However, the <loc href="http://www.w3.org/2001/tag/">W3C TAG</loc> has been discussing the ssue (see TAG issue <loc href="http://www.w3.org/2001/tag/issues.html?type=1#namespaceDocument-8">namespaceDocument-8</loc>) and is likely to provide guidance at some point.</p><div3 id="adv-optional-versus-required"><head>Optional Versus Required Extensions</head><p>Extensions can either be required or optional: An <emph>optional</emph> extension is one that the client may either engage or ignore, entirely at its discretion, and is signaled by attribute <code>wsdl:required="false"</code>; whereas a <emph>required</emph> extension is one that MUST be supported and engaged by the client in order for the interaction to succeed properly, and is signaled by attribute <code>wsdl:required="true"</code>. </p><p>The optionality signaled by <code>wsdl:required="false"</code> pertains only to the <emph>client</emph> -- not the service. The service MUST support both optional and required extensions that it advertises in its WSDL document. </p><p>A WSDL processor (acting to realize a client) need not support everyconceivable required extension, but if it sees a required extension that it does not recognize or does not support, then it MUST fault. </p></div3><div3 id="adv-scope-of-wsdl-required"><head>Scoping of the wsdl:required Attribute</head><ednote><edtext>To do: Need to check the scoping rules to see if this is correct.</edtext></ednote><p>As a convenience mechanism, the <code>wsdl:required</code> attribute need not be specified on every extension element. If it is omitted from an extension element, its effective value is inherited from the smallest enclosing scope that explicitly sets its value. If there is no enclosing scope that explicitly sets its value, then its value defaults to <code>false</code>. </p><p>Because portions of a Web service description can be written in different physical documents by different people, one should be cautious about setting <code>wsdl:required="false"</code> when an outer scope, written by someone else, had set <code>wsdl:required="true"</code>.</p></div3></div2><div2 i="adv-FP">
<head>Features and Properties</head>
--- 1136,1140 ----
<div2 id="adv-extensibility">
<head>Extensibility</head>
! <p>WSDL 2.0 provides two extensibility mechanisms: an open content model, which allows XML elements and attributes from other (non-WSDL 2.0) XML namespaces to be interspersed into a WSDL document; and <xspecref href="&w3c-designation-part1;#Feature">Features</xspecref> and <xspecref href="&w3c-designation-part1;#Property">Properties</xspecref>. Both mechanisms use URIs to identify the semantics of the extensions. For extension XML elements and attributes, the namespace URI of the extension element or attribute acts as an unambiguous name for the semantics of that extension. For Features and Properties, the Feature or Property is named by a URI.</p><p>In either case, the URI that identifies the semantics of an extension SHOULD be dereferenceable to a document that describes the semantics of that extension. As of this writing, there is no generally accepted standard for what kind of document that should be. However, the <loc href="http://www.w3.org/2001/tag/">W3C TAG</loc> has been discussing the ssue (see TAG issue <loc href="http://www.w3.org/2001/tag/issues.html?type=1#namespaceDocument-8">namespaceDocument-8</loc>) and is likely to provide guidance at some point.</p><div3 id="adv-optional-versus-required"><head>Optional Versus Required Extensions</head><p>Extensions can either be required or optional.</p><p>An <emph>optional</emph> extension is one that the client may either engage or ignore, entirely at its discretion, and is signaled by attribute <code>wsdl:required="false"</code> or the absence of the <code>wsdl:required</code> attribute (because it defaults to false). Thus, a WSDL processor, acting on behalf of the client, that encounters an unknown optional extension can safely ignore it and continue to process the WSDL 2.0 document. However, it is important to stress that optional extensions are only optional to the <emph>client</emph> -- not the service. A service MUST support all optional and required extensions that it advertises in its WSDL 2.0 document. </p><p>A <emph>required</mph> extension is one that MUST be supported and engaged by the client in order for the interaction to procede properly, and is signaled by attribute <code>wsdl:required="true"</code>. If a WSDL processor, acting on behalf of the client, encounters a required extension that it does not recognize or does not support, then it cannot safely continue to process the WSDL 2.0 document. In most practical cases, this is likely to mean that it will have to fault and seek user intervention. </p></div3><div3 id="adv-scope-of-wsdl-required"><head>Scoping of the wsdl:required Attribute</head><ednote><edtext>ToDo: Need to check the scoping rules to see if this is correct.</edtext></ednote><p>As a convenience mechanism, the <code>wsdl:required</code> attribute need not be specified on every extension element. If it is omitted from an extension element, its effective value is inherited from the smallest enclosing scope that explicitly sets its value. If there is no enclosing scope that explicitly sets its value, thenits value defaults to <code>false</code>. </p><p>Because portions of a Web service description can be written in different physical documents by different people, one should be cautious about setting <code>wsdl:required="false"</code> when an outer scope, written by someone else, had set <code>wsdl:required="true"</code>.</p></div3></div2><div2 id="adv-FP">
<head>Features and Properties</head>
***************
*** 1292,1296 ****
</div2><div2 id="adv-multiple-docs-describing-same-service">
<head>Multiple Interfaces for the Same Service</head>
! <p>Suppose a Web service wishes to expose two different interfaces: a customer interface for its regular users, and a management interface for its operator. WSDL 2.0 limits a wsdl:service to a single wsdl:interface, and does not provide any mechanisms to formally indicate this kind of relationship between interfaces. How can service providers work around this limitation? Conventions outside of the WSDL 2.0 language can be used, but since they are outside of the WSDL 2.0 language (and therefore neither endorsed nor forbidden by the WSDL 2.0 specification) the WSDL 2.0 specification cannot define or standardize their semantics. With that caveat in mind, potential workarounds include:<ulist><item><p><b>Declare both interfaces in the same wsdl:description element.</b> Although WSDL 2.0 does not ascribe any particular significance to the fact that two wsdl:services are declared within the same wsdl:description, an application or toolkit could interpret this to mean that they are related in some way.<p></item><item><p><b>Declare both interfaces in the same wsdl:targetNamespace.</b> Again, although WSDL 2.0 does not ascribe any particular significance to the fact that two wsdl:services are declared within the same wsdl:targetNamespace, an application or toolkit could interpret this to mean that they are related in some way.
</p></item><item><p><b>Add an extension to WSDL 2.0</b> that links together all services that are related in this way. WSDL 2.0's open content model permits extension elements from other namespaces to appear in a WSDL document.</p></item><item><p><b>Declare them in completely separate WSDL documents, but use the same endpoint address for both.</b> I.e., declare a wsdl:interface and wsdl:service for the customer interface in one WSDL document, and a wsdl:interface and wsdl:service for the management interface in a different WSDL document, but use the same endpoint address for both. (By "different WSDL document" we mean that both documents are never included or imported into the same WSDL 2.0 descriptions component.) Although this approach may work in some circumstances, it means that the same endpoint address would be used for two different purposes, which is apt to cause confusion or ambiguity. Furthermore, it is contrary to the Web architectural principle that different URIs should be used to identiy different Web resources. [Ref W3C TAB WebArch http://www.w3.org/TR/webarch/#URI-collision ]
</p></item><item><p><b>Use inheritance to combine the customer interface and management interface</b> into a single, larger wsdl:interface. Of course, this reduces modularity and means that the management interface becomes exposed to the customers, which is not good. </p></item></ulist></p>
--- 1303,1307 ----
</div2><div2 id="adv-multiple-docs-describing-same-service">
<head>Multiple Interfaces for the Same Service</head>
! <p>Suppose a Web service wishes to expose two different interfaces: a customer interface for its regular users, and a management interface for its operator. WSDL 2.0 limits a wsdl:service to a single wsdl:interface, and does not provide any mechanisms to formally indicate this kind of relationship between interfaces. How can service providers indicate a relationship between services? Conventions outside of the WSDL 2.0 language can be used, but since they are outside of the WSDL 2.0 language (and therefore neither endorsed nor forbidden by the WSDL 2.0 specification) the WSDL 2.0 specification cannot define or standardize their semantics. With that caveat in mind, potential strategies include:<ulist><item><p><b>Declare both interfaces in the same wsdl:description element.</b> Although WSDL 2.0 does not ascribe any particular significance to the fact that two wsdl:services are declared within the same wsdl:description, an application or toolkit could interpret this to mean that they are related i some way.</p></item><item><p><b>Declare both interfaces in the same wsdl:targetNamespace.</b> Again, although WSDL 2.0 does not ascribe any particular significance to the fact that two wsdl:services are declared within the same wsdl:targetNamespace, an application or toolkit could interpret this to mean that they are related in some way.
</p></item><item><p><b>Add an extension to WSDL 2.0</b> that links together all services that are related in this way. WSDL 2.0's open content model permits extension elements from other namespaces to appear in a WSDL document.</p></item><item><p><b>Declare them in completely separate WSDL documents, but use the same endpoint address for both.</b> I.e., declare a wsdl:interface and wsdl:service for the customer interface in one WSDL document, and a wsdl:interface and wsdl:service for the management interface in a different WSDL document, but use the same endpoint address for both. (By "different WSDL document" we mean that both documents are never included or imported into the same WSDL 2.0 descriptions component.) Although this approach may work in some circumstances, it means that the same endpoint address would be used for two different purposes, which is apt to cause confusion or ambiguity. Furthermore, it is contrary to the Web architectural principle that different URIs should be used to identiy different Web resources. [Ref W3C TAB WebArch http://www.w3.org/TR/webarch/#URI-collision ]
</p></item><item><p><b>Use inheritance to combine the customer interface and management interface</b> into a single, larger wsdl:interface. Of course, this reduces modularity and means that the management interface becomes exposed to the customers, which is not good. </p></item></ulist></p>
***************
*** 2707,2710 ****
--- 2718,2727 ----
1999. Available at http://www.ietf.org/rfc/rfc2616.txt.
</bibl>
+ <bibl id="RFC2818" key="IETF RFC 2818" href="http://www.ietf.org/rfc/rfc2818.txt">
+ <titleref>HTTP Over TLS</titleref>,
+ E. Rescorla, Author. Internet Engineering
+ Task Force, May 2000. Available at
+ http://www.ietf.org/rfc/rfc2818.txt.
+ </bibl>
<bibl id="SOAP11" key="SOAP 1.1" href="http://www.w3.org/TR/2000/NOTE-SOAP-20000508/">
<titleref>Simple Object Access Protocol (SOAP)
Index: wsdl20-primer.html
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.html,v
retrieving revision 1.30
retrieving revision 1.31
diff -C2 -d -r1.30 -r1.31
*** wsdl20-primer.html 16 Apr 2005 23:40:23 -0000 1.30
--- wsdl20-primer.html 17 Apr 2005 02:42:40 -0000 1.31
***************
*** 1,4 ****
! <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
! <html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Web Services Description Language (WSDL) Version 2.0 Part 0: Primer</title><style type="text/css">
code { font-family: monospace; }
--- 1,14 ----
! <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
! "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
! <html lang="en" xmlns="http://www.w3.org/1999/xhtml">
! <head>
! <meta name="generator"
[...7321 lines suppressed...]
!
! <dt class="label"><a id="XPTR" name="XPTR"></a>[XPointer
! Framework]</dt>
!
! <dd><cite><a
! href="http://www.w3.org/TR/2003/REC-xptr-framework-20030325/">XPointer
! Framework</a></cite>,Paul Grosso, Eve Maler, Jonathan Marsh, Norman
! Walsh, Editors. World Wide Web Consortium, 22 November 2002. This
! version of the XPointer Framework Proposed Recommendation is
! http://www.w3.org/TR/2003/REC-xptr-framework-20030325/ The <a
! href="http://www.w3.org/TR/xptr-framework/">latest version of
! XPointer Framework</a> is available at
! http://www.w3.org/TR/xptr-framework/.</dd>
! </dl>
! </div>
! </div>
! </div>
! </body>
! </html>
Received on Sunday, 17 April 2005 02:42:45 UTC