- From: Kevin Liu via cvs-syncmail <cvsmail@w3.org>
- Date: Tue, 14 Jun 2005 22:39:22 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20 In directory hutz:/tmp/cvs-serv21312/ws/desc/wsdl20 Modified Files: wsdl20-primer.html wsdl20-primer.xml Log Message: incorporated Amy's contribution about "defining new MEPs" Index: wsdl20-primer.xml =================================================================== RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v retrieving revision 1.93 retrieving revision 1.94 diff -C2 -d -r1.93 -r1.94 *** wsdl20-primer.xml 13 Jun 2005 19:22:52 -0000 1.93 --- wsdl20-primer.xml 14 Jun 2005 22:39:19 -0000 1.94 *************** *** 875,903 **** </example> ! </div3> ! ! <div3 id="more-interfaces-defining-meps"><head>Defining New Message Exchange Patterns (MEPs)</head><p>Although the eight MEPs defined in WSDL 2.0 Part 2 <bibref ref="WSDL-PART2"/> are intended to cover most use cases, WSDL 2.0 has designed this set to be extensible. This is why MEPs are identified by URIs rather than a fixed set of tokens. Here are the general steps for defining a new MEP. ! ! <ednote> ! <name>KevinL</name> ! <date>20050519</date> ! <edtext> ! This section is subject to change. The WG has decided to add a template for defining new MEPs in part 2, and provide an example here. ! </edtext> ! </ednote> ! ! <olist><item><p>Search around on the Web to see if somebody else has already defined ! an MEP that is close enough to what you want. If others are already using an MEP that fits your needs, it will reduce the effort required in step 4 to get other people to adopt yours. </p></item><item><p>Write an HTML document that clearly defines the MEP, and publish it at a ! stable URL -- see <loc href="http://purl.org/">purl.org</loc>, for example -- that will represent the full, formal name of the MEP, such as ! http://example.com/2005/ws/in-multi-out. ! ! (This is a fictitious example: "example.com" is a standard fictitious domain name. You, of course, must use an appropriate real domain and URL.) </p></item><item><p>Write and publish a corresponding specification for a binding extension that implements your MEP. ! ! </p></item><item><p>Publicize your new MEP and binding extension, and get others to ! support them in their WSDL toolkits. ! ! </p></item></olist></p><p>Note that the above procedure does NOT cause your MEP to become ! automatically recognized and usable by WSDL toolkits. It simply ! provides a well-defined convention for naming and reusing them.</p></div3></div2> </div1> --- 875,880 ---- </example> ! <p>Although the eight MEPs defined in WSDL 2.0 Part 2 <bibref ref="WSDL-PART2"/> are intended to cover most use cases, WSDL 2.0 has designed this set to be extensible. This is why MEPs are identified by URIs rather than a fixed set of tokens.</p> ! <p>For more about defining new MEPs, see <specref ref="adv-MEP"/>. </p></div3></div2> </div1> *************** *** 1212,1216 **** . . . ]]></eg> ! </example><p>First we define, in the <code>types</code> section, an XML Schema restriction type over integers with minimum and maximum values, per our discussion above. Then instead of using the <code>value</code> element inside <code>property</code>, we use <code>constraint</code> and refer to the restriction type. This informs the implementation that the property must have the appropriate values. This information might be useful to a deployment user interface, for example, which might allow an administrator to set this value with a slider when deploying the service.</p></div3></div2><div2 id="adv-import-and-authoring"> <head>Import mechanism and authoring style</head> --- 1189,1381 ---- . . . ]]></eg> ! </example><p>First we define, in the <code>types</code> section, an XML Schema restriction type over integers with minimum and maximum values, per our discussion above. Then instead of using the <code>value</code> element inside <code>property</code>, we use <code>constraint</code> and refer to the restriction type. This informs the implementation that the property must have the appropriate values. This information might be useful to a deployment user interface, for example, which might allow an administrator to set this value with a slider when deploying the service.</p></div3></div2> ! ! ! ! <div2 id="adv-MEP"> ! <head>Defining New MEPs</head> ! ! <p>As we mentioned in <specref ref= "more-interfaces-meps"/>, even though the 8 MEPs defined by WSDL2.0 are intented to cover most of the common use cases, there are situations that require new MEPs to be defined. In this section, we will explain how new MEPs can be defined to address special business requirements.</p> ! ! <p>Following the wild success of its reservation service, GreatH discovered ! that it could radically increase tourist interest by supplying information ! on weather conditions, both to travel agents and to the general touring ! public. This produced a challenge for the service implementors: how could ! this information be supplied to interested parties without requiring ! knowledge of web service technology specifically, and of computers ! generally? At issue was the desire to provide asynchronous updates to ! unsophisticated customers without incurring onerous overheads for technical ! support.</p> ! ! <p>The solution adopted was to create a standard mailing ! list, and to make available a small cross-platform web service client ! (actually, a subscriber) that could be installed on any computer with POP or ! IMAP access to a mailbox. The mailbox, once signed up for the mailing list, ! could either be processed as "dedicated" (to the GreatH weather service; ! travel agents did this) or as "general purpose" (in which case the ! application would only examine those emails that contained Subject headers ! associated with the service). This required development of a binding to ! email, which is out of scope for this example, but the resulting WSDL was ! otherwise quite straightforward.</p> ! ! <p>Note: the email binding in use here supports publish/subscribe, by ! supporting the robust-out-only MEP as well as the client/server style in-out ! used for subscribing and unsubscribing. Details of this binding would ! require a document as long as the primer, so play along.</p> ! ! <example id="weather-not-initial"> ! <head>Weather Notification Service (Initial)</head> ! <eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?> ! <description xmlns="http://www.w3.org/2005/05/wsdl" ! targetNamespace=http://greath.example.com/@@@@/wsdl/weathSvc.wsdl" ! xmlns:tns=http://greath.example.com/@@@@/wsdl/weathSvc.wsdl" ! xmlns:wsoap="http://www.w3.org/2005/05/wsdl/soap" ! xmlns:email="http://www.example.com/webservices/email" > ! ! <types> ! . . . ! </types> ! ! <interface name="weatherInterface"> ! <operation name="opSubscribeWeather" ! pattern="http://www.w3.org/2005/05/wsdl/in-out"> ! <input element=". . ." /> ! <output element=". . ." /> ! </operation> ! <operation name="opUnsubscribeWeather" ! pattern="http://www.w3.org/2005/05/wsdl/in-out"> ! <output element=". . ." /> ! <input element=". . ." /> ! </operation> ! <operation name="opNotifyWeather" ! pattern="http://www.w3.org/2005/05/wsdl/robust-out-only"> ! <output element=". . ." /> ! </operation> ! </interface> ! ! <binding name="weatherMailingListBinding" ! interface="tns:weatherInterface ! type="http://www.w3.org/2005/05/wsdl/soap" ! wsoap:protocol="http://www.example.com/bindings/email"> ! . . . ! </binding> ! ! <service name="weatherService" ! interface="tns:weatherInterface"> ! <endpoint name="greatHWeatherList" ! binding="tns:weatherMailingListBinding" ! address="mailto:weather-owner@greath.example.com" /> ! </service> ! ! </description> ! ]]></eg></example> ! ! <p>Note: in the example, the messageLabels of all input and output elements ! have been elided, as they are not necessary to disambiguate (but note that ! the order of input and output elements is not significant).</p> ! ! <p>Unfortunately, the service was soon highjacked for the ! purpose of annoyment. Repeatedly, hotels in less salubrious climes, and the ! victims of various natural climactic disasters (hurricanes, tornadoes) found ! themselves signed up to receive material full of incomprehensible pointy ! brackets. They complained to GreatH, who complained to their service ! designers.</p> ! ! <p>Applying public key infrastructure to solving ! the problem was immediately rejected as too complex and too heavyweight. ! Analysis showed that the problem was simply to verify that the address ! requesting information actually wanted that information. Consequently, a ! new message exchange pattern was defined.</p> ! ! <div3 id="challenge-confirm"> ! <head>Confirmed Challenge</head> ! <p>This pattern consists of two or more messages in order as follows:</p> ! <olist> ! <item><p>A message:</p> ! <ulist> ! <item><p>indicated by a Message Label component whose ! message label is <attval>Request</attval> and ! direction is <attval>in</attval></p></item> ! <item><p>received from some node N1</p></item> ! </ulist> ! </item> ! <item><p>A message:</p> ! <ulist> ! <item><p>indicated by a Message Label component whose message label is ! <attval>Challenge</attval> and direction is <attval>out</attval></p></item> ! <item><p>sent to some node N2 (which <emph>may</emph> be the same ! node as N1)</p></item> ! </ulist> ! </item> ! <item><p>An optional message:</p> ! <ulist> ! <item><p>indicated by a Message Label component whose message label is ! <attval>Confirmation</attval> and direction is <attval>in</attval></p></item> ! <item><p>received from node N2</p></item> ! </ulist> ! </item> ! <item><p>An optional message:</p> ! <ulist> ! <item><p>indicated by a Message Label component whose message label is ! <attval>Response</attval> and direction is <attval>out</attval></p></item> ! <item><p>sent to node N2</p></item> ! </ulist> ! </item> ! </olist> ! <p>This pattern uses the rule Message Triggers Fault.</p> ! <p>An operation using this message exchange pattern has a pattern property with ! the value <attval>http://www.example.com/webservices/meps/confirmed-challenge</attval>.</p> ! </div3> ! ! <p>Once the MEP had been defined (and the email binding specification ! appropriately modified to indicate that this was a supported MEP), the ! service was redefined and redeployed. Only the changed operations are shown ! in the excerpt below.</p> ! ! <example id="weather-not-final"> ! <head>Weather Notification Service (Revised)</head> ! <eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?> ! <description xmlns="http://www.w3.org/2005/05/wsdl" ! targetNamespace=http://greath.example.com/@@@@/wsdl/weathSvc.wsdl" ! xmlns:tns=http://greath.example.com/@@@@/wsdl/weathSvc.wsdl" ! xmlns:wsoap="http://www.w3.org/2005/05/wsdl/soap" ! xmlns:email="http://www.example.com/webservices/email" > ! ! . . . ! ! <interface name="weatherInterface"> ! <operation name="opSubscribeWeather" ! pattern="http://www.example.com/webservices/meps/confirmed-challenge"> ! <input messageLabel="Request" element=". . ." /> ! <output messageLabel="Challenge" element=". . ." /> ! <input messageLabel="Confirmation" element=". . ." /> ! <output messageLabel="Response" element=". . ." /> ! </operation> ! <operation name="opUnsubscribeWeather" ! pattern="http://www.example.com/webservices/meps/confirmed-challenge"> ! <output messageLabel="Challenge" element=". . ." /> ! <output messageLabel="Response" element=". . ." /> ! <input messageLabel="Confirmation" element=". . ." /> ! <input messageLabel="Request" element=". . ." /> ! </operation> ! . . . ! </interface> ! ! . . . ! ! </description> ! ]]></eg></example> ! ! <p>Note: in the second example, the input and output examples are not in the ! sequence in which they occur in the pattern; this illustrates that the ! sequence is not significant. Note, however, that for this pattern, the ! messageLabel attribute is required on every input and output element.</p> ! ! </div2><!-- adv-MEP --> ! ! ! ! ! <div2 id="adv-import-and-authoring"> <head>Import mechanism and authoring style</head> Index: wsdl20-primer.html =================================================================== RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.html,v retrieving revision 1.65 retrieving revision 1.66 diff -C2 -d -r1.65 -r1.66 *** wsdl20-primer.html 13 Jun 2005 21:48:10 -0000 1.65 --- wsdl20-primer.html 14 Jun 2005 22:39:19 -0000 1.66 *************** *** 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 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-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-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="#N67836">Operation Message References</a><br> 5.4.2.1 <a href="#N67865">The messageLabel Attribute</a><br> 5.4.2.2 <a href="#N67885">The element Attribute</a><br> 5.4.2.3 <a href="#N67924">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="#N68391">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-import-and-authoring">Import mechanism and authoring style</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="#ad-versioing-migration">Evolving a Service</a><br> 7.5.4 <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 and Endpoint References</a><br> 7.9.1 <a href="#reservationDetails">The Reservation Details Web Service</a><br>   7.9.2 <a href="#reservationList">The Reservation List Web Service</a><br> 7.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="#N69822">Schemas in Imported Documents</a><br> 7.10.2 <a href="#N69961">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="#N70057">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> <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"> [...1036 lines suppressed...] were used simply to illustrate the referencing concepts. However, the use of --- 3164,3168 ---- <code>import</code> mechanism, which is based on XML Schema's term for the similar concept.</p></div><div class="div3"> ! <h4><a name="adv-relative-uris"></a>7.13.2 Relative URIs</h4><p>Throughout this document there are fully qualified URIs used in WSDL 2.0 and XSD examples. In some cases, fully qualified URIs were used simply to illustrate the referencing concepts. However, the use of *************** *** 3000,3004 **** cases. For information on processing relative URIs, see <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC2396</a>.</p></div><div class="div3"> ! <h4><a name="adv-generating-uris"></a>7.12.3 Generating Temporary URIs</h4><p>In general, when a WSDL 2.0 document is published for use by others, it should only contain URIs that are globally unique. This is usually done by allocating them under a domain name that is controlled by the issuer. For example, the W3C allocates namespace URIs under its base domain name, w3.org.</p><p>However, it is sometimes desirable to make up a temporary URI for an entity, for use during development, but not make the URI globally unique for all time and have it "mean" that version of the --- 3170,3174 ---- cases. For information on processing relative URIs, see <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC2396</a>.</p></div><div class="div3"> ! <h4><a name="adv-generating-uris"></a>7.13.3 Generating Temporary URIs</h4><p>In general, when a WSDL 2.0 document is published for use by others, it should only contain URIs that are globally unique. This is usually done by allocating them under a domain name that is controlled by the issuer. For example, the W3C allocates namespace URIs under its base domain name, w3.org.</p><p>However, it is sometimes desirable to make up a temporary URI for an entity, for use during development, but not make the URI globally unique for all time and have it "mean" that version of the
Received on Tuesday, 14 June 2005 22:39:31 UTC