- From: David Booth via cvs-syncmail <cvsmail@w3.org>
- Date: Fri, 18 Feb 2005 21:37:39 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20
In directory hutz:/tmp/cvs-serv26645
Modified Files:
wsdl20-primer.xml
Log Message:
Removed file extensions from namespaces
Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.29
retrieving revision 1.30
diff -C2 -d -r1.29 -r1.30
*** wsdl20-primer.xml 26 Jan 2005 20:00:12 -0000 1.29
--- wsdl20-primer.xml 18 Feb 2005 21:37:37 -0000 1.30
***************
*** 98,104 ****
<description
xmlns="http://www.w3.org/2004/08/wsdl"
! targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
! xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
! xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"
xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
--- 98,104 ----
<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"
xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"
xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
***************
*** 114,119 ****
<xs:schema
xmlns:xs="http://www.w3.org/2001/XMLSchema"
! targetNamespace="http://greath.example.com/2004/schemas/resSvc.xsd"
! xmlns="http://greath.example.com/2004/schemas/resSvc.xsd">
<xs:element name="checkAvailability" type="tCheckAvailability"/>
--- 114,119 ----
<xs:schema
xmlns:xs="http://www.w3.org/2001/XMLSchema"
! targetNamespace="http://greath.example.com/2004/schemas/resSvc"
! xmlns="http://greath.example.com/2004/schemas/resSvc">
<xs:element name="checkAvailability" type="tCheckAvailability"/>
***************
*** 177,196 ****
<description
xmlns="http://www.w3.org/2004/08/wsdl"
! targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
! xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
. . . >
. . .
</description>]]></eg>
! </example><div3 id="example-empty-shell-explanation"><head>Explanation of Example</head><p><glist><gitem><label><code><description</code></label><def><p>Every WSDL 2.0 document has a <el>description</el> element as its top-most element. This merely acts as a container for the rest of the WSDL 2.0 document, and is used to declare namespaces that will be used throughout the document.</p></def></gitem><gitem><label><code>xmlns="http://www.w3.org/2004/08/wsdl"</code></label><def><p>This is the XML namespace for WSDL 2.0 itself. Because we have not defined a prefix for it, any unprefixed elements or attributes are expected to be WSDL 2.0 elements or attributes (such as the <el>description</el> element).</p></def></gitem><gitem><label><code>targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"</code></label><def><p>This defines the WSDL target namespace that we have chosen for the GreatH reservation service, as described above. Note that this is not an actual XML namespace declaration. ather, it is a WSDL 2.0 attribute whose purpose is <emph>analogous</emph> to an XML Schema target namespace.</p></def></gitem><gitem><label><code>xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"</code></label><def><p>This is an actual XML namespace declaration for use in our GreatH service description. Note that this is the same URI that was specified above as the value of the <att>targetNamespace</att> attribute. This will allow us later to use the <code>tns:</code> prefix in qnames, to refer to the WSDL target namespace of the GreatH service. (For more on QNames see <bibref ref="XMLNS"/> section 3 <xspecref href="http://www.w3.org/TR/1999/REC-xml-names-19990114/#ns-qualnames">Qualified Names</xspecref>.)</p></def></gitem></glist></p><p> Now we can start describing the GreatH service. </p></div3></div2><div2 id="basics-types"><head>Defining Message Types</head><p>We know that the GreatH service will be sending and receiving messages, so a good starting point in describing the servic is to define the message types that the service will use. We'll use XML Schema to do so, because WSDL 2.0 requires all conformant WSDL processors to support XML Schema at a minimum. However, WSDL 2.0 does not prohibit the use of some other schema definition language.</p><p>WSDL 2.0 allows message types to be defined directly within the WSDL document, inside the <el>types</el> element, which is a child of the <el>description</el> element. (Later we'll see how we can provide the type definitions in a separate document, using XML Schema's <el>import</el> mechanism.) The following schema defines checkAvailability, checkAvailabilityResponse and invalidDataError message types that we'll need. </p><p>In WSDL 2.0, all normal and fault message types must be defined as single <emph>elements</emph> at the topmost level (though of course each element may have any amount of substructure inside it). Thus, a message type must not directly consist of a sequence of elements or other complex type. </p><example id=example-initial-types">
<head>GreatH Message Types</head>
<ednote><name>dbooth</name><edtext>Not sure the namespace declarations and prefixes in this schema declaration are correct. In particular, need to check: xmlns:xs="http://www.w3.org/2001/XMLSchema"
! xmlns="http://greath.example.com/2004/schemas/resSvc.xsd"</edtext></ednote><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.wsdl"
! xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
! xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
. . . >
--- 177,196 ----
<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"
. . . >
. . .
</description>]]></eg>
! </example><div3 id="example-empty-shell-explanation"><head>Explanation of Example</head><p><glist><gitem><label><code><description</code></label><def><p>Every WSDL 2.0 document has a <el>description</el> element as its top-most element. This merely acts as a container for the rest of the WSDL 2.0 document, and is used to declare namespaces that will be used throughout the document.</p></def></gitem><gitem><label><code>xmlns="http://www.w3.org/2004/08/wsdl"</code></label><def><p>This is the XML namespace for WSDL 2.0 itself. Because we have not defined a prefix for it, any unprefixed elements or attributes are expected to be WSDL 2.0 elements or attributes (such as the <el>description</el> element).</p></def></gitem><gitem><label><code>targetNamespace= "http://greath.example.com/2004/wsdl/resSvc"</code></label><def><p>This defines the WSDL target namespace that we have chosen for the GreatH reservation service, as described above. Note that this is not an actual XML namespace declaration. Rathe, it is a WSDL 2.0 attribute whose purpose is <emph>analogous</emph> to an XML Schema target namespace.</p></def></gitem><gitem><label><code>xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc"</code></label><def><p>This is an actual XML namespace declaration for use in our GreatH service description. Note that this is the same URI that was specified above as the value of the <att>targetNamespace</att> attribute. This will allow us later to use the <code>tns:</code> prefix in qnames, to refer to the WSDL target namespace of the GreatH service. (For more on QNames see <bibref ref="XMLNS"/> section 3 <xspecref href="http://www.w3.org/TR/1999/REC-xml-names-19990114/#ns-qualnames">Qualified Names</xspecref>.)</p></def></gitem></glist></p><p> Now we can start describing the GreatH service. </p></div3></div2><div2 id="basics-types"><head>Defining Message Types</head><p>We know that the GreatH service will be sending and receiving messages, so a good starting point in describing the service is to deine the message types that the service will use. We'll use XML Schema to do so, because WSDL 2.0 requires all conformant WSDL processors to support XML Schema at a minimum. However, WSDL 2.0 does not prohibit the use of some other schema definition language.</p><p>WSDL 2.0 allows message types to be defined directly within the WSDL document, inside the <el>types</el> element, which is a child of the <el>description</el> element. (Later we'll see how we can provide the type definitions in a separate document, using XML Schema's <el>import</el> mechanism.) The following schema defines checkAvailability, checkAvailabilityResponse and invalidDataError message types that we'll need. </p><p>In WSDL 2.0, all normal and fault message types must be defined as single <emph>elements</emph> at the topmost level (though of course each element may have any amount of substructure inside it). Thus, a message type must not directly consist of a sequence of elements or other complex type. </p><example id="example-iitial-types">
<head>GreatH Message Types</head>
<ednote><name>dbooth</name><edtext>Not sure the namespace declarations and prefixes in this schema declaration are correct. In particular, need to check: xmlns:xs="http://www.w3.org/2001/XMLSchema"
! xmlns="http://greath.example.com/2004/schemas/resSvc"</edtext></ednote><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"
. . . >
***************
*** 200,205 ****
<xs:schema
xmlns:xs="http://www.w3.org/2001/XMLSchema"
! targetNamespace="http://greath.example.com/2004/schemas/resSvc.xsd"
! xmlns="http://greath.example.com/2004/schemas/resSvc.xsd">
<xs:element name="checkAvailability" type="tCheckAvailability"/>
--- 200,205 ----
<xs:schema
xmlns:xs="http://www.w3.org/2001/XMLSchema"
! targetNamespace="http://greath.example.com/2004/schemas/resSvc"
! xmlns="http://greath.example.com/2004/schemas/resSvc">
<xs:element name="checkAvailability" type="tCheckAvailability"/>
***************
*** 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>
--- 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"</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"</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 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>
***************
*** 226,232 ****
<description
xmlns="http://www.w3.org/2004/08/wsdl"
! targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
! xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
! xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
. . . >
--- 226,232 ----
<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"
. . . >
***************
*** 235,240 ****
<xs:schema
xmlns:xs="http://www.w3.org/2001/XMLSchema"
! targetNamespace="http://greath.example.com/2004/schemas/resSvc.xsd"
! xmlns="http://greath.example.com/2004/schemas/resSvc.xsd">
<xs:element name="checkAvailability" type="tCheckAvailability"/>
--- 235,240 ----
<xs:schema
xmlns:xs="http://www.w3.org/2001/XMLSchema"
! targetNamespace="http://greath.example.com/2004/schemas/resSvc"
! xmlns="http://greath.example.com/2004/schemas/resSvc">
<xs:element name="checkAvailability" type="tCheckAvailability"/>
***************
*** 274,280 ****
<description
xmlns="http://www.w3.org/2004/08/wsdl"
! targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
! xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
! xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"
xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
--- 274,280 ----
<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"
xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"
xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
***************
*** 317,323 ****
<description
xmlns="http://www.w3.org/2004/08/wsdl"
! targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
! xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
! xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"
xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
--- 317,323 ----
<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"
xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"
xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
***************
*** 540,548 ****
<el>xs:schema</el> constructs is a necessary condition for making XML Schema
components available to a WSDL description. </p>
! <p>Please note the use of type system other than XML Schema is indicated by the extension elements in the above syntax. (See <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">Examples of Specifications of Extension Elements for Alternative Schema Language Support</xspecref>.)
</p>
<div3 id="more-types-schema-import">
<head>Importing XML Schema</head>
! <p>Let's examine the XML Schema <el>import</el> first. Note the schema import mechanism described here is defined in XML Schema Language with some additional restrictions. It is different from the WSDL import/include as explained in <specref ref="adv-import-and-authoring"/>. The schema components defined in the imported schema are available for reference by QName. Note that only components defined in the schema itself and components included by it via <el>xs:include</el> are available to WSDL. Specifically, components that the schema imports via <el>xs:import</el> are NOT available to WSDL. <ednote><name>dbooth</name><edtext>Check this. An issue was recently raised about import not being transitive.</edtext></ednote></p>
<p>A <el>types</el> element can contain zero or more <el>import</el>s which may have one or two attributes as follows:</p>
<ulist>
--- 540,548 ----
<el>xs:schema</el> constructs is a necessary condition for making XML Schema
components available to a WSDL description. </p>
! <p>The use of type system other than XML Schema is permitted by the extension elements in the above syntax. (See <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">Examples of Specifications of Extension Elements for Alternative Schema Language Support</xspecref>.)
</p>
<div3 id="more-types-schema-import">
<head>Importing XML Schema</head>
! <p>Let's examine the XML Schema <el>import</el> first. Note the schema import mechanism described here is defined in the XML Schema language with some additional restrictions. It is different from the WSDL import/include as explained in <specref ref="adv-import-and-authoring"/>. The schema components defined in the imported schema are available for reference by QName. Note that only components defined in the schema itself and components the schema includes via <el>xs:include</el> are available to WSDL. Specifically, components that the schema imports via <el>xs:import</el> are NOT available to WSDL. <ednote><name>dbooth</name><edtext>Check this. An issue was recently raised about import not being transitive.</edtext></ednote></p>
<p>A <el>types</el> element can contain zero or more <el>import</el>s which may have one or two attributes as follows:</p>
<ulist>
***************
*** 560,564 ****
<div3 id="more-types-schema-embed">
<head>Embedding XML Schema</head>
! <p>Embedding an XML schema uses the existing top-level <el>xs:schema</el> element defined by XML Schema <bibref ref="XMLSchemaP1"/>. It comparable to simply cutting and pasting an
existing, stand-alone schema to a location inside the <el>types</el> element.</p>
<p>The schema components defined in the embedded schema are available to
--- 560,564 ----
<div3 id="more-types-schema-embed">
<head>Embedding XML Schema</head>
! <p>When an XML schema is embedded directly in a WSDL document, it uses the existing top-level <el>xs:schema</el> element defined by XML Schema <bibref ref="XMLSchemaP1"/> to do so. This is comparable to simply cutting and pasting an
existing, stand-alone schema to a location inside the <el>types</el> element.</p>
<p>The schema components defined in the embedded schema are available to
***************
*** 586,590 ****
</edtext>
</ednote>
! <p>A <el>types</el> element can contain zero or more <el>schema</el>s which may have the following attributes:</p>
<ulist>
<item>
--- 586,590 ----
</edtext>
</ednote>
! <p>A <el>types</el> element can contain zero or more <el>schema</el> elements, which may have the following attributes:</p>
<ulist>
<item>
***************
*** 603,612 ****
<example id="example-schema-import">
<head>Importing Message Definitions into WSDL 2.0</head>
! <example><head>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.wsdl"
! xmlns:tns= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
! xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
. . . >
. . .
--- 603,612 ----
<example id="example-schema-import">
<head>Importing Message Definitions into WSDL 2.0</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"
. . . >
. . .
***************
*** 617,626 ****
</documentation>
! <xs:import namespace="http://greath.example.com/2004/schemas/resSvc.xsd"
schemaLocation= "http://greath.example.com/2004/schemas/resSvc.xsd"/>
</types>
. . .
! </description>]]></eg></example>
</example>
--- 617,626 ----
</documentation>
! <xs:import namespace="http://greath.example.com/2004/schemas/resSvc"
schemaLocation= "http://greath.example.com/2004/schemas/resSvc.xsd"/>
</types>
. . .
! </description>]]></eg>
</example>
***************
*** 630,634 ****
<!-- ************************interface*************************** -->
! <p>We previously mentioned that a WSDL 2.0 <el>interface</el> is basically a set of <el>operation</el>s. However, there are some additional capabilities that we have not yet covered. First, let's review the syntax for <el>interface</el>. </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 <el>interface</el> element:</p>
--- 630,634 ----
<!-- ************************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 <el>interface</el> 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 <el>interface</el> element:</p>
***************
*** 705,709 ****
</eg>
<p>One WSDL <el>description</el> element may contain zero or more <el>interface</el> elements as its direct children. Zero <el>interface</el> elements are permitted since a <el>description</el> 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 <el>interface</el> first. It has one required <att>name</att> attribute. Within the same WSDL target namespace (might be in different wsdl documents, see section @@@@), each interface must have a unique name. The <el>interface</el> 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 <el>interface</el> can be used to define a default value for the <att>style</att> attribute of all <el>operation</el>s under this <el>interface</el>, 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>
--- 705,709 ----
</eg>
<p>One WSDL <el>description</el> element may contain zero or more <el>interface</el> elements as its direct children. Zero <el>interface</el> elements are permitted since a <el>description</el> 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 <el>interface</el> 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 <el>interface</el> 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 <el>interface</el> 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>
***************
*** 730,735 ****
<description
! targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
! xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
xmlns = "http://www.w3.org/2004/08/wsdl"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
--- 730,735 ----
<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">
***************
*** 743,747 ****
<types>
! <xs:import namespace="http://greath.example.com/2004/schemas/resSvc.xsd"
schemaLocation= "http://greath.example.com/2004/schemas/resSvc.xsd"/>
--- 743,747 ----
<types>
! <xs:import namespace="http://greath.example.com/2004/schemas/resSvc"
schemaLocation= "http://greath.example.com/2004/schemas/resSvc.xsd"/>
***************
*** 782,791 ****
<div3 id="more-interfaces-operations">
<head>Interface Operations</head>
! <p>Now we are ready to take a close look at the <el>operation</el> 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 <el>operation</el> element is the glue that brings all the pieces together for an abstract interaction. The service indicates its participation in a MEP by using the MEP in its operations. Message placeholders defined in a MEP are associated with specific message types in operations.</p>
<p>WSDL 2.0 defines two required and two optional attributes for an <el>operation</el>:</p>
<ulist>
<item>
<p>A required <att>name</att> attribute</p>
! <p>Operation names must be unique within an interface. Beware that <el>operations</el>are local to an <el>interface</el>,so two <el>interface</el> elements sharing the same WSDL target namespace but with different name MAY contain <el>operations</el> which share the same name. Thus, <el>operations</el> cannot be referenced by QName since the <att>name</att> and WSDL target namespace are not sufficient to uniquely identify an <el>operation</el>. In order to uniquely identify an <el>operation</el>, one must first identify the <el>interface</el> by QName and then identify the <el>operation</el> within that <el>interface</el> 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>
--- 782,791 ----
<div3 id="more-interfaces-operations">
<head>Interface Operations</head>
! <p>Now we are ready to take a close look at the <el>operation</el> 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 <el>operation</el> 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 <el>operation</el>:</p>
<ulist>
<item>
<p>A required <att>name</att> attribute</p>
! <p>Operation names must be unique within an interface. Beware that <el>operations</el>are local to an <el>interface</el>,so two <el>interface</el> elements sharing the same WSDL target namespace but with different interface names MAY contain <el>operations</el> that have the same name. Thus, <el>operations</el> cannot be referenced by QName since the <att>name</att> and WSDL target namespace are not sufficient to uniquely identify an <el>operation</el>. In order to uniquely identify an <el>operation</el>, one must first identify the <el>interface</el> by QName and then identify the <el>operation</el> within that <el>interface</el> 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>
***************
*** 819,824 ****
<eg xml:space="preserve">
<description
! targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
! xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
xmlns = "http://www.w3.org/2004/08/wsdl"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
--- 819,824 ----
<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">
***************
*** 832,836 ****
<types>
! <xs:import namespace="http://greath.example.com/2004/schemas/resSvc.xsd"
schemaLocation= "http://greath.example.com/2004/schemas/resSvc.xsd"/>
--- 832,836 ----
<types>
! <xs:import namespace="http://greath.example.com/2004/schemas/resSvc"
schemaLocation= "http://greath.example.com/2004/schemas/resSvc.xsd"/>
***************
*** 881,889 ****
<div2 id="more-interfaces-meps">
<head>Understanding Message Exchange Patterns</head>
! <p>WSDL 2.0 message exchange patterns (MEPs) are used to defines 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 specifies which MEP to use. 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>
! <p>It's worth pointing out that like interfaces and operations, WSDL MEPs do not exhaustively describe the set of messages exchanged between a service and other
nodes. By some prior agreement, another node and/or the service may send other
messages (to each other or to other nodes) that are not described by the
! pattern. For instance, even though a pattern may define a single message sent
from a service to one other node, the Web Service may multicast that message to
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
--- 881,889 ----
<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>
! <p>It's worth pointing out that like interfaces and operations, WSDL MEPs do not exhaustively describe the set of messages that may be exchanged between a service and other
nodes. By some prior agreement, another node and/or the service may send other
messages (to each other or to other nodes) that are not described by the
! MEP. For instance, even though an MEP may define a single message sent
from a service to one other node, the Web Service may multicast that message to
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
***************
*** 958,962 ****
binding information MAY be specified on a per-operation basis if needed.
If a <el>binding</el> specifies any operation-specific
! binding details or any fault binding details, then it MUST specify an interface the binding information applies to, so as to indicate which interface the operations come from.Conversely, a <el>binding</el> that omits any
operation-specific binding details and any fault binding details
MAY omit specifying an interface. <el>bindings</el> that do not
--- 958,962 ----
binding information MAY be specified on a per-operation basis if needed.
If a <el>binding</el> specifies any operation-specific
! binding details or any fault binding details, then it MUST specify an interface the binding information applies to, so as to indicate which interface the operations come from. </p><p>To define a reusable binding, a <el>binding</el> should omit any
operation-specific binding details and any fault binding details
MAY omit specifying an interface. <el>bindings</el> that do not
***************
*** 1055,1060 ****
<description
! targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
! xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
xmlns = "http://www.w3.org/2004/08/wsdl"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
--- 1055,1060 ----
<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">
***************
*** 1070,1075 ****
<eg xml:space="preserve">
<description
! targetNamespace= "http://greath.example.com/2004/wsdl/resSvc.wsdl"
! xmlns:ghns = "http://greath.example.com/2004/schemas/resSvc.xsd"
xmlns = "http://www.w3.org/2004/08/wsdl"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
--- 1070,1075 ----
<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">
***************
*** 1119,1123 ****
<div2 id="adv-extensibility">
<head>Extensibility</head>
! <p>WSDL 2.0 provides two extensibility mechanisms: an open content model, which allows XML elements and attributes from other (non-wsdl) XML namespaces to be interspersed into a WSDL document; and <xspecref href="&w3c-designation-part1;#Feature">Features</xspecref> and <xspecref href="&w3c-designation-part1;#Property">Properties</xspecref>. Both mechanisms use URIs to identify the semantics of the extensions. For extension XML elements and attributes, the namespace URI of the extension element or attribute acts as an unambiguous name for the semantics of that extension. For Features and Properties, the Feature or Property is named by a URI.</p><p>In either case, the URI that identifies the semantics of an extension SHOULD be dereferenceable to a document that describes the semantics of that extension. As of this writing, there is no generally accepted standard for what kind of document that should be. However, the <loc href="http://www.w3.org/2001/tag/">W3C TAG</loc> has been discussing the issu (see TAG issue <loc href="http://www.w3.org/2001/tag/issues.html?type=1#namespaceDocument-8">namespaceDocument-8</loc>) and is likely to provide guidance at some point.</p><div3 id="adv-optional-versus-required"><head>Optional Versus Required Extensions</head><p>Extensions can either be required or optional: An <emph>optional</emph> extension is one that the requester agent may either engage or ignore, entirely at its discretion, and is signaled by attribute <code>wsdl:required="false"</code>; whereas a <emph>required</emph> extension is one that MUST be supported and engaged by the requester agent in order for the interaction to succeed properly, and is signaled by attribute <code>wsdl:required="true"</code>. </p><p>The optionality signaled by <code>wsdl:required="false"</code> pertains only to the <emph>requester</emph> agent -- not the provider agent. The provider agent MUST support both optional and required extensions that it advertises in its WSDL document. </p><p>A WSDL processor (acting to reaize a requester agent) need not support every conceivable required extension, but if it sees a required extension that it does not recognize or does not support, then it MUST fault. </p></div3><div3 id="adv-scope-of-wsdl-required"><head>Scoping of the wsdl:required Attribute</head><ednote><edtext>To do: Need to check the scoping rules to see if this is correct.</edtext></ednote><p>As a convenience mechanism, the <code>wsdl:required</code> attribute need not be specified on every extension element. If it is omitted from an extension element, its effective value is inherited from the smallest enclosing scope that explicitly sets its value. If there is no enclosing scope that explicitly sets its value, then its value defaults to <code>false</code>. </p><p>Because portions of a Web service description can be written in different physical documents by different people, one should be cautious about setting <code>wsdl:required="false"</code> when an outer scope, written by someone else, had set <code>wsdl:reuired="true"</code>.</p></div3></div2><div2 id="adv-FP">
<head>Features and Properties</head>
--- 1119,1123 ----
<div2 id="adv-extensibility">
<head>Extensibility</head>
! <p>WSDL 2.0 provides two extensibility mechanisms: an open content model, which allows XML elements and attributes from other (non-wsdl) XML namespaces to be interspersed into a WSDL document; and <xspecref href="&w3c-designation-part1;#Feature">Features</xspecref> and <xspecref href="&w3c-designation-part1;#Property">Properties</xspecref>. Both mechanisms use URIs to identify the semantics of the extensions. For extension XML elements and attributes, the namespace URI of the extension element or attribute acts as an unambiguous name for the semantics of that extension. For Features and Properties, the Feature or Property is named by a URI.</p><p>In either case, the URI that identifies the semantics of an extension SHOULD be dereferenceable to a document that describes the semantics of that extension. As of this writing, there is no generally accepted standard for what kind of document that should be. However, the <loc href="http://www.w3.org/2001/tag/">W3C TAG</loc> has been discussing the issu (see TAG issue <loc href="http://www.w3.org/2001/tag/issues.html?type=1#namespaceDocument-8">namespaceDocument-8</loc>) and is likely to provide guidance at some point.</p><div3 id="adv-optional-versus-required"><head>Optional Versus Required Extensions</head><p>Extensions can either be required or optional: An <emph>optional</emph> extension is one that the client may either engage or ignore, entirely at its discretion, and is signaled by attribute <code>wsdl:required="false"</code>; whereas a <emph>required</emph> extension is one that MUST be supported and engaged by the client in order for the interaction to succeed properly, and is signaled by attribute <code>wsdl:required="true"</code>. </p><p>The optionality signaled by <code>wsdl:required="false"</code> pertains only to the <emph>client</emph> -- not the service. The service MUST support both optional and required extensions that it advertises in its WSDL document. </p><p>A WSDL processor (acting to realize a client) need not support every coneivable required extension, but if it sees a required extension that it does not recognize or does not support, then it MUST fault. </p></div3><div3 id="adv-scope-of-wsdl-required"><head>Scoping of the wsdl:required Attribute</head><ednote><edtext>To do: Need to check the scoping rules to see if this is correct.</edtext></ednote><p>As a convenience mechanism, the <code>wsdl:required</code> attribute need not be specified on every extension element. If it is omitted from an extension element, its effective value is inherited from the smallest enclosing scope that explicitly sets its value. If there is no enclosing scope that explicitly sets its value, then its value defaults to <code>false</code>. </p><p>Because portions of a Web service description can be written in different physical documents by different people, one should be cautious about setting <code>wsdl:required="false"</code> when an outer scope, written by someone else, had set <code>wsdl:required="true"</code>.</p></div3></div2><div2 id="av-FP">
<head>Features and Properties</head>
Received on Friday, 18 February 2005 21:37:40 UTC