- From: David Booth via cvs-syncmail <cvsmail@w3.org>
- Date: Thu, 14 Apr 2005 21:40:47 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20
In directory hutz:/tmp/cvs-serv30532
Modified Files:
wsdl20-primer.xml wsdl20-primer.html
Log Message:
Set the safe="true" on opCheckAvailability. Still need to make it use
GET instead of POST.
Simplified the Interface syntax summary.
Deleted the example of defining an operation in section 5, since
the first example already demonstrates how to define an operation.
Restructured section 5.
Finished updating/editing section 5.
Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.47
retrieving revision 1.48
diff -C2 -d -r1.47 -r1.48
*** wsdl20-primer.xml 13 Apr 2005 22:27:19 -0000 1.47
--- wsdl20-primer.xml 14 Apr 2005 21:40:45 -0000 1.48
***************
*** 169,173 ****
<operation name="opCheckAvailability"
! pattern="http://www.w3.org/2004/03/wsdl/in-out" >
<input messageLabel="In"
element="ghns:checkAvailability" />
--- 169,174 ----
<operation name="opCheckAvailability"
! pattern="http://www.w3.org/2004/03/wsdl/in-out"
! safe = "true">
<input messageLabel="In"
element="ghns:checkAvailability" />
***************
*** 284,288 ****
<operation name="opCheckAvailability"
! pattern="http://www.w3.org/2004/03/wsdl/in-out" >
<input messageLabel="In"
element="ghns:checkAvailability" />
--- 285,290 ----
<operation name="opCheckAvailability"
! pattern="http://www.w3.org/2004/03/wsdl/in-out"
! save = "true">
<input messageLabel="In"
element="ghns:checkAvailability" />
***************
*** 296,300 ****
. . .
</description>]]></eg></example><div3 id="example-initial-interface-explanation"><head>Explanation of Example</head><glist><gitem><label><code><interface name = "reservationInterface" ></code></label><def><p>Interfaces are declared directly inside the <code>description</code> element. In this example, we are declaring only one interface, but in general a WSDL document may declare more than one interface. Thus, each interface must be given a name that is unique within the set of interfaces defined in this WSDL target namespace. Interface names are tokens that must not contain a space or colon (":").</p></def></gitem><gitem><label><code><fault name = "invalidDataFault"
! </code></label><def><p>The <code>name</code> attribute defines a name for this fault. The name is required so that when an operation is defined, it can reference the desired fault by name. Fault names must be unique within an interface.</p></def></gitem><gitem><label><code>element = "ghns:invalidDataError"/></code></label><def><p>The <code>element</code> attribute specifies the schema type of the fault message, as previously defined in the <code>types</code> section. </p></def></gitem><gitem><label><code><operation name="opCheckAvailability"</code></label><def><p>The <code>name</code> attribute defines a name for this operation, so that it can be referenced later when bindings are defined. Operation names must also be unique within an interface. (WSDL 2.0 uses separate symbol spaces for operation and fault names, so operation name "foo" is distinct from fault name "foo".)</p></def></gitem><gitem><label><code>pattern="http://www.w3.org/2004/03/wsdl/in-out" ></code></label><def><pThis line specifies that this operation will use the <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref> pattern as described above. WSDL 2.0 uses URIs to identify message exchange patterns in order to ensure that the identifiers are globally unambiguous, while also permitting future new patterns to be defined by anyone. (However, just because someone defines a new pattern and creates a URI to identify it, that does <emph>not</emph> mean that other WSDL processors will automatically recognize or understand that pattern. As with any other extension, it can be used among processors that <i>do</i> recognize and understand it.)</p></def></gitem><gitem><label><code><input messageLabel="In"</code></label><def><p>The <code>input</code> element specifies an input message. Even though we have already specified which message exchange pattern the operation will use, a message exchange pattern represents a template for a message sequence, and in theory could consis of multiple input and/or output messages. Thus we must also indicate which potential input message in the pattern this particular input message represents. This is the purpose of the <code>messageLabel</code> attribute. Since the <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref> pattern that we've chosen to use only has one input message, it is trivial in this case: we simply fill in the message label "In" that was defined in <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSDL-PART2"/> section 2.2.3 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">In-Out</xspecref> for the <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref> pattern. However, if a new pattern is defined that involve multiple input messages, then the different input messages in the pattern could then be distinguished by having different labels.</p></def></gitem><gitem><label><code>element="ghns:checkvailability" /></code></label><def><p>This specifies the message type for this input message, as defined previously in the <code>types</code> section.</p></def></gitem><gitem><label><code><output messageLabel="Out" . . .</code></label><def><p>This is similar to defining an input message.</p></def></gitem><gitem><label><code><outfault ref="tns:invalidDataFault" messageLabel="Out"/></code></label><def><p>This associates an output fault with this operation. Faults are declared a little differently than normal messages. The <code>ref</code> attribute refers to the name of a previously defined fault in this interface -- not a message schema type directly. Since message exchange patterns could in general involve a sequence of several messages, a fault could potentially occur at various points within the message sequence. Because one may wish to associate a different fault with each permitted point in the sequence, the messageLabel is used to indicate the desired point for this particular fault. Itdoes so indirectly by specifying the message that will either trigger this fault or that this fault will replace, depending on the pattern. (Some patterns use a <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-trigger">message-triggers-fault rule</xspecref>; others use a <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-replacement">fault-replaces-message</xspecref> rule. See <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSDL-PART2"/> section 2.1.2 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-trigger">Message Triggers Fault</xspecref> and section 2.1.1 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-replacement">Fault Replaces Message</xspecref>.) </p></def></gitem></glist><p>Now that we've defined the abstract interface for the GreatH service, we're ready to define a binding for it.</p></div3></div2>
--- 298,302 ----
. . .
</description>]]></eg></example><div3 id="example-initial-interface-explanation"><head>Explanation of Example</head><glist><gitem><label><code><interface name = "reservationInterface" ></code></label><def><p>Interfaces are declared directly inside the <code>description</code> element. In this example, we are declaring only one interface, but in general a WSDL document may declare more than one interface. Thus, each interface must be given a name that is unique within the set of interfaces defined in this WSDL target namespace. Interface names are tokens that must not contain a space or colon (":").</p></def></gitem><gitem><label><code><fault name = "invalidDataFault"
! </code></label><def><p>The <code>name</code> attribute defines a name for this fault. The name is required so that when an operation is defined, it can reference the desired fault by name. Fault names must be unique within an interface.</p></def></gitem><gitem><label><code>element = "ghns:invalidDataError"/></code></label><def><p>The <code>element</code> attribute specifies the schema type of the fault message, as previously defined in the <code>types</code> section. </p></def></gitem><gitem><label><code><operation name="opCheckAvailability"</code></label><def><p>The <code>name</code> attribute defines a name for this operation, so that it can be referenced later when bindings are defined. Operation names must also be unique within an interface. (WSDL 2.0 uses separate symbol spaces for operation and fault names, so operation name "foo" is distinct from fault name "foo".)</p></def></gitem><gitem><label><code>pattern="http://www.w3.org/2004/03/wsdl/in-out" </code></label><def><p>Thi line specifies that this operation will use the <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref> pattern as described above. WSDL 2.0 uses URIs to identify message exchange patterns in order to ensure that the identifiers are globally unambiguous, while also permitting future new patterns to be defined by anyone. (However, just because someone defines a new pattern and creates a URI to identify it, that does <emph>not</emph> mean that other WSDL processors will automatically recognize or understand that pattern. As with any other extension, it can be used among processors that <i>do</i> recognize and understand it.)</p></def></gitem><gitem><label><code>safe="true" ></code></label><def><p>This line indicates that this operation will not obligate the client in any way, i.e., the client can safely invoke this operation without fear that it may be incurring an obligation (such as agreeing to buy something). This is further explained in <specref ref="mor-interfaces-operations"/>. </p></def></gitem><gitem><label><code><input messageLabel="In"</code></label><def><p>The <code>input</code> element specifies an input message. Even though we have already specified which message exchange pattern the operation will use, a message exchange pattern represents a template for a message sequence, and in theory could consist of multiple input and/or output messages. Thus we must also indicate which potential input message in the pattern this particular input message represents. This is the purpose of the <code>messageLabel</code> attribute. Since the <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref> pattern that we've chosen to use only has one input message, it is trivial in this case: we simply fill in the message label "In" that was defined in <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSDL-PART2"/> section 2.2.3 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">InOut</xspecref> for the <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref> pattern. However, if a new pattern is defined that involve multiple input messages, then the different input messages in the pattern could then be distinguished by having different labels.</p></def></gitem><gitem><label><code>element="ghns:checkAvailability" /></code></label><def><p>This specifies the message type for this input message, as defined previously in the <code>types</code> section.</p></def></gitem><gitem><label><code><output messageLabel="Out" . . .</code></label><def><p>This is similar to defining an input message.</p></def></gitem><gitem><label><code><outfault ref="tns:invalidDataFault" messageLabel="Out"/></code></label><def><p>This associates an output fault with this operation. Faults are declared a little differently than normal messages. The <code>ref</code> attribute refers to the name of a previously defined fault in this interface -- not a message shema type directly. Since message exchange patterns could in general involve a sequence of several messages, a fault could potentially occur at various points within the message sequence. Because one may wish to associate a different fault with each permitted point in the sequence, the messageLabel is used to indicate the desired point for this particular fault. It does so indirectly by specifying the message that will either trigger this fault or that this fault will replace, depending on the pattern. (Some patterns use a <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-trigger">message-triggers-fault rule</xspecref>; others use a <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-replacement">fault-replaces-message</xspecref> rule. See <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSDL-PART2"/> section 2.1.2 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-trigger">Message Triggers Fault</xspecref> and ection 2.1.1 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-replacement">Fault Replaces Message</xspecref>.) </p></def></gitem></glist><p>Now that we've defined the abstract interface for the GreatH service, we're ready to define a binding for it.</p></div3></div2>
***************
*** 573,577 ****
</div2>
! <div2 id="component-model"><head>WSDL 2.0 Component Model</head><p>The WSDL 2.0 Infoset model above illustrates the required structure of a WSDL 2.0 document, using the XML Infoset. However, the WSDL 2.0 language also stipulates semantic constraints over and above conformance to this XML Infoset structure. In order to precisely describe these constraints, and as an aid in precisely defining the meaning of each WSDL 2.0 document, the WSDL 2.0 specification defines a <emph>component model</emph> as an additional layer of abstraction above the XML Infoset. Constraints and meaning are defined in terms of this component model, and the definition of each component includes a mapping that specifies how values in the component model are derived from corresponding items in the XML Infoset. </p><p>In general, the WSDL 2.0 component model parallels the structure of the required XML Infoset illustrated above. For example, the <emph>Description</emph>, <emph>Interface</emph>, <emph>Binding</emph>, <emph>Service/emph> and <emph>Endpoint</emph> <emph>components</emph> correspond to the <code>description</code>, <code>interface</code>, <code>binding</code>, <code>service</code>, and <code>endpoint</code> element information items, respectively. The Description component represents the meaning of the <code>description</code> element information item, and hence, it represents the meaning of the WSDL 2.0 document as a whole. </p><p>Furthermore, each of these components has <emph>properties</emph> whose values are (usually) derived from the element and attribute information item children of those element information items. For example, the Service component corresponds to the <code>service</code> element information item, so the Service component has an {endpoints} property whose value is a set of Endpoint components corresponding to the <code>endpoint</code> element information item children of that <code>service</code> element information item. (Whew!)<ednote><name>dbooth</name><date>2005-04-12</date><edtext>TDo: Should we add a graphic illustrating the parallel structure of the component model and the XML Infoset? I think it would be helpful.</edtext></ednote></p><p>The WSDL 2.0 component model is particularly helpful in defining the meaning of <code>import</code> and <code>include</code>. WSDL 2.0 <code>include</code> allows components from another WSDL 2.0 document having the same targetNamespace to be merged in with the components of the current WSDL 2.0 document, and is transitive (i.e., if the included document also includes a WSDL 2.0 document, then those components will also be merged, and so on). WSDL 2.0 <code>import</code> allows components from another WSDL 2.0 document having a different targetNamespace to be merged in with comonents of the current WSDL 2.0 document, and is not transitive.</p></div2></div1>
--- 575,579 ----
</div2>
! <div2 id="component-model"><head>WSDL 2.0 Component Model</head><p>The WSDL 2.0 Infoset model above illustrates the required structure of a WSDL 2.0 document, using the XML Infoset. However, the WSDL 2.0 language also imposes many semantic constraints over and above structural conformance to this XML Infoset. In order to precisely describe these constraints, and as an aid in precisely defining the meaning of each WSDL 2.0 document, the WSDL 2.0 specification defines a <emph>component model</emph> as an additional layer of abstraction above the XML Infoset. Constraints and meaning are defined in terms of this component model, and the definition of each component includes a mapping that specifies how values in the component model are derived from corresponding items in the XML Infoset. </p><p>In general, the WSDL 2.0 component model parallels the structure of the required XML Infoset illustrated above. For example, the <emph>Description</emph>, <emph>Interface</emph>, <emph>Binding</emph>, <emph>Servce</emph> and <emph>Endpoint</emph> <emph>components</emph> correspond to the <code>description</code>, <code>interface</code>, <code>binding</code>, <code>service</code>, and <code>endpoint</code> element information items, respectively. The Description component represents the meaning of the <code>description</code> element information item, and hence, it represents the meaning of the WSDL 2.0 document as a whole. </p><p>Furthermore, each of these components has <emph>properties</emph> whose values are (usually) derived from the element and attribute information item children of those element information items. For example, the Service component corresponds to the <code>service</code> element information item, so the Service component has an {endpoints} property whose value is a set of Endpoint components corresponding to the <code>endpoint</code> element information item children of that <code>service</code> element information item. (Whew!)<ednote><name>dbooth</name><date>2005-04-12</date><edtex>ToDo: Should we add a graphic illustrating the parallel structure of the component model and the XML Infoset? I think it would be helpful.</edtext></ednote></p><p>The WSDL 2.0 component model is particularly helpful in defining the meaning of <code>import</code> and <code>include</code>. WSDL 2.0 <code>include</code> allows components from another WSDL 2.0 document having the same targetNamespace to be merged in with the components of the current WSDL 2.0 document, and is transitive (i.e., if the included document also includes a WSDL 2.0 document, then those components will also be merged, and so on). WSDL 2.0 <code>import</code> allows components from another WSDL 2.0 document having a different targetNamespace to be merged in with comonents of the current WSDL 2.0 document, and is not transitive.</p></div2></div1>
***************
*** 579,666 ****
<!-- ******************MessageTypes********************************** -->
<!-- ******************MessageTypes********************************** -->
! <p>The WSDL 2.0 <code>types</code> element provides a mechanism for enclosing message schemas in a WSDL document. WSDL 2.0 directly supports schemas written in XML Schema
! <bibref ref="XMLSchemaP1"/>. Schemas written in other type definition languages must be defined using a WSDL 2.0 language extension (see WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> Appendix E "<xspecref href="http://www.w3.org/TR/wsdl20-primer#other-schemalang">Examples of Specifications of Extension Elements for Alternative Schema Language Support. (Non-Normative)</xspecref>".
<ednote><name>dbooth</name><date>2005-04-13</date><edtext>ToDo: Update the above reference to appendix E, as the WG decided to move it to a separate document.</edtext></ednote></p>
! <div2 id="more-types-schema">
! <head>Defining Messages Using XML Schema</head>
!
! <ednote><name>dbooth</name><date>2005-04-13</date><edtext>ToDo: Check the sections below on import and include mechanisms for correctness. (Be sure to check the table also.) I'm not sure I got them all right.</edtext></ednote><p>There are two ways to enclose XML Schema messages definitions within the <code>types</code> element. One way is to embed schema definitions within <code>xs:schema</code> elements that are children of <code>types</code>, as we have already seen. The other way is to use <code>xs:import</code> directly under <code>types</code>. It is perfectly reasonable to use both ways in one WSDL document.</p>
!
! <p>A WSDL <code>description</code> MUST NOT refer to XML Schema components that are neither imported nor embedded into that WSDL <code>description</code>. In other words, the use of <code>xs:import</code> and/or <code>xs:schema</code> is a necessary condition for making XML Schema components available to a WSDL Description component. </p>
! <p>The following XML syntax for the <code>types</code> element illustrates the use of <code>xs:import</code> and <code>xs:schema</code>:</p>
! <eg xml:space="preserve"><description>
! <<b>types</b>>
! <documentation />?
! <xs:import namespace="<emph>xs:anyURI</emph>" schemaLocation= "<emph>xs:anyURI</emph>"?/>*
! <xs:schema targetNamespace="<emph>xs:anyURI</emph>" />*
!
! [<emph>extension elements</emph>]*
! </<b>types</b>>
</description>
</eg>
! <div3 id="more-types-schema-embed">
! <head>Embedding XML Schema</head>
! <p>We have already seen an example of using embedded schema definitions in section <specref ref="basics-types"/>, so we will merely add a few additional points here. </p><p>When XML Schema is embedded directly in a WSDL document, it uses the existing top-level <code>xs:schema</code> element defined by XML Schema <bibref ref="XMLSchemaP1"/> to do so, as though the schema had been copied and pasted into the <code>types</code> element. The schema components defined in the embedded schema are then available to
WSDL for reference by QName (see WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> "<xspecref href="http://www.w3.org/TR/wsdl20-primer#qnameres">QName Resolution</xspecref>"). </p>
! <p>Although WSDL 2.0 provides a <code>wsdl:import</code> mechanism (described in the next section), an embedded XML schema may also use XML Schema's native <code>xs:import</code> and <code>xs:include</code>
elements to refer to schemas either in separate files or embedded in the same
WSDL 2.0 document. However, components embedded using <code>xs:import</code> have different visibility from those embedded using <code>xs:include</code>: <code>xs:include</code>d components are available to WSDL for reference by QName, but <code>xs:import</code>ed components are not.</p>
-
-
- </div3>
! <div3 id="more-types-schema-import">
! <head>Importing XML Schema</head>
! <p> There are many cases where one would prefer importing schema definitions from separate schema files instead of embedding them directly under the <code>types</code> element. One reason is reusability of the schemas. Although WSDL 2.0 provides a <code>wsdl:import</code> mechanism, type and element declarations embedded in a WSDL 2.0 document are NOT automatically made available to the importing document, even though other WSDL 2.0 components (such as Interfaces, Bindings, etc.) do become available. Therefore, if you wish to share schema documents across several WSDL 2.0 documents, they should instead be placed in separate XML Schema documents and imported into each WSDL 2.0 document using <code>xs:import</code> directly under <code>types</code>. </p>
!
! <p>The <code>xs:import</code> mechanism is not transitive. Only components defined in the imported schema itself and components the schema includes via <code>xs:include</code> are available to the containing WSDL document. Specifically, components that the schema imports via <code>xs:import</code> are NOT available to WSDL. </p>
!
! <ednote><name>dbooth</name><date>2005-04-13</date><edtext>Check this. An issue was recently raised about import not being transitive.</edtext></ednote>
!
!
! <p>Here is an example of importing a schema. Assuming the message types in <specref ref="example-initial-types"/> are defined in a separate schema file named "http://greath.example.com/2004/schemas/resSvc.xsd" with a target namespace "http://greath.example.com/2004/schemas/resSvc", the schema definition can then be imported into the WSDL as follows: </p>
! <example id="example-schema-import">
! <head>Example of Importing Message Definitions</head>
! <eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
<description
! xmlns="http://www.w3.org/2004/08/wsdl"
! targetNamespace= "http://greath.example.com/2004/wsdl/resSvc"
! xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc"
! xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc"
! . . . >
! . . .
!
! <types>
! <xs:import namespace="http://greath.example.com/2004/schemas/resSvc"
! schemaLocation= "http://greath.example.com/2004/schemas/resSvc.xsd"/>
! </types>
!
! . . .
! </description>]]></eg>
! </example>
! </div3>
! <div3 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 <code>wsdl:</code> and <code>xs:</code> <code>include</code> and <code>import</code> mechanisms.<table border="1"><caption>Summary of Import and Include Mechanisms</caption><thead><tr><th>Mechanism</th><th>Imported/Included Document Type</th><th>Transitive?</th></tr></thead><tbody><tr><td>wsdl:import</td><td>WSDL 2.0 document</td><td>Merge Interface, Binding and Service components from another WSDL 2.0 document that has a DIFFERENT targetNamespace. (Schema type and element declarations are NOT merged.)</td><td>No</td></tr><tr><td>wsdl:include</td><td>WSDL 2.0 document</td><td>Merge Interface, Binding and Service components from another WSDL 2.0 document that has the SAME targetNamespace. (Schema type and element declarations are NOT merged.)</td><td>Yes</td></tr><tr><td>xs::import</td><td>XML Schema document</td><td>Merge typeand element declarations from another XML Schema document that has a DIFFERENT targetNamespace.</td><td>No</td></tr><tr><td>xs:import</td><td>XML Schema document</td><td>Merge type and element declarations from another XML Schema document that has the SAME targetNamespace.</td><td>Yes</td></tr></tbody></table></p></div3></div2>
!
! <div2 id="more-types-other-schema">
! <head>Defining Messages Using other type languages</head>
! <p>The use of type systems other than XML Schema is permitted by using extensions within <code>types</code>.
! <emph>WSDL 2.0 Core Language</emph> <bibref ref="WSDL-PART1"/> appendix E <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-20040803/#other-schemalang"> provides a set of examples of using DTD and RELAX NG as alternative schema Languages</xspecref>.
! </p>
! <ednote>
! <name>KevinL</name>
! <date>20050308</date>
! <edtext>
! The WSD WG has decided to move Appendix E to a seperate notes. Reference here needs update when the new Notes is published.
! </edtext>
! </ednote>
! </div2>
</div1>
--- 581,651 ----
<!-- ******************MessageTypes********************************** -->
<!-- ******************MessageTypes********************************** -->
! <p>The WSDL 2.0 <code>types</code> element provides a mechanism for enclosing message schemas in a WSDL document. Because WSDL 2.0 directly supports schemas written in XML Schema
! <bibref ref="XMLSchemaP1"/>, we will focus here on the use of XML Schema to define message types. Schemas written in other type definition languages must be defined using a WSDL 2.0 language extension. For examples of other schema languages, see WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> Appendix E "<xspecref href="http://www.w3.org/TR/wsdl20-primer#other-schemalang">Examples of Specifications of Extension Elements for Alternative Schema Language Support. (Non-Normative)</xspecref>".
<ednote><name>dbooth</name><date>2005-04-13</date><edtext>ToDo: Update the above reference to appendix E, as the WG decided to move it to a separate document.</edtext></ednote></p>
!
! <ednote><name>dbooth</name><date>2005-04-13</date><edtext>ToDo: Check the sections below on import and include mechanisms for correctness. (Be sure to check the table also.) I'm not sure I got them all right.</edtext></ednote><p>There are two ways to indicate XML Schema message definitions using the <code>types</code> element. One way is to embed schema definitions within <code>xs:schema</code> elements that are children of <code>types</code>, as we have already seen. The other way is to use <code>xs:import</code> directly under <code>types</code>. It is perfectly reasonable to use both ways in one WSDL document.</p>
!
! <p>A WSDL <code>description</code> MUST NOT refer to XML Schema components that are neither imported nor embedded into that WSDL <code>description</code>. In other words, the use of <code>xs:import</code> and/or <code>xs:schema</code> is a necessary condition for making XML Schema components available to a WSDL Description component. </p>
! <p>The following XML syntax for the <code>types</code> element illustrates the use of <code>xs:import</code> and <code>xs:schema</code>:</p>
! <eg xml:space="preserve"><description>
! <<b>types</b>>
! <documentation />?
! <xs:import namespace="<emph>xs:anyURI</emph>" schemaLocation= "<emph>xs:anyURI</emph>"?/>*
! <xs:schema targetNamespace="<emph>xs:anyURI</emph>" />*
!
! [<emph>extension elements</emph>]*
! </<b>types</b>>
</description>
</eg>
! <div2 id="more-types-schema-embed">
! <head>Embedding XML Schema</head>
! <p>We have already seen an example of using embedded schema definitions in section <specref ref="basics-types"/>, so we will merely add a few additional points here. </p><p>When XML Schema is embedded directly in a WSDL document, it uses the existing top-level <code>xs:schema</code> element defined by XML Schema <bibref ref="XMLSchemaP1"/> to do so, as though the schema had been copied and pasted into the <code>types</code> element. The schema components defined in the embedded schema are then available to
WSDL for reference by QName (see WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> "<xspecref href="http://www.w3.org/TR/wsdl20-primer#qnameres">QName Resolution</xspecref>"). </p>
! <p>Although WSDL 2.0 provides a <code>wsdl:import</code> mechanism (described in the next section), an embedded XML schema may also use XML Schema's native <code>xs:import</code> and <code>xs:include</code>
elements to refer to schemas either in separate files or embedded in the same
WSDL 2.0 document. However, components embedded using <code>xs:import</code> have different visibility from those embedded using <code>xs:include</code>: <code>xs:include</code>d components are available to WSDL for reference by QName, but <code>xs:import</code>ed components are not.</p>
!
! </div2>
!
! <div2 id="more-types-schema-import">
! <head>Importing XML Schema</head>
! <p> There are many cases where one would prefer importing schema definitions from separate schema files instead of embedding them directly under the <code>types</code> element. One reason is reusability of the schemas. Although WSDL 2.0 provides a <code>wsdl:import</code> mechanism, type and element declarations embedded in a WSDL 2.0 document are NOT automatically made available to the importing document, even though other WSDL 2.0 components (such as Interfaces, Bindings, etc.) do become available. Therefore, if you wish to share schema documents across several WSDL 2.0 documents, they should instead be placed in separate XML Schema documents and imported into each WSDL 2.0 document using <code>xs:import</code> directly under <code>types</code>. </p>
!
! <p>The <code>xs:import</code> mechanism is not transitive. Only components defined in the imported schema itself and components the schema includes via <code>xs:include</code> are available to the containing WSDL document. Specifically, components that the schema imports via <code>xs:import</code> are NOT available to WSDL. </p>
!
! <ednote><name>dbooth</name><date>2005-04-13</date><edtext>Check this. An issue was recently raised about import not being transitive.</edtext></ednote>
!
!
! <p>Here is an example of importing a schema. Assuming the message types in <specref ref="example-initial-types"/> are defined in a separate schema file named "http://greath.example.com/2004/schemas/resSvc.xsd" with a target namespace "http://greath.example.com/2004/schemas/resSvc", the schema definition can then be imported into the WSDL as follows: </p>
! <example id="example-schema-import">
! <head>Example of Importing Message Definitions</head>
! <eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
<description
! xmlns="http://www.w3.org/2004/08/wsdl"
! targetNamespace= "http://greath.example.com/2004/wsdl/resSvc"
! xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc"
! xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc"
! . . . >
! . . .
! <types>
! <xs:import namespace="http://greath.example.com/2004/schemas/resSvc"
! schemaLocation= "http://greath.example.com/2004/schemas/resSvc.xsd"/>
! </types>
! . . .
! </description>]]></eg>
! </example>
! </div2>
! <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 <code>wsdl:</code> and <code>xs:</code> <code>include</code> and <code>import</code> mechanisms.<table border="1"><caption>Summary of Import and Include Mechanisms</caption><thead><tr><th>Mechanism</th><th>Imported/Included Document Type</th><th>Meaning</th><th>Transitive?</th></tr></thead><tbody><tr><td>wsdl:import</td><td>WSDL 2.0 document</td><td>Merge Interface, Binding and Service components from another WSDL 2.0 document that has a DIFFERENT targetNamespace. (Schema type and element declarations are NOT merged.)</td><td>No</td></tr><tr><td>wsdl:include</td><td>WSDL 2.0 document</td><td>Merge Interface, Binding and Service components from another WSDL 2.0 document that has the SAME targetNamespace. (Schema type and element declarations are NOT merged.)</td><td>Yes</td></tr><tr><td>xs::import</td><td>XML Schema document</td<td>Merge type and element declarations from another XML Schema document that has a DIFFERENT targetNamespace.</td><td>No</td></tr><tr><td>xs:import</td><td>XML Schema document</td><td>Merge type and element declarations from another XML Schema document that has the SAME targetNamespace.</td><td>Yes</td></tr></tbody></table></p></div2>
!
</div1>
***************
*** 671,921 ****
<!-- ************************interface*************************** -->
! <p>We previously mentioned that a WSDL 2.0 interface is basically a set of operations. However, there are some additional capabilities that we have not yet covered. First, let's review the complete syntax for the <code>interface</code> element. </p>
<div2 id="more-interfaces-interfaces">
<head>Interface Syntax </head>
- <ednote><name>dbooth</name><edtext>To do: Simplify this syntax summary.</edtext></ednote>
! <p>Below is the XML syntax summary of the <code>interface</code> element:</p>
<eg xml:space="preserve">
<description targetNamespace="<emph>xs:anyURI</emph>" >
! <interface name="<emph>xs:NCName</emph>" extends="<emph>list of xs:QName</emph>"? styleDefault="<emph>list of xs:anyURI</emph>"? >
! <documentation />?
!
! <fault name="<emph>xs:NCName</emph>" element="<emph>xs:QName</emph>"? >
! <documentation />?
!
! <feature ... />*
! <property ... />*
</fault>*
! <operation name="<emph>xs:NCName</emph>" pattern="<emph>xs:anyURI</emph>" style="<emph>list of xs:anyURI</emph>"? safe="<emph>xs:boolean</emph>"? >
! <documentation />?
!
! <input messageLabel="<emph>xs:NCName</emph>"? element="<emph>union of xs:QName, xs:Token</emph>"? >
! <documentation />?
!
! <feature ... />*
! <property ... />*
</input>*
! <output messageLabel="<emph>xs:NCName</emph>"? element="<emph>union of xs:QName, xs:Token</emph>"? >
! <documentation />?
!
! <feature ... />*
!
! <property ... />*
</output>*
! <infault ref="<emph>xs:QName</emph>" messageLabel="<emph>xs:NCName</emph>"? >
! <documentation />?
!
! <feature ... />*
!
! <property ... />*
! </infault>*
!
! <outfault ref="<emph>xs:QName</emph>" messageLabel="<emph>xs:NCName</emph>"? >
! <documentation />?
!
! <feature ... />*
!
! <property ... />*
! </outfault>*
! <feature ... />*
- <property ... />*
</operation>*
- <feature uri="<emph>xs:anyURI</emph>" required="<emph>xs:boolean</emph>"? >
- <documentation />?
- </feature>*
-
- <property uri="<emph>xs:anyURI</emph>" required="<emph>xs:boolean</emph>"? >
- <documentation />?
-
- <value> <emph>xs:anyType</emph> </value>?
-
- <constraint> <emph>xs:QName</emph> </constraint>?
- </property>*
</interface>*
!
!
! </description >
!
! </eg>
! <p>One WSDL <code>description</code> element may contain zero or more <code>interface</code> elements as its direct children. Zero <code>interface</code> elements are permitted since a <code>description</code> element may only contain binding and/or endpoint definitions to be aggegrated into a master WSDL description via import/include mechanisms. </p>
! <p>Let's have a look at the attributes of <code>interface</code> first. It has one required <att>name</att> attribute. Within the same WSDL target namespace (which might be in different WSDL documents; see section @@@@), each interface must have a unique name. The <code>interface</code> element has two optional attributes:<att>extends</att> and <att>styleDefault</att>. <att>extends</att> will be explained in the next section. We will explain what a <att>style</att> later. For now, keep in mind that the optional <att>styleDefault</att> attribute of <code>interface</code> can be used to define a default value for the <att>style</att> attribute of all operations under this interface, if any of the operations do not specify a value for its <att>style</att>. </p>
! <div3 id="more-interfaces-inheritance">
! <head>Interface Inheritance</head>
! <p>The optional <att>extends</att> attribute allows an interface to extend one or more other interfaces. In such cases the interface contains the operations of the interfaces it extends, along with any operations it defines. Two things about extending interfaces deserve some attention. </p><p>First, recursive extension of interfaces is prohibited. The interfaces that a given interface extends MUST NOT themselves extend that interface either directly or indirectly. </p><p>Second, there may be cases where, due to an interface extending one or more other interfaces, operations from different interface may have a name collision. More precisely, within the same namespace, two or more interface operations end up having the same name. In such cases, WSDL 2.0 requires that the component models of those Interface Operation components MUST be equivalent (see WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> "<xspecref href="http://www.w3.org/TR/wsdl20-primer#compequiv">Equivalence of Components</xspecref>"). Foroperations, basically equivalence means the two operations in question have the same set of attributes and descendents). If the collisional operations are equivalent then they are considered to collapse into a single operation. It is an error if they have the same name in the same WSDL target namespace but are not equivalent. In other words, if two interfaces have name collisional operations, then those two interfaces cannot both form part of the derivation chain of a derived interface unless those operations are exactly the same. For the above reason, it is considered good practic to ensure that all operations within the same namespace are named uniquely whenever possible. Furthermore, since faults, features and properties can also be defined as children of the <code>interface</code> element (as descrbed later), the same name-collision resolution 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 children of <code>interface</code>. An <code>interface</code> can contain zero or more <code>fault</code>, zero or more <code>operation</code>, zero or more <code>feature</code>, and zero or more <code>property</code>. <code>feature</code> and <code>property</code> will be examined in section @@@@. We will explain the <code>fault</code> and <code>operation</code> constructs in the following sections. </p>
! </div3>
! <div3 id="more-interfaces-faults">
! <head>Reusable Faults</head>
! <p>The <code>fault</code> element can be used to declare faults that may occur during execution of operations of an interface. Declaring <code>fault</code>s directly under <code>interface</code> and referencing these faults in operations where they apply allow one to easily indicate that some faults can occur in multiple operations. </p>
! <p>The <code>fault</code> element has a required <att>name</att> attribute. Within a same namespace, all faults must be named uniquely. The optional <att>element</att> attribute can be used to indicate the content or playload of the fault message. Its value should be the QName of the XML schema global element declaration which defines the fault message. Please note when other type systems are used to define a fault message, additional attributes may need to be defined via WSDL's attribute extension mechanism to allow associating such a message definition with the fault.</p>
! <p>Here is an example of reusing faults.</p>
! <ednote><name>dbooth</name><edtext>To do: Update this example</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>
! falut 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>
- </div3>
- <div3 id="more-interfaces-operations">
- <head>Interface Operations</head>
- <p>Now we are ready to take a close look at the <code>operation</code> element. As explained earlier, message types are defined in a type system, and the sequencing and cardinality of the messages involved in a particular interaction are governed by the message exchange pattern (MEP). The <code>operation</code> element is the glue that brings all the pieces together for an abstract interaction. </p>
- <p>WSDL 2.0 defines two required and two optional attributes for an <code>operation</code>:</p>
- <ulist>
- <item>
- <p>A required <att>name</att> attribute</p>
- <p>Operation names must be unique within an interface. Beware that <code>operations</code>are local to an <code>interface</code>,so two <code>interface</code> elements sharing the same WSDL target namespace but with different interface names MAY contain <code>operations</code> that have the same name. Thus, <code>operations</code> cannot be referenced by QName since the <att>name</att> and WSDL target namespace are not sufficient to uniquely identify an <code>operation</code>. In order to uniquely identify an <code>operation</code>, one must first identify the <code>interface</code> by QName and then identify the <code>operation</code> within that <code>interface</code> by a further QName. As explained in section @@@, this fact has compound impact when an interface extends other interfaces. It is considered good practice to name operations uniquely within same namespace whenever possible.</p>
- </item>
- <item>
- <p>A required <att>pattern</att> attribute</p>
- <p>it identifies the MEP a given <code>operation</code> uses. Its value must be an absolute URI.</p>
- </item>
- <item>
- <p>An optional <att>style</att> attribute</p>
- <p>it's an absolute URI identifying the rules that were used to construct the message type definitions used by the <code>operation</code>. Note that the attribute MAY not present, but if it is present, then the rules implied by that value MUST be followed or it is an error. For example, WSDL 2.0 defines a set of rules for constructing so called RPC style messages (See section@@@@). If this attribute is set to "http://www.w3.org/2004/03/wsdl/style/rpc", then all the rules defined for the RPC style must be followed. We will have a closer look at RPC style in section@@@. </p>
- <ednote>
- <name>KevinL</name>
- <date>20040910</date>
- <edtext>
- Add Example and more text - illustrate use of RPC style
-
-
- </edtext>
- </ednote>
-
- </item>
- <item>
- <p>An optional <att>safety</att> attribute</p>
- <p>A boolean indicating whether the operation is asserted to be safe (as defined in Section 3.5 of Web Architecture for users of the described service to invoke. An operation SHOULD be marked safe by setting the <att>safty</att> to true if it meets all the criteria for a safe interaction defined in Section 3.5 of Web Architecture. The default value of this attribute is false. If it is false or is not set, then no assertion is made about the safety of the operation, thus the operation MAY or MAY NOT be safe.</p>
- </item>
- </ulist>
- <p>An <code>operation</code> references a set of ordinary and fault messages it accepts or sends via zero or more <code>input</code>, <code>output</code>,<code>infault</code>, and <code>outfault</code> element. Which of these constructs to use is governed by the MEP in use. As we have seen in section@@@@, an MEP defines a set of placeholder messages that participate in the pattern and assigns them unique names within the pattern. The <code>input</code> and <code>output</code> element are used to associate an actual mesage type with that message placeholder in the MEP. Such association is done via two attributes:<att>messageLabel</att> and <att>element</att>. The <att>messageLabel</att> attribute is used to identify the role this message plays in the MEP. Its value must match the name of the MEP place holder message. Note that the <att>messageLabel</att> is optional, since it's not necessary to explicitly set the messageLabel when the MEP in use has only one message with a given direction. The <att>eement</att> attribute can be used to identify the messages content (aka payload) when the content model is defined in XML Schema (see section @@@@ for using other type systems). The content model is a token with one of the values <emph>#any</emph>, <emph>#none</emph>, or <emph>#element</emph>. A value of <emph>#any</emph> indicates that the message content is any single element. A value of <emph>#none</emph> indicates there is no message content. It means that the payload will be empty. When the value is set to a QName, it indicates that the message consists of a single element described by the referenced global element declaration reference by QName. In addition, the direction implied by the <b>in</b>put, and <b>out</b>put must also match the direction of the placeholder message identified by <att>messageLabel</att>. </p>
- <p>We have already talked about how to associate a message type with a reusable interface <code>fault</code>. We have also covered the fault generation rules a MEP may use. Here under <code>operation</code>, the <code>infault</code> and <code>outfault</code> elements can be used to associate an interface <code>fault</code> with a specific message in the MEP used by an <code>operation</code>. Such association is done via a few attributes: the now familiar <att>messageLabel</att> attribute, the direction implied by the <b>in</b>fault and <b>out</b>fault, and a required <att>ref</att> attrbiute which points to the QName of an interface <code>fault</code>. When <code>infault</code> and/or <code>outfault</code> occur multiple times within an <code>operation</code>, they define alternative fault message. </p>
-
- <ednote><name>dbooth</name><edtext>To do: Update this example. Also: which features should it illustrate?</edtext></ednote><example id="example-operations">
- <head>Defining Interface Operations</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" >
!
! <fault name = "invalidCreditCardFault"
! element = "ghns:invalidCreditCardError"/>
!
! <fault name = "invalidDataFault"
! element = "ghns:invalidDataError"/>
!
! <<b>operation</b> name="<emph>checkAvailability</emph>" pattern="<emph>http://www.w3.org/2004/03/wsdl/in-out</emph>" >
!
! <input messageLabel="<emph>In</emph>" element="<emph>ghns:checkAvailability</emph>"/ >
! <output messageLabel="<emph>Out</emph>" element="<emph>ghns:checkAvailabilityResponse</emph>"/ >
! <outfault ref="<emph>invalidDataFault</emph>" messageLabel="<emph>Out</emph>"/>
! </<b>operation</b>>
! <<b>operation</b> name="<emph>makeReservation</emph>" pattern="<emph>http://www.w3.org/2004/03/wsdl/in-out</emph>" >
!
! <input messageLabel="<emph>In</emph>" element="<emph>ghns:makeReservation</emph>"/ >
! <output messageLabel="<emph>Out</emph>" element="<emph>ghns:makeReservationResponse</emph>"/ >
! <outfault ref="<emph>invalidDataFault</emph>" messageLabel="<emph>Out</emph>"/>
! <outfault ref="<emph>invalidCreditCardFault</emph>" messageLabel="<emph>Out</emph>"/>
! </<b>operation</b>>
- </interface>
</description>
</eg>
! </example>
! <p>Note that in the above example, the <emph>invalidDataFault</emph> is re-used by both operations. In the <emph>makeReservation</emph> operation, two alternative outgoing faults are defined which means either a invalidDataFault or a invalidCreditCardFault may be returned as a replacement of the outgoing message.</p>
! <p>An <code>operation</code> can also contain zero or more <code>feature</code> and <code>property</code> elements. We defer the explanation for <code>feature</code> and <code>property</code> to section @@@@. </p>
! </div3>
</div2>
! <!-- ************************messages*************************** -->
<!-- ************************MEPs*************************** -->
! <div2 id="more-interfaces-meps">
<head>Understanding Message Exchange Patterns</head>
<p>WSDL 2.0 message exchange patterns (MEPs) are used to define the sequence and cardinality of the abstract messages in an operation. By design, WSDL 2.0 MEPs are abstract. First of all, they abstract out specific message types. MEPs identify placeholders for messages, and placeholders are associated with specific message types when an operation is defined, which includes specifying which MEP to use for that operation. Secondly, unless explicitly stated otherwise, MEPs also abstract out binding-specific information like timing between messages, whether the pattern is synchronous or asynchronous, and whether the messages are sent over a single or multiple channels.</p>
--- 656,805 ----
<!-- ************************interface*************************** -->
! <p>We previously mentioned that a WSDL 2.0 interface is basically a set of operations. However, there are some additional capabilities that we have not yet covered. First, let's review the syntax for the <code>interface</code> element. </p>
<div2 id="more-interfaces-interfaces">
<head>Interface Syntax </head>
!
! <p>Below is the XML syntax summary of the <code>interface</code> element, simplified by omitting optional <code><documentation></code> elements and <code><feature></code> and <code><property></code> extension elements:</p>
<eg xml:space="preserve">
<description targetNamespace="<emph>xs:anyURI</emph>" >
! . . .
! <interface name="<emph>xs:NCName</emph>"
! extends="<emph>list of xs:QName</emph>"?
! styleDefault="<emph>list of xs:anyURI</emph>"? >
! <fault name="<emph>xs:NCName</emph>"
! element="<emph>xs:QName</emph>"? >
</fault>*
! <operation name="<emph>xs:NCName</emph>"
! pattern="<emph>xs:anyURI</emph>"
! style="<emph>list of xs:anyURI</emph>"?
! safe="<emph>xs:boolean</emph>"? >
! <input messageLabel="<emph>xs:NCName</emph>"?
! element="<emph>union of xs:QName, xs:Token</emph>"? >
</input>*
! <output messageLabel="<emph>xs:NCName</emph>"?
! element="<emph>union of xs:QName, xs:Token</emph>"? >
</output>*
! <infault ref="<emph>xs:QName</emph>" messageLabel="<emph>xs:NCName</emph>"? > </infault>*
! <outfault ref="<emph>xs:QName</emph>" messageLabel="<emph>xs:NCName</emph>"? > </outfault>*
</operation>*
</interface>*
! . . .
</description>
+
</eg>
!
! <p>The <code>interface</code> element has two optional attributes: <att>styleDefault</att> and <att>extends</att>. The <att>styleDefault</att> attribute can be used to define a default value for the <att>style</att> attributes of all operations under this interface (see WSDL 2.0 Part 1 "<xspecref href="http://www.w3.org/TR/wsdl20-primer#Interface_styleDefault_attribute">styleDefault attribute information item</xspecref>"). The <att>extends</att> attribute is for inheritance, and is explained next. </p>
!
! </div2>
! <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">
! <head>Reusable Faults</head>
! <p>The <code>fault</code> element is used to declare faults that may occur during execution of operations of an interface. They are declared directly under <code>interface</code>, and referenced from operations where they apply, in order to permit reuse across multiple operations. </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>
!
</div2>
! <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>
!
!
!
! <div3><head>Operation Attributes</head><p>An <code>operation</code> has two required and two optional attributes:</p>
! <ulist>
! <item>
! <p>A required <att>name</att> attribute, as seen already, which must be unique within the interface.</p>
!
! </item>
! <item>
! <p>A required <att>pattern</att> attribute whose value must be an absolute URI that identifies the desired MEP for the <code>operation</code>. MEPs are further explained in <specref ref="more-interfaces-meps"/>.</p>
!
! </item>
! <item>
! <p>An optional <att>style</att> attribute whose value is a a list of absolute URIs. Each URI identifies a certain set of rules that were used to construct the message type definitions used by the <code>operation</code>. It is an error if a particular style is indicated, but the associated rules are not followed. See <specref ref="adv-RPCstyle"/> for an example of using the <code>style</code> attribute.</p>
! <ednote><edtext>ToDo: add a list of predefined style URIs here, with a sentence for each one, explaining its purpose.</edtext></ednote>
!
!
! </item>
! <item>
! <p>An optional <att>safety</att> attribute whose value is a boolean indicating whether the operation is asserted to be "safe" (as defined in Section 3.5 of the Web Architecture <bibref ref="webarch"/>) for clients to invoke. In essence, a safe operation is any operation that does not give the client any new obligations. For example, an operation that permits the client to check prices on products typically would not obligate the client to buy those products, and thus would be safe, whereas an operation for purchasing products would obligate the client to pay for the products that were ordered, and thus would not be safe. </p><p>An operation SHOULD be marked safe (by setting the <att>safety</att> to true) if it meets the criteria for a safe interaction defined in Section 3.5 of the Web Architecture <bibref ref="webarch"/>, because this permits the infrastructure to perform efficiency optimizations, such as pre-fetch, re-fetch and caching. </p><p>The default value of this attribute is false. If i is false or is not set, then no assertion is made about the safety of the operation; thus the operation MAY or MAY NOT be safe.</p>
! </item>
! </ulist></div3><div3><head>Operation Message References</head><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 <specref ref="basics-interface"/>, this section will merely comment on additional capabilities that were not previously explained.</p>
! <div4><head>The messageLabel Attribute</head><p>The <att>messageLabel</att> 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 <bibref ref="WSDL-PART2"/> and it has only one message with a given direction. </p></div4><div4><head>The element Attribute</head><p>The <att>element</att> 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: <glist><gitem><label><code>#any</code></label><def><p>The message content is any single element.</p></def></gitem><gitem><label><code>#none</code></label><def><p>There is no mesage content, i.e., the message payload is empty.</p></def></gitem></glist>The <code>element</code> attribute is also optional. If it is not specified, then @@@@. <ednote><edtext>ToDo: Say 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 </edtext></ednote></p></div4><div4><head>Multiple infault or outfault Elements</head><p>When <code>infault</code> and/or <code>outfault</code> occur multiple times within an <code>operation</code>, they define alternative fault messages. </p></div4></div3>
! <!-- ************************messages*************************** -->
<!-- ************************MEPs*************************** -->
! <div3 id="more-interfaces-meps">
<head>Understanding Message Exchange Patterns</head>
<p>WSDL 2.0 message exchange patterns (MEPs) are used to define the sequence and cardinality of the abstract messages in an operation. By design, WSDL 2.0 MEPs are abstract. First of all, they abstract out specific message types. MEPs identify placeholders for messages, and placeholders are associated with specific message types when an operation is defined, which includes specifying which MEP to use for that operation. Secondly, unless explicitly stated otherwise, MEPs also abstract out binding-specific information like timing between messages, whether the pattern is synchronous or asynchronous, and whether the messages are sent over a single or multiple channels.</p>
***************
*** 927,934 ****
other nodes. To maximize reuse, WSDL message exchange patterns identify a minimal contract between other parties and Web Services, and contain only information that is
relevant to both the Web service and the client that engages that service.</p>
! <p>A total of 8 MEPs are defined in WSDL 2.0 Part 2 <bibref ref="WSDL-PART2"/>. Hopefully, these MEPs will cover the most common use cases, but they are not meant to be an exhaustive list of MEPs that can be used by operations. More MEPs can be defined for particular application needs by interested parties. <ednote><name>dbooth</name><edtext>Add info about how to define a new MEP?</edtext></ednote></p>
<p>For the 8 MEPs defined by WSDL 2.0, some of them are variations of others based on how faults may be generated. Three common fault generation models are specified. <glist><gitem><label>Fault Replaces Message</label><def><p>Any message after the first in the pattern MAY be replaced with a fault message, which MUST have identical cardinality and direction. The fault message MUST be delivered to the same target node as the message it replaces. </p></def></gitem><gitem><label>Message Triggers Fault</label><def><p>Any message, including the first, MAY trigger a fault message in response. Each recipient MAY generate a fault message, and MUST generate no more than one fault for each triggering message. Each fault message has direction the reverse of its triggering message. The fault message MUST be delivered to the originator of the message which triggered it. If there is no path to this node, the fault MUST be discarded. In the third case, no fault may be generated in the MEP. </p></def></gitem><gitem><abel>No Faults</label><def><p>No faults will be delivered.</p></def></gitem></glist></p>
<p>Now let's have a look of each of the 8 MEPs. Depends on how the first message in the MEP is initiated, we can probably group the MEPs into in-bound MEPs in which case the service receives the first message in the exchange, and out-bound MEPs in which case the service sends out the first message in the exchange. Such Grouping is only for the purpose of easy reference from discussions in later sections of this primer. WSDL 2.0 defines four in-bound MEPS:</p>
! <ulist>
<item>
<p>
--- 811,818 ----
other nodes. To maximize reuse, WSDL message exchange patterns identify a minimal contract between other parties and Web Services, and contain only information that is
relevant to both the Web service and the client that engages that service.</p>
! <p>A total of 8 MEPs are defined in WSDL 2.0 Part 2 <bibref ref="WSDL-PART2"/>. Hopefully, these MEPs will cover the most common use cases, but they are not meant to be an exhaustive list of MEPs that can ever be used by operations. More MEPs can be defined for particular application needs by interested parties. (See <ednote><name>dbooth</name><edtext>Add info about how to define a new MEP?</edtext></ednote></p>
<p>For the 8 MEPs defined by WSDL 2.0, some of them are variations of others based on how faults may be generated. Three common fault generation models are specified. <glist><gitem><label>Fault Replaces Message</label><def><p>Any message after the first in the pattern MAY be replaced with a fault message, which MUST have identical cardinality and direction. The fault message MUST be delivered to the same target node as the message it replaces. </p></def></gitem><gitem><label>Message Triggers Fault</label><def><p>Any message, including the first, MAY trigger a fault message in response. Each recipient MAY generate a fault message, and MUST generate no more than one fault for each triggering message. Each fault message has direction the reverse of its triggering message. The fault message MUST be delivered to the originator of the message which triggered it. If there is no path to this node, the fault MUST be discarded. In the third case, no fault may be generated in the MEP. </p></def></gitem><gitem><abel>No Faults</label><def><p>No faults will be delivered.</p></def></gitem></glist></p>
<p>Now let's have a look of each of the 8 MEPs. Depends on how the first message in the MEP is initiated, we can probably group the MEPs into in-bound MEPs in which case the service receives the first message in the exchange, and out-bound MEPs in which case the service sends out the first message in the exchange. Such Grouping is only for the purpose of easy reference from discussions in later sections of this primer. WSDL 2.0 defines four in-bound MEPS:</p>
! <ednote><edtext>ToDo: Check/update the MEP URIs prior to final publication.</edtext></ednote><ulist>
<item>
<p>
***************
*** 980,984 ****
<date>20040910</date>
<edtext>
! Add more use cases and example - illustrate use of outbound meps?
</edtext>
--- 864,868 ----
<date>20040910</date>
<edtext>
! Add more MEP use cases and example - illustrate use of outbound meps?
</edtext>
***************
*** 986,990 ****
! <ednote><name>dbooth</name><date>20050401</date><edtext>ToDo: Add a section on defining a new MEP. (dbooth will do this if he has time.)</edtext></ednote></div2></div1>
<!-- **********************************Binding************************** -->
<!-- **********************************Binding************************** -->
--- 870,889 ----
! </div3>
!
! <div3 id="more-interfaces-defining-meps"><head>Defining New Message Exchange Patterns (MEPs)</head><p>Although the 8 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.<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>
<!-- **********************************Binding************************** -->
<!-- **********************************Binding************************** -->
***************
*** 1265,1269 ****
<!-- **********************************AdvancedTopics***************** -->
<div1 id="advanced-topic_ii">
! <head>Advanced Topics II - TBD</head>
<ednote>
<name>KevinL</name>
--- 1164,1168 ----
<!-- **********************************AdvancedTopics***************** -->
<div1 id="advanced-topic_ii">
! <head>Advanced Topics - TBD</head>
<ednote>
<name>KevinL</name>
Index: wsdl20-primer.html
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.html,v
retrieving revision 1.27
retrieving revision 1.28
diff -C2 -d -r1.27 -r1.28
*** wsdl20-primer.html 14 Apr 2005 02:07:18 -0000 1.27
--- wsdl20-primer.html 14 Apr 2005 21:40:45 -0000 1.28
***************
*** 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"
[...7380 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 Thursday, 14 April 2005 21:40:49 UTC