- From: Kevin Liu via cvs-syncmail <cvsmail@w3.org>
- Date: Fri, 24 Jun 2005 22:13:57 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20 In directory hutz:/tmp/cvs-serv24496/ws/desc/wsdl20 Modified Files: wsdl20-primer.html wsdl20-primer.xml Log Message: Re-organized the "advanced topics" section to logically group the topics in the following order: importing mechanisms, extensibility and predefined extensions, and miscellanous topics. All topics are still under one "Advanced Topics" section Index: wsdl20-primer.xml =================================================================== RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v retrieving revision 1.106 retrieving revision 1.107 diff -C2 -d -r1.106 -r1.107 *** wsdl20-primer.xml 23 Jun 2005 21:59:24 -0000 1.106 --- wsdl20-primer.xml 24 Jun 2005 22:13:54 -0000 1.107 *************** *** 766,772 **** <div2 id="more-types-import-include-summary"><head>Summary of Import and Include Mechanisms</head> ! <p>The following table summarizes the similarities and differences between the WSDL 2.0 and XML Schema ! <el>include</el> and <el>import</el> mechanisms.</p> <table border="1" id='imin'> <caption> --- 766,772 ---- <div2 id="more-types-import-include-summary"><head>Summary of Import and Include Mechanisms</head> [...1616 lines suppressed...] ! <input messageLabel="In" element="#none" /> ! <output messageLabel="Out" ! element="wdetails:reservationDetails" /> ! </operation> ! ! </interface> ! ! </description>]]></eg></example></div4></div3></div2> --- 3556,3564 ---- </div2> ! <div2 id="adv-multiple-docs-describing-same-service"> ! <head>Multiple Interfaces for the Same Service</head> ! <p>Suppose a Web service wishes to expose two different interfaces: a customer interface for its regular users, and a management interface for its operator. A <code>wsdl:service</code> specifies only one wsdl:interface, so to achieve the desired effect the service provider would somehow need to indicate a relationship between two services. How can a service provider indicate a relationship between services? Potential strategies include:<ulist><item><p><b>Declare both interfaces in the same wsdl:description element.</b> Although WSDL 2.0 does not ascribe any particular significance to the fact that two wsdl:services are declared within the same wsdl:description, an application or toolkit could interpret this to mean that they are related in some way.</p></item><item><p><b>Declare both interfaces in the same wsdl:targetNamespace.</b> Again, although WSDL 2.0 does not ascribe any particular significance to the fact that two wsdl:services are declared within the same wsdl:targetNamespace, an appliction or toolkit could interpret this to mean that they are related in some way. ! </p></item><item><p><b>Add an extension to WSDL 2.0</b> that links together all services that are related in this way. WSDL 2.0's open content model permits extension elements from other namespaces to appear in a WSDL 2.0 document.</p></item><item><p><b>Declare them in completely separate WSDL 2.0 documents, but use the same endpoint address for both.</b> I.e., declare a <code>wsdl:interface</code> and <code>wsdl:service</code> for the customer interface in one WSDL 2.0 document, and a <code>wsdl:interface</code> and <code>wsdl:service</code> for the management interface in a different WSDL 2.0 document, but use the same endpoint address for both. (By "different WSDL 2.0 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 eb architectural principle that different URIs should be used to identify different Web resources. (See the Web Architecture <bibref ref="webarch"/> section on <xspecref href="http://www.w3.org/TR/webarch/#URI-collision">URI collision</xspecref>.)</p></item><item><p><b>Use inheritance to combine the customer interface and management interface</b> into a single, larger wsdl:interface. Of course, this reduces modularity and means that the management interface becomes exposed to the customers, which is not good. </p></item></ulist></p><p>Bear in mind that since the above strategies step outside of the WSDL 2.0 language specifies (and are therefore neither endorsed nor forbidden by the WSDL 2.0 specification) the WSDL 2.0 specification cannot define or standardize their semantics. </p><p>The desire to express relationships between services is also relevant to Web service versioning, discussed next.</p> ! </div2> Index: wsdl20-primer.html =================================================================== RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.html,v retrieving revision 1.78 retrieving revision 1.79 diff -C2 -d -r1.78 -r1.79 *** wsdl20-primer.html 23 Jun 2005 21:59:23 -0000 1.78 --- wsdl20-primer.html 24 Jun 2005 22:13:54 -0000 1.79 *************** *** 96,102 **** <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>A. <a href="#acknowledgments">Acknowledgements</a> (Non-Normative)<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 2.0 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="#bascs-interface">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> &nbs;3.2 <a href="#wsdl-schema">WSDL 2.0 Schema</a><br> 3.2.1 <a href="#element-order">WSDL2.0 Element Ordering</a><br> 3.3 <a href="#component-model">WSDL 2.0 Component Model</a><br> 3.3.1 <a href="#import-component">WSDL 2.0 Import and Include</a><br>4. <a href="#more-types">More on Message Types</a><br> 4.1 <a href="#more-types-schema-inline">Inlining 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-fults">Interface Faults</a><br> 5.4 <a href="#more-interfaces-operations">Interface Operations</a><br> 5.4.1 <a href="#more-interfaces-op-attr">Operation Attributes</a><br> 5.4.2 <a href="#N67927">Operation Message References</a><br> 5.4.2.1 <a href="#N67956">The messageLabel Attribute</a><br> 5.4.2.2 <a href="#N67980">The element Attribute</a><br> 5.4.2.3 <a href="#N68061">Multiple infault or outfault Elements</a><br> 5.4.3 <a href="#more-interfaces-meps">Understanding 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 Bidings</a><br> 6.2 <a href="#more-bindings-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="#N68519">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.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-MEP">Defining New MEPs</a><br> 7.3.1 <a href="#challenge-confirm">Confirmed Challenge</a><br> 7.4 <a href="#adv-import-and-athoring">Importing WSDL</a><br> 7.5 <a href="#adv-multiple-docs-describing-same-service">Multiple Interfaces for the Same Service</a><br> 7.6 <a href="#adv-versioning">Web Service Versioning</a><br> 7.6.1 <a href="#adv-versioning-compatible-evolution">Compatible Evolution</a><br> 7.6.2 <a href="#adv-versioning-big-bang">Big Bang</a><br> 7.6.3 <a href="#ad-versioing-migration">Evolving a Service</a><br> 7.6.4 <a href="#adv-versioning-combined">Combined Approaches</a><br> 7.6.5 <a href="#adv-versioning-examples">Examples of Versioning and Extending a Service</a><br> 7.6.5.1 <a href="#N69521">Additional Optional Elements Added in Content</a><br> &nsp; 7.6.5.2 <a href="#N69544">Additional Optional Elements Added to a Header</a><br> 7.6.5.3 <a href="#N69567">Additional Mandatory Elements in Content</a><br> 7.6.5.4 <a href="#N69590">Additional Optional Operation Added to Interface</a><br> 7.6.5.5 <a href="#N69602">Additional Mandatory Operation Added to Interface</a><br> 7.6.5.6 <a href="#N69628">Indicating Incompatibility by Changing the Endpoint URI</a><br> 7.6.5.7 <a href="#N69637">Indicating Incompatibility by Changing the SOAP Action</a><br> 7.6.5.8 <a href="#N69660">Indicating Incomptibility by Changing the Element Content</a><br> 7.7 <a href="#adv-MTOM">MTOM Support</a><br> 7.8 <a href="#adv-RPCstyle">RPC Style</a><br> 7.9 <a href="#adv-message-dispatch">Enabling Easy Message Dispatch</a><br> 7.10 <a href="#adv-service-references">Describing Web Service Messages That Refer to Other Web Services</a><br> 7.10.1 <a href="#reservationDetails">The Reservation Details Web Service</a><br> 7.10.2 <a href="#reservationList">The Reservation List Web Service</a><br> 7.10.3 <a href="#reservationDetails_HTTP">Reservation Details Web Service Using HTTP Transfer</a><br> 7.10.4 <a href="#reservationList_HTTP_GET">Reservation List Web Service Using HTTP GET</a><br> 7.11 <a href="#adv-multiple-inline-scheas">Importing Schemas</a><br> 7.11.1 <a href="#N70334">Schemas in Imported Documents</a><br> 7.11.2 <a href="#N70473">Multiple Inline Schemas in One Document</a><br> 7.11.3 <a href="#adv-schema-location">The schemaLocation Attribute</a><br> 7.11.3.1 <a href="#N70569">Using the id Attribute to Identify Inline ! Schemas</a><br> 7.12 <a href="#adv-rdf-mapping">Mapping to RDF and Semantic Web</a><br> 7.12.1 <a href="#adv-rdf-rep-wsdl">RDF Representation of WSDL 2.0</a><br> 7.13 <a href="#adv-notes-on-uris">Notes on URIs</a><br> 7.13.1 <a href="#adv-namespaces-and-schema-locations">XML Namespaces and Schema Locations</a><br> 7.13.2 <a href="#adv-relative-uris">Relative URIs</a><br> 7.13.3 <a href="#adv-generating-uris">Generating Temporary URIs</a><br>8. <a href="#References">References</a><br> 8.1 <a href="#Normative-References">Normative References</a><br> 8.2 <a href="#Informative-References">Informative References</a><br></p> <h3><a name="appendix" id="appendix">Appendix</a></h3><p class="toc">A. <a href="#acknowledgments">Acknowledgements</a> (Non-Normative)<br></p></div><hr><div class="body"> --- 96,102 ---- <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>A. <a href="#acknowledgments">Acknowledgements</a> (Non-Normative)<br></p></div><hr><div class="toc"> [...2397 lines suppressed...] ! <output messageLabel="Out" ! element="wdetails:reservationDetails" /> ! </operation> ! ! </interface> ! ! </description></pre></div></div></div></div></div> --- 3641,3650 ---- </div> <div class="div2"> ! <h3><a name="adv-multiple-docs-describing-same-service"></a>7.11 Multiple Interfaces for the Same Service</h3> ! <p>Suppose a Web service wishes to expose two different interfaces: a customer interface for its regular users, and a management interface for its operator. A <code>wsdl:service</code> specifies only one wsdl:interface, so to achieve the desired effect the service provider would somehow need to indicate a relationship between two services. How can a service provider indicate a relationship between services? Potential strategies include:<ul><li><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></li><li><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 oolkit could interpret this to mean that they are related in some way. ! </p></li><li><p><b>Add an extension to WSDL 2.0</b> that links together all services that are related in this way. WSDL 2.0's open content model permits extension elements from other namespaces to appear in a WSDL 2.0 document.</p></li><li><p><b>Declare them in completely separate WSDL 2.0 documents, but use the same endpoint address for both.</b> I.e., declare a <code>wsdl:interface</code> and <code>wsdl:service</code> for the customer interface in one WSDL 2.0 document, and a <code>wsdl:interface</code> and <code>wsdl:service</code> for the management interface in a different WSDL 2.0 document, but use the same endpoint address for both. (By "different WSDL 2.0 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 archtectural principle that different URIs should be used to identify different Web resources. (See the Web Architecture [<cite><a href="#webarch">Web Architecture</a></cite>] section on <a href="http://www.w3.org/TR/webarch/#URI-collision">URI collision</a>.)</p></li><li><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></li></ul></p><p>Bear in mind that since the above strategies step outside of the WSDL 2.0 language specifies (and are therefore neither endorsed nor forbidden by the WSDL 2.0 specification) the WSDL 2.0 specification cannot define or standardize their semantics. </p><p>The desire to express relationships between services is also relevant to Web service versioning, discussed next.</p> ! </div>
Received on Friday, 24 June 2005 22:14:01 UTC