- From: David Booth <dbooth@dev.w3.org>
- Date: Wed, 26 Jan 2005 20:00:14 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20
In directory hutz:/tmp/cvs-serv16324
Modified Files:
wsdl20-primer.xml wsdl20-primer.html
Log Message:
Misc small fixes from Arthur Ryman:
http://lists.w3.org/Archives/Public/www-ws-desc/2005Jan/0042.html
Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.28
retrieving revision 1.29
diff -C2 -d -r1.28 -r1.29
*** wsdl20-primer.xml 20 Dec 2004 17:15:57 -0000 1.28
--- wsdl20-primer.xml 26 Jan 2005 20:00:12 -0000 1.29
***************
*** 220,224 ****
. . .
</description>]]></eg>
! </example><div3 id="example-initial-types-explanation"><head>Explanation of Example</head><glist><gitem><label><code>xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"</code></label><def><p>We've added another namespace declaration. The <code>ghns</code> namespace prefix will allow us (later, when defining an interface) to reference the XML Schema target namespace that we define for our message types. Thus, the URI we specify must be the same as the URI that we define as the target namespace of our XML Schema types (below) -- <emph>not</emph> the target namespace of the WSDL document itself.</p></def></gitem><gitem><label><code>targetNamespace="http://greath.example.com/2004/schemas/resSvc.xsd"</code></label><def><p>This is the XML Schema target namespace that we've created for use by the GreatH reservation service. The <code>checkAvailability</code>, <code>checkAvailability</code> and <code>invalidDataError</code> element names will be associated with this XML Schema target namespae.</p></def></gitem><gitem><label><code>checkAvailability</code>, <code>checkAvailabilityResponse</code> and <code>invalidDataError</code></label><def><p>These are the message types that we'll use. Note that these are defined to be XML <emph>elements</emph>, as explained above.</p></def></gitem></glist><p>Although we have defined several types, we have not yet indicated which ones are to be used as message types for a Web service. We'll do that in the next section. </p></div3></div2><div2 id="basics-interface"><head>Defining an Interface</head><p>WSDL 2.0 enables one to separate the description of a Web service's abstract functionality from the concrete details of how and where that functionality is offered. This separation facilitates different levels of reusability and distribution of work in the lifecycle of a Web service and the WSDL document that describes it. </p><p>A WSDL 2.0 <el>interface</el> defines the abstract interface of a Web service as a set of abstract <emph>operations</emph>, each opration representing a simple interaction between the client and the service. Each operation specifies the types of messages that the service can send or receive as part of that operation. Each operation also specifies a message exchange <emph>pattern</emph> that indicates the sequence in which the associated messages are to be transmitted between the parties. For example, the <emph>in-out</emph> pattern (see <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>) indicates that if the client sends a message <emph>in</emph> to the service, the service will either send a reply message back <emph>out</emph> to the client (in the normal case) or it will send a fault message back to the client (in the case of an error).</p><p>For the GreatH service, we will (initially) define an interface containing a single operation, <code>opCheckAvailability</code>, using the <code>checkAvailaility</code> and <code>checkAvailabilityResponse</code> message types that we defined in the <el>types</el> section. We'll use the <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref> pattern for this operation, because this is the most natural way to represent a simple request-response interaction. We could have instead (for example) defined two separate operations using the <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-only</xspecref> and <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#out-only">out-only</xspecref> patterns (see <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSDL-PART2"/> section 2.2.1 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-only">In-Only</xspecref> and section 2.2.5 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#out-only">Out-Only</xspecref>), but that would just complicate matters for the client, becausewe would then have to separately indicate to the client developer that the two operations should be used together as a request-response pair.</p><p>In addition to the normal input and output messages, we also need to specify the fault message that we wish to use in the event of an error. WSDL 2.0 permits fault messages to be declared within the <el>interface</el> element in order to facilitate reuse of faults across operations. If a fault occurs, it terminates whatever message sequence was indicated by the message exchange pattern of the operation. </p><p>Let's add these to our WSDL document.</p><example id="example-initial-interface">
<head>GreatH Interface Definition</head>
--- 220,224 ----
. . .
</description>]]></eg>
! </example><div3 id="example-initial-types-explanation"><head>Explanation of Example</head><glist><gitem><label><code>xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"</code></label><def><p>We've added another namespace declaration. The <code>ghns</code> namespace prefix will allow us (later, when defining an interface) to reference the XML Schema target namespace that we define for our message types. Thus, the URI we specify must be the same as the URI that we define as the target namespace of our XML Schema types (below) -- <emph>not</emph> the target namespace of the WSDL document itself.</p></def></gitem><gitem><label><code>targetNamespace="http://greath.example.com/2004/schemas/resSvc.xsd"</code></label><def><p>This is the XML Schema target namespace that we've created for use by the GreatH reservation service. The <code>checkAvailability</code>, <code>checkAvailabilityResponse</code> and <code>invalidDataError</code> element names will be associated with this XML Schema targetnamespace.</p></def></gitem><gitem><label><code>checkAvailability</code>, <code>checkAvailabilityResponse</code> and <code>invalidDataError</code></label><def><p>These are the message types that we'll use. Note that these are defined to be XML <emph>elements</emph>, as explained above.</p></def></gitem></glist><p>Although we have defined several types, we have not yet indicated which ones are to be used as message types for a Web service. We'll do that in the next section. </p></div3></div2><div2 id="basics-interface"><head>Defining an Interface</head><p>WSDL 2.0 enables one to separate the description of a Web service's abstract functionality from the concrete details of how and where that functionality is offered. This separation facilitates different levels of reusability and distribution of work in the lifecycle of a Web service and the WSDL document that describes it. </p><p>A WSDL 2.0 <el>interface</el> defines the abstract interface of a Web service as a set of abstract <emph>operations</emph>,each operation representing a simple interaction between the client and the service. Each operation specifies the types of messages that the service can send or receive as part of that operation. Each operation also specifies a message exchange <emph>pattern</emph> that indicates the sequence in which the associated messages are to be transmitted between the parties. For example, the <emph>in-out</emph> pattern (see <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>) indicates that if the client sends a message <emph>in</emph> to the service, the service will either send a reply message back <emph>out</emph> to the client (in the normal case) or it will send a fault message back to the client (in the case of an error).</p><p>For the GreatH service, we will (initially) define an interface containing a single operation, <code>opCheckAvailability</code>, using the <code>chekAvailability</code> and <code>checkAvailabilityResponse</code> message types that we defined in the <el>types</el> section. We'll use the <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref> pattern for this operation, because this is the most natural way to represent a simple request-response interaction. We could have instead (for example) defined two separate operations using the <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-only</xspecref> and <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#out-only">out-only</xspecref> patterns (see <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSDL-PART2"/> section 2.2.1 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-only">In-Only</xspecref> and section 2.2.5 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#out-only">Out-Only</xspecref>), but that would just complicate matters for the client,because we would then have to separately indicate to the client developer that the two operations should be used together as a request-response pair.</p><p>In addition to the normal input and output messages, we also need to specify the fault message that we wish to use in the event of an error. WSDL 2.0 permits fault messages to be declared within the <el>interface</el> element in order to facilitate reuse of faults across operations. If a fault occurs, it terminates whatever message sequence was indicated by the message exchange pattern of the operation. </p><p>Let's add these to our WSDL document.</p><example id="example-initial-interface">
<head>GreatH Interface Definition</head>
***************
*** 812,817 ****
</item>
</ulist>
! <p>An <el>operation</el> references a set of ordinary and fault messages it accepts or sends via zero or more <el>input</el>, <el>output</el>,<el>infault</el>, and <el>outfault</el> 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 <el>input</el> and <el>output</el> 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>element</att> attribute can b 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 <el>fault</el>. We have also covered the fault generation rules a MEP may use. Here under <el>operation</el>, the <el>infault</el> and <el>outfault</el> elements can be used to associate an interface <el>fault</el> with a specific message in the MEP used by an <el>operation</el>. 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 <el>fault</el>. When <el>infault</el> and/or <el>outfault</el> occur multiple times within an <el>operation</el>, 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">
--- 812,817 ----
</item>
</ulist>
! <p>An <el>operation</el> references a set of ordinary and fault messages it accepts or sends via zero or more <el>input</el>, <el>output</el>,<el>infault</el>, and <el>outfault</el> 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 <el>input</el> and <el>output</el> 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>element</att> attribute can b 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 <el>fault</el>. We have also covered the fault generation rules a MEP may use. Here under <el>operation</el>, the <el>infault</el> and <el>outfault</el> elements can be used to associate an interface <el>fault</el> with a specific message in the MEP used by an <el>operation</el>. 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 <el>fault</el>. When <el>infault</el> and/or <el>outfault</el> occur multiple times within an <el>operation</el>, 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">
***************
*** 1025,1029 ****
exchange as defined by an interface <el>operation</el> and its binding
counterpart the binding <el>operation</el>. </p>
! <p>A binding <el>fault</el> has one required <att>ref</att> attribute which is a reference, by Qname, to an <el>interface</el>
<att>fault</att>. It identifies the abstract interface <el>fault</el> for which binding information is being specified. Be aware that the value of <att>ref</att> attribute of all the <el>faults</el> under a <el>binding</el>
MUST be unique. That is, one cannot define multiple bindings for the same interface fault within a given <el>binding</el>.</p>
--- 1025,1029 ----
exchange as defined by an interface <el>operation</el> and its binding
counterpart the binding <el>operation</el>. </p>
! <p>A binding <el>fault</el> has one required <att>ref</att> attribute which is a reference, by QName, to an <el>interface</el>
<att>fault</att>. It identifies the abstract interface <el>fault</el> for which binding information is being specified. Be aware that the value of <att>ref</att> attribute of all the <el>faults</el> under a <el>binding</el>
MUST be unique. That is, one cannot define multiple bindings for the same interface fault within a given <el>binding</el>.</p>
***************
*** 1100,1104 ****
<p>A <el>service</el> has a required <att>name</att> attribute (also see section @@@@ for service reference). Each <el>service</el> within a same namespace must be named uniquely. A <el>service</el> can only implement one single interface, and it must specify the single interface it implements via the <att>interface</att> attribute. </p>
<p>A <el>service</el> may contain one or more alternate <el>endpoints</el>. An <el>endpoint</el> defines the particulars of a specific endpoint at which a given service is available.</p>
! <p>An <el>endpoint</el> has two required attributes: <att>name</att> and <att>binding</att>. All <el>endpoints</el> within a <el>service</el> must be named uniquely via the <att>name</att> attribute. The required <att>binding</att> attribute refers to, via Qname, a <el>binding</el> definition. Note that if the refered <el>binding</el> specifies a particular interface, that interface MUST be the same as the one implmented by the parent <el>service</el>. </p>
<p>Like the WSDL binding constructs explained in section @@@@, the WSDL <el>endpoint</el> construct is also like an anchor for hosting extension elements that are used to provide information specific to a
particular endpoint in a server. The semantics of such extensions are defined by the specification for those extensions. Such specifications are expected to annotate the WSDL <el>endpoint</el> construct with additional properties and specify the mapping between those properties and the XML representation. For example, The SOAP and HTTP binding extensions defined in WSDL 2.0 part 3 also provides extensions to be used under a service <el>endpoint</el>. </p>
--- 1100,1104 ----
<p>A <el>service</el> has a required <att>name</att> attribute (also see section @@@@ for service reference). Each <el>service</el> within a same namespace must be named uniquely. A <el>service</el> can only implement one single interface, and it must specify the single interface it implements via the <att>interface</att> attribute. </p>
<p>A <el>service</el> may contain one or more alternate <el>endpoints</el>. An <el>endpoint</el> defines the particulars of a specific endpoint at which a given service is available.</p>
! <p>An <el>endpoint</el> has two required attributes: <att>name</att> and <att>binding</att>. All <el>endpoints</el> within a <el>service</el> must be named uniquely via the <att>name</att> attribute. The required <att>binding</att> attribute refers to, via QName, a <el>binding</el> definition. Note that if the refered <el>binding</el> specifies a particular interface, that interface MUST be the same as the one implmented by the parent <el>service</el>. </p>
<p>Like the WSDL binding constructs explained in section @@@@, the WSDL <el>endpoint</el> construct is also like an anchor for hosting extension elements that are used to provide information specific to a
particular endpoint in a server. The semantics of such extensions are defined by the specification for those extensions. Such specifications are expected to annotate the WSDL <el>endpoint</el> construct with additional properties and specify the mapping between those properties and the XML representation. For example, The SOAP and HTTP binding extensions defined in WSDL 2.0 part 3 also provides extensions to be used under a service <el>endpoint</el>. </p>
***************
*** 1197,1216 ****
relative URIs is allowed and warranted in many
cases. For information on processing relative URIs, see
! <loc href="http://www.ietf.org/rfc/rfc2396.txt">RFC2396</loc>.</p></div3><div3 id="adv-generating-uris"><head>Generating URIs</head><ednote><name>dbooth</name><edtext>Is this convention vendor-specific? http://tempuri.org only seems to mention MS tools. If so, this section needs to be further edited or removed.</edtext></ednote><p>When working with WSDL, it is sometimes desirable to make
! up a URI for an entity, but not make the URI globally unique
for all time and have it "mean" that version of the
! entity (schema, WSDL document, etc.). There is a particular
! URI base reserved for use for this type of behavior. The base
! URI <attval>http://tempuri.org/</attval> can be used to
! construct a URI without any unique association to an entity.
! For example, two people or programs could choose to
! simultaneously use the URI <attval>
! http://tempuri.org/userSchema</attval> for two completely
! different schemas, and as long as the scope of the use of the
! URIs does not intersect, then they are considered unique
! enough. This has the further benefit that the entity referenced by the URI can be versioned without having to generate a
! new URI, as long as it makes sense within the processing
! context. It is not recommended that <attval>
! http://tempuri.org/</attval> be used as a base for stable,
fixed entities.</p></div3></div2>
</div1>
--- 1197,1213 ----
relative URIs is allowed and warranted in many
cases. For information on processing relative URIs, see
! <loc href="http://www.ietf.org/rfc/rfc2396.txt">RFC2396</loc>.</p></div3><div3 id="adv-generating-uris"><head>Generating Temporary URIs</head><p>In general, when a WSDL document is published for use by others, it should contain URIs that are globally unique. This is usually done by allocating them under a domain name that is controlled by the issuer. For example, the W3C allocates namespace URIs under its base domain name, w3.org.</p><p>However, it is sometimes desirable to make
! up a temporary URI for an entity, for use during development, but not make the URI globally unique
for all time and have it "mean" that version of the
! entity (schema, WSDL document, etc.). <emph>Reserved Top Level DNS Names</emph> <bibref ref="RFC2606"/> specifies some URI base names that are reserved for use for this type of behavior. For example, the base
! URI <attval>http://example.org/</attval> can be used to
! construct a temporary URI without any unique association to an entity.
! This means that two people or programs could choose to
! simultaneously use the temporary URI <attval>
! http://example.org/userSchema</attval> for two completely
! different schemas. As long as the scope of use of these
! URIs does not intersect, then they would be unique
! enough. It is not recommended that <attval>
! http://example.org/</attval> be used as a base for stable,
fixed entities.</p></div3></div2>
</div1>
***************
*** 1408,1412 ****
http://www.ietf.org/rfc/rfc2045.txt.
</bibl>
! <bibl id="RFC2616" key="IETF RFC 2616" href="http://www.ietf.org/rfc/rfc2616.txt">
<titleref>Hypertext Transfer Protocol --
HTTP/1.1</titleref>, R. Fielding, J. Gettys, J. Mogul,
--- 1405,1413 ----
http://www.ietf.org/rfc/rfc2045.txt.
</bibl>
! <bibl id="RFC2606" key="IETF RFC 2606" href="http://www.ietf.org/rfc/rfc2606.txt">
! <titleref>Reserved Top Level DNS Names</titleref>, D. Eastlake, A. Panitz, Authors. Network Working Group, Internet Engineering
! Task Force, June 1999. Available at
! http://www.ietf.org/rfc/rfc2606.txt.
! </bibl><bibl id="RFC2616" key="IETF RFC 2616" href="http://www.ietf.org/rfc/rfc2616.txt">
<titleref>Hypertext Transfer Protocol --
HTTP/1.1</titleref>, R. Fielding, J. Gettys, J. Mogul,
Index: wsdl20-primer.html
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.html,v
retrieving revision 1.15
retrieving revision 1.16
diff -C2 -d -r1.15 -r1.16
*** wsdl20-primer.html 20 Dec 2004 17:15:57 -0000 1.15
--- wsdl20-primer.html 26 Jan 2005 20:00:12 -0000 1.16
***************
*** 1,13 ****
<!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" xml:lang="en">
<head>
! <meta name="generator" content=
! "HTML Tidy for Linux/x86 (vers 1st August 2004), see www.w3.org" />
! <meta http-equiv="Content-Type" content=
! "text/html; charset=utf-8" />
<title>Web Services Description Language (WSDL) Version 2.0 Part 0:
Primer</title>
[...4949 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>
***************
*** 3226,3227 ****
--- 3714,3716 ----
</body>
</html>
+
Received on Wednesday, 26 January 2005 20:00:15 UTC