- From: Kevin Liu via cvs-syncmail <cvsmail@w3.org>
- Date: Tue, 08 Mar 2005 03:03:53 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20
In directory hutz:/tmp/cvs-serv8900/ws/desc/wsdl20
Modified Files:
wsdl20-primer.xml
Log Message:
Made the following edits per editor TODO's:
- fixed structure of the document by grouping Advanced Topics into two subsections
- changed the XML summary section, added diagram, reorganized the syntax summary, added the section for "order of wsdl elements and placement of extensions"
- other editorial changes
Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.31
retrieving revision 1.32
diff -C2 -d -r1.31 -r1.32
*** wsdl20-primer.xml 25 Feb 2005 20:05:52 -0000 1.31
--- wsdl20-primer.xml 8 Mar 2005 03:03:50 -0000 1.32
***************
*** 312,316 ****
. . .
</description>]]></eg>
! </example><div3 id="example-initial-binding-explanation"><head>Explanation of Example</head><glist><gitem><label><code>xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"</code></label><def><p>We've added two more namespace declarations. This one is the namespace for the SOAP 1.2 binding construct that is defined in WSDL 2.0 Part 3 <bibref ref="SOAP12-PART1"/>. Elements and attributes prefixed with <code>wsoap:</code> are constructs defined there. </p></def></gitem><gitem><label><code>xmlns:soap="http://www.w3.org/2003/05/soap-envelope"</code></label><def><p>This namespace is defined by the SOAP 1.2 specification itself. The SOAP 1.2 specification defines certain terms within this namespace to unambiguously identify particular concepts. Thus, we will use the <code>soap:</code> prefix when we need to refer to one of those terms.</p></def></gitem><gitem><label><code><binding name="reservationSOAPBinding"</code></label><def><p>Bindings are declared directly inside the <code>description</code>element. The <att>name</att> attribute defines a name for this binding. Each name must be unique among all bindings in this WSDL target namespace, and will be used later when we define a service endpoint that references this binding. WSDL 2.0 uses separate symbol spaces for interfaces, bindings and services, so interface "foo", binding "foo" and service "foo" are all distinct. </p></def></gitem><gitem><label><code>interface="tns:reservationInterface"</code></label><def><p>This is the name of the interface whose message format and transmission protocols we are specifying. As discussed in <specref ref="more-bindings"/>, a reusable binding can be defined by omitting the <att>interface</att> attribute. Note also the use of the <code>tns:</code> prefix, which refers to the previously defined WSDL target namespace for this WSDL document. In this case it may seem silly to have to specify the <code>tns:</code> prefix, but in <specref ref="adv-import-and-authoring"/>we will see how WSDL 2.0's import mechanismcan be used to combine components that are defined in different WSDL target namespaces.</p></def></gitem><gitem><label><code>type="http://www.w3.org/2004/08/wsdl/soap12"</code></label><def><p>This specifies the type of concrete message format to use, in this case SOAP 1.2.</p></def></gitem><gitem><label><code>wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP"</code></label><def><p>This attribute is specific to WSDL 2.0's SOAP binding (thus it uses the <code>wsoap:</code> prefix). It specifies the underlying transmission protocol that should be used, in this case HTTP. </p></def></gitem><gitem><label><code><operation ref="tns:opCheckAvailability"</code></label><def><p>This not defining a new operation. Rather, it is referencing the previously defined <code>opCheckAvailability</code> operation in order to specify binding details for it. This element can be omitted if defaulting rules are instead used to supply the necessary information. (See the SOAP binding in <emph>WSDL 2.0 Bindings</emh> <bibref ref="WSDL-PART3"/> section 2.3 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-bindings-20040803/#soap-defaults">Default Binding Rules</xspecref>.)</p></def></gitem><gitem><label><code>wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response"></code></label><def><p>This attribute is also specific to WSDL 2.0's SOAP binding. It specifies the SOAP message exchange pattern that will be used to implement the abstract WSDL 2.0 message exchange pattern (<xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref>) that was specified when the <code>opCheckAvailability</code> operation was defined. </p></def></gitem><gitem><label><code><fault ref="tns:invalidDataFault"</code></label><def><p>As with a binding operation, this is not declaring a new fault. Rather, it is referencing a fault (<code>invalidDataFault</code>) that was previously defined in the <code>opCheckAvailability</code> interface, in order to specify binding details for it.</p></de></gitem><gitem><label><code>wsoap:code="soap:Sender"/></code></label><def><p>This attribute is also specific to WSDL 2.0's SOAP binding. This specifies the SOAP 1.2 fault code that will cause this fault message to be sent. <ednote><edtext> Need to verify that this explanation is correct. See http://lists.w3.org/Archives/Public/public-ws-desc-comments/2004Dec/0003.html </edtext></ednote> If desired, an list of subcodes can also be specified using the optional <att>wsoap:subcodes</att> attribute.</p></def></gitem></glist></div3></div2><div2 id="basics-service"><head>Defining a Service</head><p>Now that our binding has specified <emph>how</emph> messages will be transmitted, we are ready to specify <emph>where</emph> the service can be accessed, by use of the <code>service</code> element. </p><p>A WSDL 2.0 <emph>service</emph> specifies a single interface that the service will support, and a list of <emph>endpoint</emph> locations where that service can be accessed. Each endpoint must also refeence a previously defined binding in order to indicate the binding details that are to be used at that endpoint. A service is only permitted to have one interface. (However, WSDL 2.0 does not prohibit one from declaring multiple services that use different interfaces but happen to use the same endpoint address. See <specref ref="adv-multiple-docs-describing-same-service"/>.) </p><p>Here is a definition for our GreatH service.</p><example id="example-initial-service">
<head>GreatH Service Definition</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
--- 312,316 ----
. . .
</description>]]></eg>
! </example><div3 id="example-initial-binding-explanation"><head>Explanation of Example</head><glist><gitem><label><code>xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"</code></label><def><p>We've added two more namespace declarations. This one is the namespace for the SOAP 1.2 binding construct that is defined in WSDL 2.0 Part 3 <bibref ref="SOAP12-PART1"/>. Elements and attributes prefixed with <code>wsoap:</code> are constructs defined there. </p></def></gitem><gitem><label><code>xmlns:soap="http://www.w3.org/2003/05/soap-envelope"</code></label><def><p>This namespace is defined by the SOAP 1.2 specification itself. The SOAP 1.2 specification defines certain terms within this namespace to unambiguously identify particular concepts. Thus, we will use the <code>soap:</code> prefix when we need to refer to one of those terms.</p></def></gitem><gitem><label><code><binding name="reservationSOAPBinding"</code></label><def><p>Bindings are declared directly inside the <code>description</code>element. The <att>name</att> attribute defines a name for this binding. Each name must be unique among all bindings in this WSDL target namespace, and will be used later when we define a service endpoint that references this binding. WSDL 2.0 uses separate symbol spaces for interfaces, bindings and services, so interface "foo", binding "foo" and service "foo" are all distinct. </p></def></gitem><gitem><label><code>interface="tns:reservationInterface"</code></label><def><p>This is the name of the interface whose message format and transmission protocols we are specifying. As discussed in <specref ref="more-bindings"/>, a reusable binding can be defined by omitting the <att>interface</att> attribute. Note also the use of the <code>tns:</code> prefix, which refers to the previously defined WSDL target namespace for this WSDL document. In this case it may seem silly to have to specify the <code>tns:</code> prefix, but in <specref ref="adv-import-and-authoring"/>we will see how WSDL 2.0's import mechanismcan be used to combine components that are defined in different WSDL target namespaces.</p></def></gitem><gitem><label><code>type="http://www.w3.org/2004/08/wsdl/soap12"</code></label><def><p>This specifies the type of concrete message format to use, in this case SOAP 1.2.</p></def></gitem><gitem><label><code>wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP"</code></label><def><p>This attribute is specific to WSDL 2.0's SOAP binding (thus it uses the <code>wsoap:</code> prefix). It specifies the underlying transmission protocol that should be used, in this case HTTP. </p></def></gitem><gitem><label><code><operation ref="tns:opCheckAvailability"</code></label><def><p>This not defining a new operation. Rather, it is referencing the previously defined <code>opCheckAvailability</code> operation in order to specify binding details for it. This element can be omitted if defaulting rules are instead used to supply the necessary information. (See the SOAP binding in <emph>WSDL 2.0 Bindings</emh> <bibref ref="WSDL-PART3"/> section 2.3 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-bindings-20040803/#soap-defaults">Default Binding Rules</xspecref>.)</p></def></gitem><gitem><label><code>wsoap:mep="http://www.w3.org/2003/05/soap/mep/request-response"></code></label><def><p>This attribute is also specific to WSDL 2.0's SOAP binding. It specifies the SOAP message exchange pattern that will be used to implement the abstract WSDL 2.0 message exchange pattern (<xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref>) that was specified when the <code>opCheckAvailability</code> operation was defined. </p></def></gitem><gitem><label><code><fault ref="tns:invalidDataFault"</code></label><def><p>As with a binding operation, this is not declaring a new fault. Rather, it is referencing a fault (<code>invalidDataFault</code>) that was previously defined in the <code>opCheckAvailability</code> interface, in order to specify binding details for it.</p></de></gitem><gitem><label><code>wsoap:code="soap:Sender"/></code></label><def><p>This attribute is also specific to WSDL 2.0's SOAP binding. This specifies the SOAP 1.2 fault code that will cause this fault message to be sent. If desired, an list of subcodes can also be specified using the optional <att>wsoap:subcodes</att> attribute.</p></def></gitem></glist></div3></div2><div2 id="basics-service"><head>Defining a Service</head><p>Now that our binding has specified <emph>how</emph> messages will be transmitted, we are ready to specify <emph>where</emph> the service can be accessed, by use of the <code>service</code> element. </p><p>A WSDL 2.0 <emph>service</emph> specifies a single interface that the service will support, and a list of <emph>endpoint</emph> locations where that service can be accessed. Each endpoint must also reference a previously defined binding in order to indicate the binding details that are to be used at that endpoint. A service is only permitted to have one interface. (However, WSDL 2.0 does not prohibit one from declaring multiple services that use different interfaces but happen to use the same endpoint address. See <specref ref="adv-multiple-docs-describing-same-service"/>.) </p><p>Here is a definition for our GreatH service.</p><example id="example-initial-service">
<head>GreatH Service Definition</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
***************
*** 365,369 ****
. . .
</description>]]></eg>
! </example><div3 id="example-initial-documentation-explanation"><head>Explanation of Example</head><glist><gitem><label><code><documentation></code></label><def><p> This element is optional, but a good idea to include. It can contain arbitrary mixed content. </p></def></gitem><gitem><label><code>at http://greath.example.com/2004/reservation-documentation.html</code></label><def><p>The most important thing to include is a pointer to any additional documentation that a client developer would need in order to use the service. </p></def></gitem></glist><p>This completes our presentation of the GreatH example. Let's summarize the syntax we've seen. </p></div3></div2><div2 id="basics-syntax"><head>XML Syntax Summary</head><p>In the core language specification, WSDL 2.0 constructs are defined as a set of abstract components, along with a mapping to an XML infoset representation for these components. For easier consumption, the primer uses the XML representation of WSDL components. The following onventions are followed for the syntax: </p>
<ulist>
<item>
--- 365,392 ----
. . .
</description>]]></eg>
! </example>
!
! <div3 id="example-initial-documentation-explanation"><head>Explanation of Example</head><glist><gitem><label><code><documentation></code></label><def><p> This element is optional, but a good idea to include. It can contain arbitrary mixed content. </p></def></gitem><gitem><label><code>at http://greath.example.com/2004/reservation-documentation.html</code></label><def><p>The most important thing to include is a pointer to any additional documentation that a client developer would need in order to use the service. </p></def></gitem></glist><p>This completes our presentation of the GreatH example. </p></div3></div2>
! </div1>
!
! <div1 id="wsdl-xml-representation"><head>WSDL 2.0 XML Representation</head>
!
! <p>In the core language specification, WSDL 2.0 constructs are defined as a set of abstract components, along with a mapping to an XML infoset representation for these components. For easier consumption, the primer uses the XML representation of WSDL components.</p>
!
! <div2 id="wsdl-infoset-diagram"><head>WSDL2.0 Infoset Model Overview</head>
!
! <p>The following diagram gives an overview of a WSDL2.0 XML Infoset.
!
! <graphic source="images/WSDL20ComponentModel.gif" alt="WSDL 2.0 Infoset Diagram"/>
!
! </p>
!
! <p>A WSDL Infoset contains representations for a collection of WSDL components which share a common target namespace. Note that WSDL definitions may be represented by one or more WSDL Infosets, that is one or more <el>description</el> elements which all share a common target namespace. When a WSDL Infoset contains one or more <el>import</el> elements, the WSDL definition corresponds to a collection with components drawn from multiple target namespaces.</p>
!
! </div2>
!
! <div2 id="wsdl-xml-syntax"><head>WSDL2.0 XML Syntax Summary</head>
!
! <p>The XML syntax of the infoset model is summarized below. The following conventions are followed for the syntax: </p>
<ulist>
<item>
***************
*** 378,525 ****
</ulist>
! <ednote><name>dbooth</name><edtext>To do: check the above elipses (...), as they weren't rendering properly at one point.</edtext></ednote><div3 id="basics-syntax-brief"><head>Brief Syntax Summary</head><ednote><edtext>To do: Insert short summary here</edtext></ednote></div3><div3 id="basics-syntax-longer"><head>Longer Syntax Summary</head><ednote><name>dbooth</name><edtext>To do: Update this, and delete the <documentation>, <feature> and <property> elements, because they're mentioned below.</edtext></ednote><eg xml:space="preserve">
! <description targetNamespace="<emph>xs:anyURI</emph>" >
! <documentation />?
!
! <import namespace="<emph>xs:anyURI</emph>" location="<emph>xs:anyURI</emph>"? >
! <documentation />?
! </import>*
!
! <include location="<emph>xs:anyURI</emph>" >
! <documentation />?
! </include>*
!
! <types>
! <documentation />?
! </types>
!
! <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>*
<binding name="<emph>xs:NCName</emph>" interface="<emph>xs:QName</emph>"? type="<emph>xs:anyURI</emph>" >
- <documentation />?
! <fault ref="<emph>xs:QName</emph>" >
! <documentation />?
! <feature ... />*
! <property ... />*
! </fault>*
! <operation ref="<emph>xs:QName</emph>" >
! <documentation />?
! <input messageLabel="<emph>xs:NCName</emph>"? >
! <documentation />?
! <feature ... />*
! <property ... />*
! </input>*
! <output messageLabel="<emph>xs:NCName</emph>"? >
! <documentation />?
! <feature ... />*
! <property ... />*
! </output>*
! <feature ... />*
! <property ... />*
! </operation>*
! <feature ... />*
! <property ... />*
! </binding>*
! <service name="<emph>xs:NCName</emph>" interface="<emph>xs:QName</emph>" >
! <documentation />?
! <endpoint name="<emph>xs:NCName</emph>" binding="<emph>xs:QName</emph>" address="<emph>xs:anyURI</emph>"? >
! <documentation />?
! <feature ... />*
! <property ... />*
! </endpoint>*
! <feature ... />*
! <property ... />*
! </service>*
! </description>
! </eg>
!
! <p>In addition, <code>feature</code> and <code>property</code> elements are allowed inside most WSDL elements. Also, an optional <code>documentation</code> element is allowed inside any WSDL element as a container for human readable and/or machine processable documentation. The content of <code>documentation</code> is arbitrary characters and elements
! ("mixed" content in XML Schema). </p></div3></div2></div1>
<!-- ******************MessageTypes********************************** -->
<!-- ******************MessageTypes********************************** -->
! <div1 id="more-types"><head>More on Message Types</head><div2 id="more-types-schema">
<head>Defining Messages Using XML Schema</head>
--- 401,569 ----
</ulist>
! <!-- ednote><name>dbooth</name><edtext>To do: check the above elipses (...), as they weren't rendering properly at one point.</edtext></ednote -->
! <!--div3 id="basics-syntax-brief"><head>Brief Syntax Summary</head><ednote><edtext>To do: Insert short summary here</edtext></ednote></div3>
! </div3>
! <div3 id="basics-syntax-longer">
! <head>Longer Syntax Summary</head -->
! <eg xml:space="preserve">
! <description targetNamespace="<emph>xs:anyURI</emph>" >
! <import namespace="<emph>xs:anyURI</emph>" location="<emph>xs:anyURI</emph>"?/>*
! <include location="<emph>xs:anyURI</emph>"/>*
! <types/>
! <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>"?/>*
! <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>"? />*
!
! <output messageLabel="<emph>xs:NCName</emph>"? element="<emph>union of xs:QName, xs:Token</emph>"? />*
! <infault ref="<emph>xs:QName</emph>" messageLabel="<emph>xs:NCName</emph>"? />*
! <outfault ref="<emph>xs:QName</emph>" messageLabel="<emph>xs:NCName</emph>"? />*
</operation>*
</interface>*
<binding name="<emph>xs:NCName</emph>" interface="<emph>xs:QName</emph>"? type="<emph>xs:anyURI</emph>" >
! <fault ref="<emph>xs:QName</emph>" />*
! <operation ref="<emph>xs:QName</emph>" >
! <input messageLabel="<emph>xs:NCName</emph>"? />*
!
! <output messageLabel="<emph>xs:NCName</emph>"? />*
! </operation>*
! </binding>*
! <service name="<emph>xs:NCName</emph>" interface="<emph>xs:QName</emph>" >
! <endpoint name="<emph>xs:NCName</emph>" binding="<emph>xs:QName</emph>" address="<emph>xs:anyURI</emph>"? />*
! </service>*
! </description>
! </eg>
!
! <p>In addition, <code>feature</code> and <code>property</code> elements are allowed inside all WSDL elements except <code>import</code>, <code>include</code>, and <code>types</code>. Also, an optional <code>documentation</code> element is allowed as the first child of any WSDL element as a container for human readable and/or machine processable documentation. The content of <code>documentation</code> is arbitrary characters and elements
! ("mixed" content in XML Schema). </p>
! </div2>
! <div2 id="wsdl-element-order">
! <head>Order of WSDL elements and placement of extensions</head>
! <p>The order of the WSDL2.0 elmenets matters. As specified in part 1 section 2.1.2, the children elements of the <code>description</code> element should be ordered as follows: </p>
! <eg xml:space="preserve">
! <<b>description</b>>
! <documentation />?
! [ <import /> | <include /> ]*
! <types />?
! [ <interface /> | <binding /> | <service /> ]*
! </<b>description</b>>
! </eg>
!
! <p></p>
! In other words,
! <ulist>
! <item>
! <p>
! An optoinal <el>documentation</el> comes first, if presents.
! </p>
! </item>
! <item>
! <p>then comes zero or more elements from among the following, in any
! order:
! </p>
! <ulist>
! <item>
! <p>
! Zero or more <el>include</el>
! </p>
! </item>
! <item>
! <p>
! Zero or more <el>import</el>
! </p>
! </item>
! <item>
! <p>
! Zero or more extensions
! </p>
! </item>
! </ulist>
! </item>
! <item>
! <p>
! An optional <el>types</el> follows
! </p>
! </item>
! <item>
! <p>
! Zero or more elements from among the following, in any
! order:
! </p>
! <ulist>
! <item>
! <p>
! <el>interface</el> elements
! </p>
! </item>
! <item>
! <p>
! <el>binding</el> elements
! </p>
! </item>
! <item>
! <p>
! <el>service</el> elements
! </p>
! </item>
! <item>
! <p>
! Zero or more extensions.
! </p>
! </item>
! </ulist>
! </item>
!
! </ulist>
! Note the term "extension" is used above as a convenient way to refer to namespace-qualified extension elements. The namespace name of such extension elements must not be<attval>&wsdl-ns;</attval>.
! </div2>
! </div1>
!
!
! <div1 id="advanced-topic-i"><head>Advanced Topic I: More on Message Types, Interfaces, Bindings, and Services</head>
<!-- ******************MessageTypes********************************** -->
<!-- ******************MessageTypes********************************** -->
! <div2 id="more-types"><head>More on Message Types</head>
! <div3 id="more-types-schema">
<head>Defining Messages Using XML Schema</head>
***************
*** 542,546 ****
<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 <code>import</code> 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 <code>xs:include</code> are available to WSDL. Specifically, components that the schema imports via <code>xs:import</code> 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>
--- 586,590 ----
<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>
! <div4 id="more-types-schema-import">
<head>Importing XML Schema</head>
<p>Let's examine the XML Schema <code>import</code> 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 <code>xs:include</code> are available to WSDL. Specifically, components that the schema imports via <code>xs:import</code> 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>
***************
*** 557,562 ****
</item>
</ulist>
! </div3>
! <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 <code>xs:schema</code> element defined by XML Schema <bibref ref="XMLSchemaP1"/> to do so. This is comparable to simply cutting and pasting an
--- 601,606 ----
</item>
</ulist>
! </div4>
! <div4 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 <code>xs:schema</code> element defined by XML Schema <bibref ref="XMLSchemaP1"/> to do so. This is comparable to simply cutting and pasting an
***************
*** 625,634 ****
</example>
! </div3>
! </div2></div1><!-- ******************Interface********************************** --><!-- ******************Interface********************************** --><div1 id="more-interfaces">
<head>More on Interfaces</head>
<!-- ************************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>
<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>
--- 669,684 ----
</example>
! </div4>
! </div3>
! </div2>
!
! <!-- ******************Interface********************************** -->
! <!-- ******************Interface********************************** -->
! <div2 id="more-interfaces">
<head>More on Interfaces</head>
<!-- ************************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>
! <div3 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>
***************
*** 706,710 ****
<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 (Component Equivalence is defined in Part 1 section 2.15 Equivalence of Components. For operations, basically equivalence means the two operations in quesion have 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>
--- 756,760 ----
<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>
! <div4 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 (Component Equivalence is defined in Part 1 section 2.15 Equivalence of Components. For operations, basically equivalence means the two operations in quesion have 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>
***************
*** 719,724 ****
<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>
--- 769,774 ----
<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>
! </div4>
! <div4 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>
***************
*** 779,784 ****
</edtext>
</ednote>
! </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>
--- 829,834 ----
</edtext>
</ednote>
! </div4>
! <div4 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>
***************
*** 874,883 ****
<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>
--- 924,933 ----
<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>
! </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>
***************
*** 948,955 ****
! </div2></div1>
<!-- **********************************Binding************************** -->
<!-- **********************************Binding************************** -->
! <div1 id="more-bindings">
<head>More on Bindings</head>
--- 998,1005 ----
! </div3></div2>
<!-- **********************************Binding************************** -->
<!-- **********************************Binding************************** -->
! <div2 id="more-bindings">
<head>More on Bindings</head>
***************
*** 973,977 ****
defining bindings for them. Thus, it is an error for a binding to not define bindings for all the operations of the corresponding interface.</p>
<p>The binding constructs can be grouped into two categories: those in the WSDL namespace of "http://www.w3.org/2004/08/wsdl" and those not in WSDL namespace. WSDL 2.0 part 1 defines a set of binding constructs within the WSDL namespace that can be used to host binding detail definitions. Constructs for defining binding details are defined within their own namespaces which must be different from the WSDL namespace. ll these binding detail constructs are defined outside WSDL namespace, and are typically used as extensions of the hosting WSDL binding constructs. In the following sections, we will introduce the hosting WSDL binding constructs first, and then move on the the binding extensions.
! </p><div2 id="more-bindings-wsdl">
<head>Binding Constructs in WSDL Namespace</head>
<p>Let's have a look at the constructs defined within the WSDL namespace first. The XML syntax of these constructs is summarized below:</p>
--- 1023,1027 ----
defining bindings for them. Thus, it is an error for a binding to not define bindings for all the operations of the corresponding interface.</p>
<p>The binding constructs can be grouped into two categories: those in the WSDL namespace of "http://www.w3.org/2004/08/wsdl" and those not in WSDL namespace. WSDL 2.0 part 1 defines a set of binding constructs within the WSDL namespace that can be used to host binding detail definitions. Constructs for defining binding details are defined within their own namespaces which must be different from the WSDL namespace. ll these binding detail constructs are defined outside WSDL namespace, and are typically used as extensions of the hosting WSDL binding constructs. In the following sections, we will introduce the hosting WSDL binding constructs first, and then move on the the binding extensions.
! </p><div3 id="more-bindings-wsdl">
<head>Binding Constructs in WSDL Namespace</head>
<p>Let's have a look at the constructs defined within the WSDL namespace first. The XML syntax of these constructs is summarized below:</p>
***************
*** 1019,1023 ****
<p>The <code>binding</code> element has a required <att>name</att> attribute. Within the same WSDL target namespace , each binding must have a unique name. The optional <att>interface</att> attribute refers, by QName, to an <code>interface</code>. See the previous section for how the <att>interface</att>attribute can be used to achieve different levels of reusability of the <code>binding</code>. </p>
<p>Careful readers may have already noticed that the <code>binding</code> syntax is to some extent symmetric with the syntax of <code>interface</code>, in other words, each interface construct has a binding counterpart. Simliar to <code>interface</code>,a <code>binding</code> element 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>. Be aware that despite of the syntax similarity, they are indeed different constructs since they are in different symbol spaces and are designed for different purpose. The <code>feature</code> and <code>property</code> element will be examined in section @@@@. We will explain the binding <code>fault</code> and <code>operation</code> constructs in the following sections. </p>
! <div3 id="more-bindings-faults">
<head>Binding Faults</head>
<p>A binding <code>fault</code> describes a concrete binding of an abstract fault
--- 1069,1073 ----
<p>The <code>binding</code> element has a required <att>name</att> attribute. Within the same WSDL target namespace , each binding must have a unique name. The optional <att>interface</att> attribute refers, by QName, to an <code>interface</code>. See the previous section for how the <att>interface</att>attribute can be used to achieve different levels of reusability of the <code>binding</code>. </p>
<p>Careful readers may have already noticed that the <code>binding</code> syntax is to some extent symmetric with the syntax of <code>interface</code>, in other words, each interface construct has a binding counterpart. Simliar to <code>interface</code>,a <code>binding</code> element 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>. Be aware that despite of the syntax similarity, they are indeed different constructs since they are in different symbol spaces and are designed for different purpose. The <code>feature</code> and <code>property</code> element will be examined in section @@@@. We will explain the binding <code>fault</code> and <code>operation</code> constructs in the following sections. </p>
! <div4 id="more-bindings-faults">
<head>Binding Faults</head>
<p>A binding <code>fault</code> describes a concrete binding of an abstract fault
***************
*** 1028,1033 ****
<att>fault</att>. It identifies the abstract interface <code>fault</code> for which binding information is being specified. Be aware that the value of <att>ref</att> attribute of all the <code>faults</code> under a <code>binding</code>
MUST be unique. That is, one cannot define multiple bindings for the same interface fault within a given <code>binding</code>.</p>
! </div3>
! <div3 id="bindingOperations">
<head id="more-bindings-operations">Binding Operations</head>
<p>A binding <code>operation</code> describes a concrete binding of a particular
--- 1078,1083 ----
<att>fault</att>. It identifies the abstract interface <code>fault</code> for which binding information is being specified. Be aware that the value of <att>ref</att> attribute of all the <code>faults</code> under a <code>binding</code>
MUST be unique. That is, one cannot define multiple bindings for the same interface fault within a given <code>binding</code>.</p>
! </div4>
! <div4 id="bindingOperations">
<head id="more-bindings-operations">Binding Operations</head>
<p>A binding <code>operation</code> describes a concrete binding of a particular
***************
*** 1046,1052 ****
</ednote>
<p>Corresponding to its interface <code>operation</code> counterpart, binding <code>operation</code> may also have zero or more <code>input</code>,<code>output</code>, <code>infault</code>, and/or <code>outfault</code>. The presence or absence of these message and/or fault reference constructs within a particular binding <code>operation</code> is governed by the interface <code>operation</code> counterpart.</p>
! </div3>
! </div2>
! <div2 id="more-bindings-soap">
<head>Extensions for SOAP Binding</head>
<example id="example-binding-soap">
--- 1096,1102 ----
</ednote>
<p>Corresponding to its interface <code>operation</code> counterpart, binding <code>operation</code> may also have zero or more <code>input</code>,<code>output</code>, <code>infault</code>, and/or <code>outfault</code>. The presence or absence of these message and/or fault reference constructs within a particular binding <code>operation</code> is governed by the interface <code>operation</code> counterpart.</p>
! </div4>
! </div3>
! <div3 id="more-bindings-soap">
<head>Extensions for SOAP Binding</head>
<example id="example-binding-soap">
***************
*** 1063,1068 ****
</eg>
</example>
! </div2>
! <div2 id="more-bindings-http">
<head>Extensions for HTTP Binding</head>
<example id="example-bindings-http">
--- 1113,1118 ----
</eg>
</example>
! </div3>
! <div3 id="more-bindings-http">
<head>Extensions for HTTP Binding</head>
<example id="example-bindings-http">
***************
*** 1078,1086 ****
</eg>
</example>
! </div2>
! </div1>
<!-- **********************************Service************************** -->
<!-- **********************************Service************************** -->
! <div1 id="more-service">
<head>More on Service Endpoints </head>
<ednote><name>dbooth</name><edtext>This section now seems largely redundant. Perhaps we should reduce or eliminate it.</edtext></ednote><p>As described previously, the <code>service</code> construct specifies a set of alternate endpoints at which a service is available. Zero or more <code>services</code> can be defined within a <code>description</code> element. However, each service is limited to a single interface. The XML syntax of <code>service</code> is summarized below:</p>
--- 1128,1136 ----
</eg>
</example>
! </div3>
! </div2>
<!-- **********************************Service************************** -->
<!-- **********************************Service************************** -->
! <div2 id="more-service">
<head>More on Service Endpoints </head>
<ednote><name>dbooth</name><edtext>This section now seems largely redundant. Perhaps we should reduce or eliminate it.</edtext></ednote><p>As described previously, the <code>service</code> construct specifies a set of alternate endpoints at which a service is available. Zero or more <code>services</code> can be defined within a <code>description</code> element. However, each service is limited to a single interface. The XML syntax of <code>service</code> is summarized below:</p>
***************
*** 1104,1112 ****
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 <code>endpoint</code> 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 <code>endpoint</code>. </p>
! </div1>
<!-- **********************************AdvancedTopics***************** -->
<!-- **********************************AdvancedTopics***************** -->
! <div1 id="advanced">
! <head>Advanced Topics - TBD</head>
<ednote>
<name>KevinL</name>
--- 1154,1165 ----
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 <code>endpoint</code> 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 <code>endpoint</code>. </p>
! </div2>
!
! </div1>
!
<!-- **********************************AdvancedTopics***************** -->
<!-- **********************************AdvancedTopics***************** -->
! <div1 id="advanced-topic_ii">
! <head>Advanced Topics II - TBD</head>
<ednote>
<name>KevinL</name>
Received on Tuesday, 8 March 2005 03:03:53 UTC