- From: Kevin Liu via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 27 Apr 2005 20:13:21 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20 In directory hutz:/tmp/cvs-serv24269/ws/desc/wsdl20 Modified Files: wsdl20-primer.html wsdl20-primer.xml Log Message: Enhanced example 5.1 to illustrate reusable faults definition via interface inheritance. Removed related ed note Index: wsdl20-primer.xml =================================================================== RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v retrieving revision 1.65 retrieving revision 1.66 diff -C2 -d -r1.65 -r1.66 *** wsdl20-primer.xml 27 Apr 2005 04:17:22 -0000 1.65 --- wsdl20-primer.xml 27 Apr 2005 20:13:19 -0000 1.66 *************** *** 720,734 **** <div2 id="more-interfaces-inheritance"> <head>Interface Inheritance</head> ! <p>The optional <att>extends</att> attribute allows an interface to extend or inherit from one or more other interfaces. In such cases the interface contains the operations of the interfaces it extends, along with any operations it defines directly. Two things about extending interfaces deserve some attention. </p><p>First, an inheritance loop (or infinite recursion) is prohibited: the interfaces that a given interface extends MUST NOT themselves extend that interface either directly or indirectly. </p><p>Second, we must explain what happens when operations from two different interfaces have the same target namespace and operation name. There are two cases: either the component models of the operations are the same, or they are different. If the component models are the same (per the component comparison algorithm defined in WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> "<xspecref href="http://www.w3.org/TR/wsdl20-primer#compequiv">Equivalence of Components</xspecref>") then they are considered to b the same operation, i.e., they are collapsed into a single operation, and the fact that they were included more than once is not considered an error. (For operations, component equivalence basically means that the two operations have the same set of attributes and descendents.) In the second case, if two operations have the same name in the same WSDL target namespace but are not equivalent, then it is an error. For the above reason, it is considered good practic to ensure that all operations within the same target namespace are named uniquely. </p><p>Finally, since faults, features and properties can also be defined as children of the <code>interface</code> element (as descrbed later), the same name-collision rules apply to those constructs.</p> ! ! <ednote> ! <name>KevinL</name> ! <date>20040910</date> ! <edtext> ! Add Example - illustrate use extends attribute ! </edtext> ! </ednote> ! ! <p>Now let's have a look at the element children of <code>interface</code>, beginning with <code>fault</code>.</p> </div2> <div2 id="more-interfaces-faults"> --- 720,726 ---- <div2 id="more-interfaces-inheritance"> <head>Interface Inheritance</head> ! <p>The optional <att>extends</att> attribute allows an interface to extend or inherit from one or more other interfaces. In such cases the interface contains the operations of the interfaces it extends, along with any operations it defines directly. Two things about extending interfaces deserve some attention. </p><p>First, an inheritance loop (or infinite recursion) is prohibited: the interfaces that a given interface extends MUST NOT themselves extend that interface either directly or indirectly. </p><p>Second, we must explain what happens when operations from two different interfaces have the same target namespace and operation name. There are two cases: either the component models of the operations are the same, or they are different. If the component models are the same (per the component comparison algorithm defined in WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> "<xspecref href="http://www.w3.org/TR/wsdl20-primer#compequiv">Equivalence of Components</xspecref>") then they are considered to b the same operation, i.e., they are collapsed into a single operation, and the fact that they were included more than once is not considered an error. (For operations, component equivalence basically means that the two operations have the same set of attributes and descendents.) In the second case, if two operations have the same name in the same WSDL target namespace but are not equivalent, then it is an error. For the above reason, it is considered good practice to ensure that all operations within the same target namespace are named uniquely. </p><p>Finally, since faults, features and properties can also be defined as children of the <code>interface</code> element (as descrbed later), the same name-collision rules apply to those constructs.</p> ! <p>Now let's have a look at the element children of <code>interface</code>, beginning with <code>fault</code>. In the next section, we will provide an example of leveraging interface inheritance for reusing faults and operations across multiple interfaces. </p> ! </div2> <div2 id="more-interfaces-faults"> *************** *** 748,799 **** of SOAP, faults have codes and subcodes in addition to a payload. By defining faults at the interface level, common codes and subcodes can be associated with ! them, thereby ensuring consistency across all operations that use the faults </p><p>The <code>fault</code> element has a required <att>name</att> attribute that must be unique within the WSDL document's target namespace, and permits it to be referenced from operation declarations. The optional <att>element</att> attribute can be used to indicate a schema for the content or payload of the fault message. Its value should be the QName of a global element defined in the <code>types</code> section. Please note when other type systems are used to define the schema for a fault message, additional attributes may need to be defined via WSDL's attribute extension mechanism to allow the schema to be associated with the fault.</p> ! <p>Here is an example of reusing faults.</p> ! <ednote><name>dbooth</name><date>2005-04-14</date><edtext>To do: Update and simplify the fault example below. It should be a slight modification of the initial example, but illustrate: (a) fault reuse; and (b) two alternative faults for an operation.</edtext></ednote><example id="example-faults"> ! <head>Declaring Interface Faults</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"> ! ! <documentation> ! Description: The definition of the reservation Web service of GreatH hotel. ! Author: Joe Somebody ! Date: 05/17/2004 ! </documentation> ! ! <types> ! ! <xs:import namespace="http://greath.example.com/2004/schemas/resSvc" ! schemaLocation= "http://greath.example.com/2004/schemas/resSvc.xsd"/> ! ! </types> ! ! < interface name = "reservation" > ! ! <<b>fault</b> name = "invalidCreditCardFault" ! element = "ghns:invalidCreditCardError"> ! <documentation> ! fault declaration for invalid credit card information. ! </documentation> ! <<b>/fault</b>> ! <<b>fault</b> name = "invalidDataFault" ! element = "ghns:invalidDataError"> ! <documentation> ! falut declaration for invalid data. ! </documentation> ! <<b>/fault</b>> ! </interface> ! </description> ! </eg> </example> --- 740,794 ---- of SOAP, faults have codes and subcodes in addition to a payload. By defining faults at the interface level, common codes and subcodes can be associated with ! them, thereby ensuring consistency across all operations that use the faults </p> ! <p>The <code>fault</code> element has a required <att>name</att> attribute that must be unique within the WSDL document's target namespace, and permits it to be referenced from operation declarations. The optional <att>element</att> attribute can be used to indicate a schema for the content or payload of the fault message. Its value should be the QName of a global element defined in the <code>types</code> section. Please note when other type systems are used to define the schema for a fault message, additional attributes may need to be defined via WSDL's attribute extension mechanism to allow the schema to be associated with the fault.</p> ! <p>The following example shows one way to leverage interface inheritance for reusing faults and operations across multiple interfaces. In most cases, faults are defined under each inidividual interface like in the initial example @@TODO:Add reference to example 2-1@@. But some system may require a set of standard fault messages to be reused across a system. For example, let's say the GreatH hotel wants to maintain a set of standard fault messages and a standard error log operation for credit card and data validation errors that are reusable across the whole reservation system. One way to meet such requirement is to define the standard faults and the log operation in an interface which can be inherited by other interfaces. </p> ! <example id="example-faults"> ! <head>Reusalbe Faults and Interface Inheritance</head> ! <eg xml:space="preserve"> ! ! <description ...> ! ... ! <interface name = "faultManagementInterface" > ! ! <<b>fault</b> name = "invalidCreditCardFault" ! element = "ghns:invalidCreditCardError"> ! <documentation> ! fault declaration for invalid credit card information. ! </documentation> ! <<b>/fault</b>> ! <<b>fault</b> name = "invalidDataFault" ! element = "ghns:invalidDataError"> ! <documentation> ! falut declaration for invalid data. ! </documentation> ! <<b>/fault</b>> ! ! <operation name="opLogError" ! pattern="http://www.w3.org/2004/03/wsdl/in"> ! <input messageLabel="In" ! element="ghns:errorMsg" /> ! </operation> ! </interface> + <interface name="reservationInterface" <b>extends</b>="tns:faultManagementInterface" > + + <operation name="opCheckAvailability" + pattern="http://www.w3.org/2004/03/wsdl/in-out" + style="http://www.w3.org/2004/08/wsdl/style/uri" + safe = "true"> + <input messageLabel="In" + element="ghns:checkAvailability" /> + <output messageLabel="Out" + element="ghns:checkAvailabilityResponse" /> + <outfault ref="tns:invalidDataFault" messageLabel="Out"/> ! </operation> ! </interface> ! ... ! </description></eg> </example> *************** *** 801,805 **** <div2 id="more-interfaces-operations"> <head>Interface Operations</head> ! <p>As shown earlier, the <code>operation</code> element is used to indicate an operation supported by the containing interface. It associate message schemas with a message exchange pattern (MEP), in order abstractly describe a simple interaction with a Web service. </p> --- 796,800 ---- <div2 id="more-interfaces-operations"> <head>Interface Operations</head> ! <p>As shown earlier, the <code>operation</code> element is used to indicate an operation supported by the containing interface. It associates message schemas with a message exchange pattern (MEP), in order abstractly describe a simple interaction with a Web service. </p> Index: wsdl20-primer.html =================================================================== RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.html,v retrieving revision 1.45 retrieving revision 1.46 diff -C2 -d -r1.45 -r1.46 *** wsdl20-primer.html 27 Apr 2005 04:17:22 -0000 1.45 --- wsdl20-primer.html 27 Apr 2005 20:13:18 -0000 1.46 *************** *** 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="#N108AB">Operation Message References</a><br> 5.4.2.1 <a href="#N108C8">The messageLabel Attribute</a><br> 5.4.2.2 <a href="#N108DC">The element Attribute</a><br> 5.4.2.3 <a href="#N10903">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="#N10B3F">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="#N1104E">Schemas in Imported Documents</a><br> 7.10.2 <a href="#N110D9">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="#N11136">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="#N1089C">Operation Message References</a><br> 5.4.2.1 <a href="#N108B9">The messageLabel Attribute</a><br> 5.4.2.2 <a href="#N108CD">The element Attribute</a><br> 5.4.2.3 <a href="#N108F4">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="#N10B30">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="#N1103F">Schemas in Imported Documents</a><br> 7.10.2 <a href="#N110CA">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="#N11127">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"> *************** *** 765,775 **** <h3><a name="more-interfaces-inheritance"></a>5.2 Interface Inheritance</h3> ! <p>The optional <code>extends</code> attribute allows an interface to extend or inherit from one or more other interfaces. In such cases the interface contains the operations of the interfaces it extends, along with any operations it defines directly. Two things about extending interfaces deserve some attention. </p><p>First, an inheritance loop (or infinite recursion) is prohibited: the interfaces that a given interface extends MUST NOT themselves extend that interface either directly or indirectly. </p><p>Second, we must explain what happens when operations from two different interfaces have the same target namespace and operation name. There are two cases: either the component models of the operations are the same, or they are different. If the component models are the same (per the component comparison algorithm defined in 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#compequiv">Equivalence of Components</a>") the they are considered to be the same operation, i.e., they are collapsed into a single operation, and the fact that they were included more than once is not considered an error. (For operations, component equivalence basically means that the two operations have the same set of attributes and descendents.) In the second case, if two operations have the same name in the same WSDL target namespace but are not equivalent, then it is an error. For the above reason, it is considered good practic to ensure that all operations within the same target namespace are named uniquely. </p><p>Finally, since faults, features and properties can also be defined as children of the <code>interface</code> element (as descrbed later), the same name-collision rules apply to those constructs.</p> ! ! <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">20040910</td></tr><tr><td valign="top" align="left" colspan="2"> ! Add Example - illustrate use extends attribute ! </td></tr></table> ! ! <p>Now let's have a look at the element children of <code>interface</code>, beginning with <code>fault</code>.</p> </div> <div class="div2"> --- 765,771 ---- <h3><a name="more-interfaces-inheritance"></a>5.2 Interface Inheritance</h3> ! <p>The optional <code>extends</code> attribute allows an interface to extend or inherit from one or more other interfaces. In such cases the interface contains the operations of the interfaces it extends, along with any operations it defines directly. Two things about extending interfaces deserve some attention. </p><p>First, an inheritance loop (or infinite recursion) is prohibited: the interfaces that a given interface extends MUST NOT themselves extend that interface either directly or indirectly. </p><p>Second, we must explain what happens when operations from two different interfaces have the same target namespace and operation name. There are two cases: either the component models of the operations are the same, or they are different. If the component models are the same (per the component comparison algorithm defined in 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#compequiv">Equivalence of Components</a>") the they are considered to be the same operation, i.e., they are collapsed into a single operation, and the fact that they were included more than once is not considered an error. (For operations, component equivalence basically means that the two operations have the same set of attributes and descendents.) In the second case, if two operations have the same name in the same WSDL target namespace but are not equivalent, then it is an error. For the above reason, it is considered good practice to ensure that all operations within the same target namespace are named uniquely. </p><p>Finally, since faults, features and properties can also be defined as children of the <code>interface</code> element (as descrbed later), the same name-collision rules apply to those constructs.</p> ! <p>Now let's have a look at the element children of <code>interface</code>, beginning with <code>fault</code>. In the next section, we will provide an example of leveraging interface inheritance for reusing faults and operations across multiple interfaces. </p> ! </div> <div class="div2"> *************** *** 790,841 **** of SOAP, faults have codes and subcodes in addition to a payload. By defining faults at the interface level, common codes and subcodes can be associated with ! them, thereby ensuring consistency across all operations that use the faults </p><p>The <code>fault</code> element has a required <code>name</code> attribute that must be unique within the WSDL document's target namespace, and permits it to be referenced from operation declarations. The optional <code>element</code> attribute can be used to indicate a schema for the content or payload of the fault message. Its value should be the QName of a global element defined in the <code>types</code> section. Please note when other type systems are used to define the schema for a fault message, additional attributes may need to be defined via WSDL's attribute extension mechanism to allow the schema to be associated with the fault.</p> ! <p>Here is an example of reusing faults.</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-14</td></tr><tr><td valign="top" align="left" colspan="2">To do: Update and simplify the fault example below. It should be a slight modification of the initial example, but illustrate: (a) fault reuse; and (b) two alternative faults for an operation.</td></tr></table><div class="exampleOuter"> ! <p class="exampleHead" style="text-align: left"><a name="example-faults"></a><i><span>Example 5-1. </span>Declaring Interface Faults</i></p> ! <div class="exampleInner"><pre> ! ! <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"> ! ! <documentation> ! Description: The definition of the reservation Web service of GreatH hotel. ! Author: Joe Somebody ! Date: 05/17/2004 ! </documentation> ! ! <types> ! ! <xs:import namespace="http://greath.example.com/2004/schemas/resSvc" ! schemaLocation= "http://greath.example.com/2004/schemas/resSvc.xsd"/> ! ! </types> ! ! < interface name = "reservation" > ! ! <<b>fault</b> name = "invalidCreditCardFault" ! element = "ghns:invalidCreditCardError"> ! <documentation> ! fault declaration for invalid credit card information. ! </documentation> ! <<b>/fault</b>> ! <<b>fault</b> name = "invalidDataFault" ! element = "ghns:invalidDataError"> ! <documentation> ! falut declaration for invalid data. ! </documentation> ! <<b>/fault</b>> ! </interface> ! </description> ! </pre></div> </div> --- 786,840 ---- of SOAP, faults have codes and subcodes in addition to a payload. By defining faults at the interface level, common codes and subcodes can be associated with ! them, thereby ensuring consistency across all operations that use the faults </p> ! <p>The <code>fault</code> element has a required <code>name</code> attribute that must be unique within the WSDL document's target namespace, and permits it to be referenced from operation declarations. The optional <code>element</code> attribute can be used to indicate a schema for the content or payload of the fault message. Its value should be the QName of a global element defined in the <code>types</code> section. Please note when other type systems are used to define the schema for a fault message, additional attributes may need to be defined via WSDL's attribute extension mechanism to allow the schema to be associated with the fault.</p> ! <p>The following example shows one way to leverage interface inheritance for reusing faults and operations across multiple interfaces. In most cases, faults are defined under each inidividual interface like in the initial example @@TODO:Add reference to example 2-1@@. But some system may require a set of standard fault messages to be reused across a system. For example, let's say the GreatH hotel wants to maintain a set of standard fault messages and a standard error log operation for credit card and data validation errors that are reusable across the whole reservation system. One way to meet such requirement is to define the standard faults and the log operation in an interface which can be inherited by other interfaces. </p> ! <div class="exampleOuter"> ! <p class="exampleHead" style="text-align: left"><a name="example-faults"></a><i><span>Example 5-1. </span>Reusalbe Faults and Interface Inheritance</i></p> ! <div class="exampleInner"><pre> ! ! <description ...> ! ... ! <interface name = "faultManagementInterface" > ! ! <<b>fault</b> name = "invalidCreditCardFault" ! element = "ghns:invalidCreditCardError"> ! <documentation> ! fault declaration for invalid credit card information. ! </documentation> ! <<b>/fault</b>> ! <<b>fault</b> name = "invalidDataFault" ! element = "ghns:invalidDataError"> ! <documentation> ! falut declaration for invalid data. ! </documentation> ! <<b>/fault</b>> ! ! <operation name="opLogError" ! pattern="http://www.w3.org/2004/03/wsdl/in"> ! <input messageLabel="In" ! element="ghns:errorMsg" /> ! </operation> ! </interface> + <interface name="reservationInterface" <b>extends</b>="tns:faultManagementInterface" > + + <operation name="opCheckAvailability" + pattern="http://www.w3.org/2004/03/wsdl/in-out" + style="http://www.w3.org/2004/08/wsdl/style/uri" + safe = "true"> + <input messageLabel="In" + element="ghns:checkAvailability" /> + <output messageLabel="Out" + element="ghns:checkAvailabilityResponse" /> + <outfault ref="tns:invalidDataFault" messageLabel="Out"/> ! </operation> ! </interface> ! ... ! </description></pre></div> </div> *************** *** 844,848 **** <h3><a name="more-interfaces-operations"></a>5.4 Interface Operations</h3> ! <p>As shown earlier, the <code>operation</code> element is used to indicate an operation supported by the containing interface. It associate message schemas with a message exchange pattern (MEP), in order abstractly describe a simple interaction with a Web service. </p> --- 843,847 ---- <h3><a name="more-interfaces-operations"></a>5.4 Interface Operations</h3> ! <p>As shown earlier, the <code>operation</code> element is used to indicate an operation supported by the containing interface. It associates message schemas with a message exchange pattern (MEP), in order abstractly describe a simple interaction with a Web service. </p> *************** *** 869,877 **** </li> </ul></div><div class="div3"> ! <h4><a name="N108AB"></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="N108C8"></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="N108DC"></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="N10903"></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> --- 868,876 ---- </li> </ul></div><div class="div3"> ! <h4><a name="N1089C"></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="N108B9"></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="N108CD"></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="N108F4"></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> *************** *** 1148,1152 **** </div> <div class="div3"> ! <h4><a name="N10B3F"></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> --- 1147,1151 ---- </div> <div class="div3"> ! <h4><a name="N10B30"></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> *************** *** 2376,2380 **** <div class="div3"> ! <h4><a name="N1104E"></a>7.10.1 Schemas in Imported Documents</h4> <p> In this example, we consider some GreatH Hotel --- 2375,2379 ---- <div class="div3"> ! <h4><a name="N1103F"></a>7.10.1 Schemas in Imported Documents</h4> <p> In this example, we consider some GreatH Hotel *************** *** 2583,2587 **** <div class="div3"> ! <h4><a name="N110D9"></a>7.10.2 Multiple Inline Schemas in One Document</h4> <p> A WSDL 2.0 document may define multiple inline --- 2582,2586 ---- <div class="div3"> ! <h4><a name="N110CA"></a>7.10.2 Multiple Inline Schemas in One Document</h4> <p> A WSDL 2.0 document may define multiple inline *************** *** 2717,2721 **** 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="N11136"></a>7.10.3.1 Using the id Attribute to Identify Inline Schemas</h5><p> <a href="#schemaIds.wsdl">Example 7-26</a> --- 2716,2720 ---- 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="N11127"></a>7.10.3.1 Using the id Attribute to Identify Inline Schemas</h5><p> <a href="#schemaIds.wsdl">Example 7-26</a>
Received on Wednesday, 27 April 2005 20:13:35 UTC