- From: David Booth via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 13 Apr 2005 20:19:46 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20
In directory hutz:/tmp/cvs-serv11966
Modified Files:
wsdl20-primer.xml wsdl20-primer.html
Log Message:
Finished editing/updating section 4. Also collapsed a level of hierarchy in section 4, so the previous
subsections on Message Types, Interfaces, Bindings and Services
are now div1 sections. Thus, the previous "Advanced Topics I" header
is gone, and "Advanced Topics II" is now merely "Advanced Topics".
Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.45
retrieving revision 1.46
diff -C2 -d -r1.45 -r1.46
*** wsdl20-primer.xml 13 Apr 2005 04:40:45 -0000 1.45
--- wsdl20-primer.xml 13 Apr 2005 20:19:44 -0000 1.46
***************
*** 202,206 ****
</description>]]></eg>
! </example></div2><div2 id="basics-getting-started"><head>Getting Started: Defining a WSDL Target Namespace</head><p>Before writing our WSDL 2.0 document, we need to decide on a <emph>WSDL target namespace</emph> URI for it. The WSDL target namespace is analogous to an XML Schema target namespace: interface, binding and service names that we define in our WSDL document will be associated with the WSDL target namespace, and thus will be distinguishable from similar names in a different WSDL target namespace. (This will become important if using WSDL 2.0's import or interface inheritance mechanisms.) </p><p>The value of the WSDL target namespace MUST be an absolute URI. Furthermore, it SHOULD be dereferenceable to a WSDL document that describes the Web service that the WSDL target namespace is used to describe. For example, the GreatH owners SHOULD make the WSDL document available from this URI. (And if a WSDL description is split into multiple documents, then the WSDL target namespace should reslve to a master document that includes all the WSDL documents needed for that service description.) However, there is no absolute requirement for this URI to be dereferenceable, so a WSDL processor must not depend on it being dereferenceable. </p><p>This recommendation may sound circular, but bear in mind that the client might have obtained the WSDL document from anywhere -- not necessarily an authoritative source. But by dereferencing the WSDL target namespace URI, a user SHOULD be able to obtain an authoritative version. Since GreatH will be the owner of the service, the WSDL target namespace URI should refer to a location on the GreatH Web site or otherwise within its control.</p><p>Once we have decided on a WSDL target namespace URI, we can begin our WSDL 2.0 document as the following empty shell.</p><example id="example-empty-shell">
<head>An Initial Empty WSDL Document</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
--- 202,207 ----
</description>]]></eg>
! </example><ednote><name>dbooth</name><date>205-04-12</date><edtext>ToDo: Make opCheckAvailability use GET instead of POST,
! and set the safe="true" on it.</edtext></ednote><ednote><name>dbooth</name><date>2005-04-12</date><edtext>ToDo: Should we add line numbers to the examples, to make it clearer in the explanations when we refer to specific portions? I think this may be helpful. If so, we should: 1. Add them to the complete example above; 2. When showing excerpts, use the same line numbers from the complete example above (for consistency); 3. Explain that the line numbers are not a part of the XML or WSDL 2.0 document, but are merely shown in this primer for ease of reference.</edtext></ednote></div2><div2 id="basics-getting-started"><head>Getting Started: Defining a WSDL Target Namespace</head><p>Before writing our WSDL 2.0 document, we need to decide on a <emph>WSDL target namespace</emph> URI for it. The WSDL target namespace is analogous to an XML Schema target namespace: interface, binding and service names that we define in our WSDL document will be associated with the WSDL target namespace, and thus will be distingishable from similar names in a different WSDL target namespace. (This will become important if using WSDL 2.0's import or interface inheritance mechanisms.) </p><p>The value of the WSDL target namespace MUST be an absolute URI. Furthermore, it SHOULD be dereferenceable to a WSDL document that describes the Web service that the WSDL target namespace is used to describe. For example, the GreatH owners SHOULD make the WSDL document available from this URI. (And if a WSDL description is split into multiple documents, then the WSDL target namespace should resolve to a master document that includes all the WSDL documents needed for that service description.) However, there is no absolute requirement for this URI to be dereferenceable, so a WSDL processor must not depend on it being dereferenceable. </p><p>This recommendation may sound circular, but bear in mind that the client might have obtained the WSDL document from anywhere -- not necessarily an authoritative source. But by dereferencing the WSDL trget namespace URI, a user SHOULD be able to obtain an authoritative version. Since GreatH will be the owner of the service, the WSDL target namespace URI should refer to a location on the GreatH Web site or otherwise within its control.</p><p>Once we have decided on a WSDL target namespace URI, we can begin our WSDL 2.0 document as the following empty shell.</p><example id="example-empty-shell">
<head>An Initial Empty WSDL Document</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
***************
*** 328,339 ****
Part 2: Adjuncts
</emph>
! <bibref ref="WSDL-PART2"/>
! , section 4.3
! <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-adjuncts/#soap-defaults">
! Default Binding Rules
! </xspecref>
! .)
</p>
! <p>In order to accommodate new kinds of message formats and transmission protocols, bindings are defined using extensions to the WSDL 2.0 language, via WSDL 2.0's open content model. (See <specref ref="adv-extensibility"/> for more on extensibility.) WSDL 2.0 Part 3 defines binding constructs for SOAP 1.2 <bibref ref="SOAP12-PART1"/> and HTTP 1.1 <bibref ref="RFC2616"/> as predefined extensions, so that SOAP 1.2 or HTTP 1.1 bindings can be easily defined in WSDL documents. However, other specifications could define new binding constructs that could also be used to define bindings. (As with any extension, other WSDL processors would have to know about the new constructs in order to make use of them.) </p><p>For the GreatH service, we will use SOAP 1.2 as our concrete message format and HTTP as our underlying transmission protocol, as shown below. </p><example id="example-initial-binding">
<head>GreatH Binding Definition</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
--- 329,335 ----
Part 2: Adjuncts
</emph>
! <bibref ref="WSDL-PART2"/>, <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-adjuncts/#soap-defaults">Default Binding Rules</xspecref>.)
</p>
! <p>In order to accommodate new kinds of message formats and transmission protocols, bindings are defined using extensions to the WSDL 2.0 language, via WSDL 2.0's open content model. (See <specref ref="adv-extensibility"/> for more on extensibility.) WSDL 2.0 Part 3 <bibref ref="WSDL-PART3"/> defines binding constructs for SOAP 1.2 <bibref ref="SOAP12-PART1"/> and HTTP 1.1 <bibref ref="RFC2616"/> as predefined extensions, so that SOAP 1.2 or HTTP 1.1 bindings can be easily defined in WSDL documents. However, other specifications could define new binding constructs that could also be used to define bindings. (As with any extension, other WSDL processors would have to know about the new constructs in order to make use of them.) </p><p>For the GreatH service, we will use SOAP 1.2 as our concrete message format and HTTP as our underlying transmission protocol, as shown below. </p><example id="example-initial-binding">
<head>GreatH Binding Definition</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
***************
*** 451,459 ****
</div1>
! <div1 id="wsdl-xml-representation"><head>WSDL 2.0 XML Infoset and Component Model</head>
<p>In conventional computer science theory, a language consists of a (possibly infinite) set of sentences, and each sentence is a string of literal symbols or characters. The language specification must therefore define two things: the set of permissible sentences, and the meaning of each sentence. Indeed, this is the purpose of the WSDL 2.0 specification.</p><p>However, instead of defining WSDL 2.0 in terms of literal symbols or characters, to avoid dependency on any particular character encoding, WSDL 2.0 is defined in terms of the <emph>XML Infoset</emph> <bibref ref="XMLInfoSet"/>. Specifically, a <emph>WSDL 2.0 document</emph> consists of a <code>description</code> element information item (in the XML Infoset) that conforms to the WSDL 2.0 specification. In other words, a sentence in the WSDL 2.0 language is a <code>description</code> element information item that obeys the additional constraints spelled out in the WSDL 2.0 specification.</p><p>Since an XML Infoset can be created from morethan one physical document, a WSDL 2.0 document does not necessarily correspond to a single physical document: the word "document" is used figuratively, for convenience. Furthermore, since WSDL 2.0 provides <code>import</code> and <code>include</code> mechanisms, a WSDL 2.0 document may reference other WSDL 2.0 documents to facilitate convenient organization or reuse. </p><p>Unfortunately, the terms "element information item" and "attribute information item" are rather lengthy. Thus, for convenience, this primer often uses the terms "element" and "attribute" instead, as a shorthand. It should be understood, however, that since WSDL 2.0 is based on the XML Infoset, we really mean "element information item" and "attribute information item", respectively.</p>
! <div2 id="wsdl-infoset-diagram"><head>WSDL 2.0 Infoset Model Overview</head>
<p>The following diagram gives an overview of the XML Infoset for a WSDL 2.0 document.
--- 447,455 ----
</div1>
! <div1 id="wsdl-xml-representation"><head>WSDL 2.0 Infoset, Schema and Component Model</head>
<p>In conventional computer science theory, a language consists of a (possibly infinite) set of sentences, and each sentence is a string of literal symbols or characters. The language specification must therefore define two things: the set of permissible sentences, and the meaning of each sentence. Indeed, this is the purpose of the WSDL 2.0 specification.</p><p>However, instead of defining WSDL 2.0 in terms of literal symbols or characters, to avoid dependency on any particular character encoding, WSDL 2.0 is defined in terms of the <emph>XML Infoset</emph> <bibref ref="XMLInfoSet"/>. Specifically, a <emph>WSDL 2.0 document</emph> consists of a <code>description</code> element information item (in the XML Infoset) that conforms to the WSDL 2.0 specification. In other words, a sentence in the WSDL 2.0 language is a <code>description</code> element information item that obeys the additional constraints spelled out in the WSDL 2.0 specification.</p><p>Since an XML Infoset can be created from morethan one physical document, a WSDL 2.0 document does not necessarily correspond to a single physical document: the word "document" is used figuratively, for convenience. Furthermore, since WSDL 2.0 provides <code>import</code> and <code>include</code> mechanisms, a WSDL 2.0 document may reference other WSDL 2.0 documents to facilitate convenient organization or reuse. </p><p>Unfortunately, the terms "element information item" and "attribute information item" are rather lengthy. Thus, for convenience, this primer often uses the terms "element" and "attribute" instead, as a shorthand. It should be understood, however, that since WSDL 2.0 is based on the XML Infoset, we really mean "element information item" and "attribute information item", respectively.</p>
! <div2 id="wsdl-infoset-diagram"><head>WSDL 2.0 Infoset</head>
<p>The following diagram gives an overview of the XML Infoset for a WSDL 2.0 document.
***************
*** 472,476 ****
<head>WSDL 2.0 Schema and Element Ordering</head>
! <p>The WSDL 2.0 specification supplies a normative WSDL 2.0 schema @@ToDo: Add reference@@, defined in XML Schema, which can be used as an aid in validating WSDL 2.0 documents. Although the WSDL 2.0 schema does not indicate the required ordering of elements, the WSDL 2.0 specification (Part 1 section 2.1.2) clearly states a set of constraints about how the children elements of the <code>description</code> element should be ordered. Thus, the order of the WSDL 2.0 elements matters, in spite of what the WSDL 2.0 schema says. </p><p>The following is a pseudo-content model of <code>description</code>.</p>
<eg xml:space="preserve">
--- 468,472 ----
<head>WSDL 2.0 Schema and Element Ordering</head>
! <p>The WSDL 2.0 specification supplies a normative WSDL 2.0 schema @@ToDo: Add reference@@, defined in XML Schema <bibref ref="XMLSchemaP1"/> <bibref ref="XMLSchemaP2"/>, which can be used as an aid in validating WSDL 2.0 documents. Although the WSDL 2.0 schema does not indicate the required ordering of elements, the WSDL 2.0 specification (WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> "<xspecref href="http://www.w3.org/TR/wsdl20-primer#Description_XMLRep">XML Representation of Description Component</xspecref>") clearly states a set of constraints about how the children elements of the <code>description</code> element should be ordered. Thus, the order of the WSDL 2.0 elements matters, in spite of what the WSDL 2.0 schema says. </p><p>The following is a pseudo-content model of <code>description</code>.</p>
<eg xml:space="preserve">
***************
*** 557,577 ****
</div2>
! <div2 id="component-model"><head>WSDL 2.0 Component Model</head><p>The WSDL 2.0 Infoset model above illustrates the required structure of a WSDL 2.0 document, using the XML Infoset. However, the WSDL 2.0 language also stipulates semantic constraints over and above conformance to this XML Infoset structure. In order to precisely describe these constraints, and as an aid in precisely defining the meaning of each WSDL 2.0 document, the WSDL 2.0 specification defines a <emph>component model</emph> as an additional layer of abstraction above the XML Infoset. Constraints and meaning are defined in terms of this component model, and the definition of each component includes a mapping that specifies how values in the component model are derived from corresponding items in the XML Infoset. </p><p>In general, the WSDL 2.0 component model parallels the structure of the required XML Infoset illustrated above. For example, the <emph>Description</emph>, <emph>Interface</emph>, <emph>Binding</emph>, <emph>Service/emph> and <emph>Endpoint</emph> <emph>components</emph> correspond to the <code>description</code>, <code>interface</code>, <code>binding</code>, <code>service</code>, and <code>endpoint</code> element information items, respectively. Furthermore, each of these components has <emph>properties</emph> whose values are (usually) derived from the element and attribute information item children of those element information items. For example, the Service component corresponds to the <code>service</code> element information item, so the Service component has an {endpoints} property whose value is a set of Endpoint components corresponding to the <code>endpoint</code> element information item children of that <code>service</code> element information item. (Whew!)<ednote><name>dbooth</name><date>2005-04-12</date><edtext>Should we add a graphic illustrating the parallel structure of the component model and the XML Infoset?</edtext></ednote></p><p>The WSDL 2.0 component model is particularly helpful in definin the meaning of <code>import</code> and <code>include</code>. WSDL 2.0 <code>include</code> allows components from another WSDL 2.0 document having the same targetNamespace to be merged in with the components of the current WSDL 2.0 document, and is transitive (i.e., if the included document also includes a WSDL 2.0 document, then those components will also be merged, and so on). WSDL 2.0 <code>import</code> allows components from another WSDL 2.0 document having a different targetNamespace to be merged in with comonents of the current WSDL 2.0 document, and is not transitive.</p></div2></div1>
! <div1 id="advanced-topic-i"><head>Advanced Topic I: More on Messages, Interfaces, Bindings, and Services Definitions</head>
<!-- ******************MessageTypes********************************** -->
<!-- ******************MessageTypes********************************** -->
! <div2 id="more-types"><head>Defining Messages</head>
! <p>WSDL 2.0 <code>types</code> element provides a mechanism for enclosing messages definitions in a WSDL document. WSDL 2.0 only defines the use W3C XML Schema Language
! <bibref ref="XMLSchemaP1"/>. Support for XML Schema <bibref ref="XMLSchemaP1"/> is required of all WSDL 2.0 processors. Alternatively, other type languages can be used via extension to define messages.
! </p>
! <div3 id="more-types-schema">
<head>Defining Messages Using XML Schema</head>
! <p>There are two ways to enclose XML Schema messages definitions within the <code>types</code> element. One way is to use <code>xs:import</code> directly under <code>types</code>, the other way is to embed schema definitions within <code>xs:schema</code> elements which are children of <code>types</code>. It's perfectly reasonable to use both ways in one WSDL.</p>
! <p>A WSDL description MUST NOT refer to XML Schema components in a given namespace unless they are either imported or embedded into the WSDL description. In other words, using the <code>xs:import</code> and/or <code>xs:schema</code> constructs is a necessary condition for making XML Schema components available to a WSDL description. </p>
<p>The following XML syntax for the <code>types</code> element illustrates the use of <code>xs:import</code> and <code>xs:schema</code>:</p>
--- 553,572 ----
</div2>
! <div2 id="component-model"><head>WSDL 2.0 Component Model</head><p>The WSDL 2.0 Infoset model above illustrates the required structure of a WSDL 2.0 document, using the XML Infoset. However, the WSDL 2.0 language also stipulates semantic constraints over and above conformance to this XML Infoset structure. In order to precisely describe these constraints, and as an aid in precisely defining the meaning of each WSDL 2.0 document, the WSDL 2.0 specification defines a <emph>component model</emph> as an additional layer of abstraction above the XML Infoset. Constraints and meaning are defined in terms of this component model, and the definition of each component includes a mapping that specifies how values in the component model are derived from corresponding items in the XML Infoset. </p><p>In general, the WSDL 2.0 component model parallels the structure of the required XML Infoset illustrated above. For example, the <emph>Description</emph>, <emph>Interface</emph>, <emph>Binding</emph>, <emph>Service/emph> and <emph>Endpoint</emph> <emph>components</emph> correspond to the <code>description</code>, <code>interface</code>, <code>binding</code>, <code>service</code>, and <code>endpoint</code> element information items, respectively. The Description component represents the meaning of the <code>description</code> element information item, and hence, it represents the meaning of the WSDL 2.0 document as a whole. </p><p>Furthermore, each of these components has <emph>properties</emph> whose values are (usually) derived from the element and attribute information item children of those element information items. For example, the Service component corresponds to the <code>service</code> element information item, so the Service component has an {endpoints} property whose value is a set of Endpoint components corresponding to the <code>endpoint</code> element information item children of that <code>service</code> element information item. (Whew!)<ednote><name>dbooth</name><date>2005-04-12</date><edtext>TDo: Should we add a graphic illustrating the parallel structure of the component model and the XML Infoset? I think it would be helpful.</edtext></ednote></p><p>The WSDL 2.0 component model is particularly helpful in defining the meaning of <code>import</code> and <code>include</code>. WSDL 2.0 <code>include</code> allows components from another WSDL 2.0 document having the same targetNamespace to be merged in with the components of the current WSDL 2.0 document, and is transitive (i.e., if the included document also includes a WSDL 2.0 document, then those components will also be merged, and so on). WSDL 2.0 <code>import</code> allows components from another WSDL 2.0 document having a different targetNamespace to be merged in with comonents of the current WSDL 2.0 document, and is not transitive.</p></div2></div1>
! <div1 id="more-types"><head>More on Message Types</head>
<!-- ******************MessageTypes********************************** -->
<!-- ******************MessageTypes********************************** -->
! <p>The WSDL 2.0 <code>types</code> element provides a mechanism for enclosing message schemas in a WSDL document. WSDL 2.0 directly supports schemas written in XML Schema
! <bibref ref="XMLSchemaP1"/>. Schemas written in other type definition languages must be defined using a WSDL 2.0 language extension (see WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> Appendix E "<xspecref href="http://www.w3.org/TR/wsdl20-primer#other-schemalang">Examples of Specifications of Extension Elements for Alternative Schema Language Support. (Non-Normative)</xspecref>".
! <ednote><name>dbooth</name><date>2005-04-13</date><edtext>ToDo: Update the above reference to appendix E, as the WG decided to move it to a separate document.</edtext></ednote></p>
! <div2 id="more-types-schema">
<head>Defining Messages Using XML Schema</head>
! <ednote><name>dbooth</name><date>2005-04-13</date><edtext>ToDo: Check the sections below on import and include mechanisms for correctness. (Be sure to check the table also.) I'm not sure I got them all right.</edtext></ednote><p>There are two ways to enclose XML Schema messages definitions within the <code>types</code> element. One way is to embed schema definitions within <code>xs:schema</code> elements that are children of <code>types</code>, as we have already seen. The other way is to use <code>xs:import</code> directly under <code>types</code>. It is perfectly reasonable to use both ways in one WSDL document.</p>
! <p>A WSDL <code>description</code> MUST NOT refer to XML Schema components that are neither imported nor embedded into that WSDL <code>description</code>. In other words, the use of <code>xs:import</code> and/or <code>xs:schema</code> is a necessary condition for making XML Schema components available to a WSDL Description component. </p>
<p>The following XML syntax for the <code>types</code> element illustrates the use of <code>xs:import</code> and <code>xs:schema</code>:</p>
***************
*** 587,618 ****
</eg>
! <div4 id="more-types-schema-embed">
<head>Embedding XML Schema</head>
! <p>We have already seen examples of using embedded schema definitions in section <specref ref="basics-types"/> . 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 existing, stand-alone schema to a location inside the <code>types</code> element.</p>
! <p>The schema components defined in the embedded schema are available to
! WSDL for reference by QName (see @@@@). </p>
! <p>Just like in normal schemas, an embedded XML schema may use the <code>xs:import</code> and <code>xs:include</code>
! elements to refer to other XML schemas either in separate files or embedded in the same
! WSDL description. Note that components embedded in WSDL, <code>xs:import</code>ed, or <code>xs:include</code>d have different visibility to the containing WSDL description. Only components defined in the embedded schemas and components
! <code>xs:include</code>d are available to WSDL for Qname reference.Components that the embedded schemas import via <code>xs:import</code> are NOT available to WSDL.</p>
! <p>A <code>types</code> element can contain zero or more <code>schema</code> elements</p>
! </div4>
! <div4 id="more-types-schema-import">
<head>Importing XML Schema</head>
! <p> There are many cases where one would prefer importing schema definitions from separate schema files to embedding them directly in WSDL. One reason is reusability of the schemas. Components defined in an embedded XML schema are NOT automatically made available to a WSDL description that imported (using <code>wsdl:import</code>)the description that embeds the schema (see section @@@@ for more details).So it is recommended that XML schema documents intended
! to be shared across several WSDL descriptions be placed in separate schema documents and imported into a WSDL document.To facilitate this, WSDL 2.0 allows use of <code>xs:import</code> directly under <code>types</code>. </p>
! <p>Note the schema import mechanism described here leverages XML Schema language <bibref ref="XMLSchemaP1"/>. 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 to the containing WSDL for reference by QName. Note that only components defined in the imported schema itself and components the schema includes via <code>xs:include</code> are available to the containing WSDL. Specifically, components that the schema imports via <code>xs:import</code> are NOT available to WSDL. </p>
! <ednote><name>dbooth</name><edtext>Check this. An issue was recently raised about import not being transitive.</edtext></ednote>
! <p>A <code>types</code> element can contain zero or more <code>import</code>s </p>
! <p>Now let's see an example of importing a schema. Assuming the messages in <specref ref="example-initial-types"/> are defined in a separate schema file named "http://greath.example.com/2004/schemas/resSvc.xsd" with a target namespace "http://greath.example.com/2004/schemas/resSvc", the schema definition can then be imported into the WSDL as follows: </p>
<example id="example-schema-import">
! <head>Importing Message Definitions into WSDL 2.0</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
<description
--- 582,610 ----
</eg>
! <div3 id="more-types-schema-embed">
<head>Embedding XML Schema</head>
! <p>We have already seen an example of using embedded schema definitions in section <specref ref="basics-types"/>, so we will merely add a few additional points here. </p><p>When XML Schema is embedded directly in a WSDL document, it uses the existing top-level <code>xs:schema</code> element defined by XML Schema <bibref ref="XMLSchemaP1"/> to do so, as though the schema had been copied and pasted into the <code>types</code> element. The schema components defined in the embedded schema are then available to
! WSDL for reference by QName (see WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> "<xspecref href="http://www.w3.org/TR/wsdl20-primer#qnameres">QName Resolution</xspecref>"). </p>
! <p>Although WSDL 2.0 provides a <code>wsdl:import</code> mechanism (described in the next section), an embedded XML schema may also use XML Schema's native <code>xs:import</code> and <code>xs:include</code>
! elements to refer to schemas either in separate files or embedded in the same
! WSDL 2.0 document. However, components embedded using <code>xs:import</code> have different visibility from those embedded using <code>xs:include</code>: <code>xs:include</code>d components are available to WSDL for reference by QName, but <code>xs:import</code>ed components are not.</p>
!
! </div3>
! <div3 id="more-types-schema-import">
<head>Importing XML Schema</head>
! <p> There are many cases where one would prefer importing schema definitions from separate schema files instead of embedding them directly under the <code>types</code> element. One reason is reusability of the schemas. Although WSDL 2.0 provides a <code>wsdl:import</code> mechanism, type and element declarations embedded in a WSDL 2.0 document are NOT automatically made available to the importing document, even though other WSDL 2.0 components (such as Interfaces, Bindings, etc.) do become available. Therefore, if you wish to share schema documents across several WSDL 2.0 documents, they should instead be placed in separate XML Schema documents and imported into each WSDL 2.0 document using <code>xs:import</code> directly under <code>types</code>. </p>
! <p>The <code>xs:import</code> mechanism is not transitive. Only components defined in the imported schema itself and components the schema includes via <code>xs:include</code> are available to the containing WSDL document. Specifically, components that the schema imports via <code>xs:import</code> are NOT available to WSDL. </p>
! <ednote><name>dbooth</name><date>2005-04-13</date><edtext>Check this. An issue was recently raised about import not being transitive.</edtext></ednote>
!
! <p>Here is an example of importing a schema. Assuming the message types in <specref ref="example-initial-types"/> are defined in a separate schema file named "http://greath.example.com/2004/schemas/resSvc.xsd" with a target namespace "http://greath.example.com/2004/schemas/resSvc", the schema definition can then be imported into the WSDL as follows: </p>
<example id="example-schema-import">
! <head>Example of Importing Message Definitions</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
<description
***************
*** 632,639 ****
</description>]]></eg>
</example>
! </div4>
! </div3>
! <div3 id="more-types-other-schema">
<head>Defining Messages Using other type languages</head>
<p>The use of type systems other than XML Schema is permitted by using extensions within <code>types</code>.
--- 624,631 ----
</description>]]></eg>
</example>
! </div3>
! <div3 id="more-types-import-include-summary"><head>Summary of Import and Include Mechanisms</head><p>The following table summarizes the similarities and differences between the <code>wsdl:</code> and <code>xs:</code> <code>include</code> and <code>import</code> mechanisms.<table border="1"><caption>Summary of Import and Include Mechanisms</caption><thead><tr><th>Mechanism</th><th>Imported/Included Document Type</th><th>Transitive?</th></tr></thead><tbody><tr><td>wsdl:import</td><td>WSDL 2.0 document</td><td>Merge Interface, Binding and Service components from another WSDL 2.0 document that has a DIFFERENT targetNamespace. (Schema type and element declarations are NOT merged.)</td><td>No</td></tr><tr><td>wsdl:include</td><td>WSDL 2.0 document</td><td>Merge Interface, Binding and Service components from another WSDL 2.0 document that has the SAME targetNamespace. (Schema type and element declarations are NOT merged.)</td><td>Yes</td></tr><tr><td>xs::import</td><td>XML Schema document</td><td>Merge typeand element declarations from another XML Schema document that has a DIFFERENT targetNamespace.</td><td>No</td></tr><tr><td>xs:import</td><td>XML Schema document</td><td>Merge type and element declarations from another XML Schema document that has the SAME targetNamespace.</td><td>Yes</td></tr></tbody></table></p></div3></div2>
! <div2 id="more-types-other-schema">
<head>Defining Messages Using other type languages</head>
<p>The use of type systems other than XML Schema is permitted by using extensions within <code>types</code>.
***************
*** 650,664 ****
</ednote>
! </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 complete 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>
--- 642,656 ----
</ednote>
! </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 complete syntax for the <code>interface</code> element. </p>
! <div2 id="more-interfaces-interfaces">
<head>Interface Syntax </head>
<ednote><name>dbooth</name><edtext>To do: Simplify this syntax summary.</edtext></ednote>
***************
*** 738,744 ****
<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>
<ednote>
--- 730,736 ----
<p>One WSDL <code>description</code> element may contain zero or more <code>interface</code> elements as its direct children. Zero <code>interface</code> elements are permitted since a <code>description</code> element may only contain binding and/or endpoint definitions to be aggegrated into a master WSDL description via import/include mechanisms. </p>
<p>Let's have a look at the attributes of <code>interface</code> first. It has one required <att>name</att> attribute. Within the same WSDL target namespace (which might be in different WSDL documents; see section @@@@), each interface must have a unique name. The <code>interface</code> element has two optional attributes:<att>extends</att> and <att>styleDefault</att>. <att>extends</att> will be explained in the next section. We will explain what a <att>style</att> later. For now, keep in mind that the optional <att>styleDefault</att> attribute of <code>interface</code> can be used to define a default value for the <att>style</att> attribute of all operations under this interface, if any of the operations do not specify a value for its <att>style</att>. </p>
! <div3 id="more-interfaces-inheritance">
<head>Interface Inheritance</head>
! <p>The optional <att>extends</att> attribute allows an interface to extend one or more other interfaces. In such cases the interface contains the operations of the interfaces it extends, along with any operations it defines. Two things about extending interfaces deserve some attention. </p><p>First, recursive extension of interfaces is prohibited. The interfaces that a given interface extends MUST NOT themselves extend that interface either directly or indirectly. </p><p>Second, there may be cases where, due to an interface extending one or more other interfaces, operations from different interface may have a name collision. More precisely, within the same namespace, two or more interface operations end up having the same name. In such cases, WSDL 2.0 requires that the component models of those Interface Operation components MUST be equivalent (see WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> "<xspecref href="http://www.w3.org/TR/wsdl20-primer#compequiv">Equivalence of Components</xspecref>"). Foroperations, basically equivalence means the two operations in question have the same set of attributes and descendents). If the collisional operations are equivalent then they are considered to collapse into a single operation. It is an error if they have the same name in the same WSDL target namespace but are not equivalent. In other words, if two interfaces have name collisional operations, then those two interfaces cannot both form part of the derivation chain of a derived interface unless those operations are exactly the same. For the above reason, it is considered good practic to ensure that all operations within the same namespace are named uniquely whenever possible. Furthermore, since faults, features and properties can also be defined as children of the <code>interface</code> element (as descrbed later), the same name-collision resolution rules apply to those constructs.</p>
<ednote>
***************
*** 751,756 ****
<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>
--- 743,748 ----
<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>
***************
*** 805,810 ****
</example>
! </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>
--- 797,802 ----
</example>
! </div3>
! <div3 id="more-interfaces-operations">
<head>Interface Operations</head>
<p>Now we are ready to take a close look at the <code>operation</code> element. As explained earlier, message types are defined in a type system, and the sequencing and cardinality of the messages involved in a particular interaction are governed by the message exchange pattern (MEP). The <code>operation</code> element is the glue that brings all the pieces together for an abstract interaction. </p>
***************
*** 900,909 ****
<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>
--- 892,901 ----
<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>
***************
*** 915,919 ****
other nodes. To maximize reuse, WSDL message exchange patterns identify a minimal contract between other parties and Web Services, and contain only information that is
relevant to both the Web service and the client that engages that service.</p>
! <p>A total of 8 MEPs are defined in Part 2 of the WSDL 2.0 specification. Hopefully, these MEPs will cover the most common use cases, but they are not meant to be an exhaustive list of MEPs that can be used by operations. More MEPs can be defined for particular application needs by interested parties. <ednote><name>dbooth</name><edtext>Add info about how to define a new MEP?</edtext></ednote></p>
<p>For the 8 MEPs defined by WSDL 2.0, some of them are variations of others based on how faults may be generated. Three common fault generation models are specified. <glist><gitem><label>Fault Replaces Message</label><def><p>Any message after the first in the pattern MAY be replaced with a fault message, which MUST have identical cardinality and direction. The fault message MUST be delivered to the same target node as the message it replaces. </p></def></gitem><gitem><label>Message Triggers Fault</label><def><p>Any message, including the first, MAY trigger a fault message in response. Each recipient MAY generate a fault message, and MUST generate no more than one fault for each triggering message. Each fault message has direction the reverse of its triggering message. The fault message MUST be delivered to the originator of the message which triggered it. If there is no path to this node, the fault MUST be discarded. In the third case, no fault may be generated in the MEP. </p></def></gitem><gitem><abel>No Faults</label><def><p>No faults will be delivered.</p></def></gitem></glist></p>
<p>Now let's have a look of each of the 8 MEPs. Depends on how the first message in the MEP is initiated, we can probably group the MEPs into in-bound MEPs in which case the service receives the first message in the exchange, and out-bound MEPs in which case the service sends out the first message in the exchange. Such Grouping is only for the purpose of easy reference from discussions in later sections of this primer. WSDL 2.0 defines four in-bound MEPS:</p>
--- 907,911 ----
other nodes. To maximize reuse, WSDL message exchange patterns identify a minimal contract between other parties and Web Services, and contain only information that is
relevant to both the Web service and the client that engages that service.</p>
! <p>A total of 8 MEPs are defined in WSDL 2.0 Part 2 <bibref ref="WSDL-PART2"/>. Hopefully, these MEPs will cover the most common use cases, but they are not meant to be an exhaustive list of MEPs that can be used by operations. More MEPs can be defined for particular application needs by interested parties. <ednote><name>dbooth</name><edtext>Add info about how to define a new MEP?</edtext></ednote></p>
<p>For the 8 MEPs defined by WSDL 2.0, some of them are variations of others based on how faults may be generated. Three common fault generation models are specified. <glist><gitem><label>Fault Replaces Message</label><def><p>Any message after the first in the pattern MAY be replaced with a fault message, which MUST have identical cardinality and direction. The fault message MUST be delivered to the same target node as the message it replaces. </p></def></gitem><gitem><label>Message Triggers Fault</label><def><p>Any message, including the first, MAY trigger a fault message in response. Each recipient MAY generate a fault message, and MUST generate no more than one fault for each triggering message. Each fault message has direction the reverse of its triggering message. The fault message MUST be delivered to the originator of the message which triggered it. If there is no path to this node, the fault MUST be discarded. In the third case, no fault may be generated in the MEP. </p></def></gitem><gitem><abel>No Faults</label><def><p>No faults will be delivered.</p></def></gitem></glist></p>
<p>Now let's have a look of each of the 8 MEPs. Depends on how the first message in the MEP is initiated, we can probably group the MEPs into in-bound MEPs in which case the service receives the first message in the exchange, and out-bound MEPs in which case the service sends out the first message in the exchange. Such Grouping is only for the purpose of easy reference from discussions in later sections of this primer. WSDL 2.0 defines four in-bound MEPS:</p>
***************
*** 974,981 ****
! <ednote><name>dbooth</name><date>20050401</date><edtext>ToDo: Add a section on defining a new MEP. (dbooth will do this if he has time.)</edtext></ednote></div3></div2>
<!-- **********************************Binding************************** -->
<!-- **********************************Binding************************** -->
! <div2 id="more-bindings">
<head>More on Bindings</head>
--- 966,973 ----
! <ednote><name>dbooth</name><date>20050401</date><edtext>ToDo: Add a section on defining a new MEP. (dbooth will do this if he has time.)</edtext></ednote></div2></div1>
<!-- **********************************Binding************************** -->
<!-- **********************************Binding************************** -->
! <div1 id="more-bindings">
<head>More on Bindings</head>
***************
*** 1001,1006 ****
listing each operation of the interface and
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>
--- 993,998 ----
listing each operation of the interface and
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 <bibref ref="WSDL-PART1"/>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>
***************
*** 1048,1052 ****
<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>
--- 1040,1044 ----
<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>
***************
*** 1081,1086 ****
<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
--- 1073,1078 ----
<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
***************
*** 1099,1107 ****
</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>
--- 1091,1099 ----
</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>
***************
*** 1202,1207 ****
</p>
! </div3>
! <div3 id="more-bindings-http">
<head>Extensions for HTTP Binding</head>
<example id="example-bindings-http">
--- 1194,1199 ----
</p>
! </div2>
! <div2 id="more-bindings-http">
<head>Extensions for HTTP Binding</head>
<example id="example-bindings-http">
***************
*** 1217,1249 ****
</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>
! <eg xml:space="preserve">
<description targetNamespace="<emph>xs:anyURI</emph>" >
! <service name="<emph>xs:NCName</emph>" interface="<emph>xs:QName</emph>"
! <documentation />?
! <endpoint name="<emph>xs:NCName</emph>" binding="<emph>xs:QName</emph>" >
! <documentation />?
! </endpoint>+
! </service>*
</description>
</eg>
! <p>A <code>service</code> has a required <att>name</att> attribute (also see section @@@@ for service reference). Each <code>service</code> within a same namespace must be named uniquely. A <code>service</code> can only implement one single interface, and it must specify the single interface it implements via the <att>interface</att> attribute. </p>
! <p>A <code>service</code> may contain one or more alternate <code>endpoints</code>. An <code>endpoint</code> defines the particulars of a specific endpoint at which a given service is available.</p>
! <p>An <code>endpoint</code> has two required attributes: <att>name</att> and <att>binding</att>. All <code>endpoints</code> within a <code>service</code> must be named uniquely via the <att>name</att> attribute. The required <att>binding</att> attribute refers to, via QName, a <code>binding</code> definition. Note that if the refered <code>binding</code> specifies a particular interface, that interface MUST be the same as the one implmented by the parent <code>service</code>. </p>
! <p>Like the WSDL binding constructs explained in section @@@@, the WSDL <code>endpoint</code> construct is also like an anchor for hosting extension elements that are used to provide information specific to a
! particular endpoint in a server. The semantics of such extensions are defined by the specification for those extensions. Such specifications are expected to annotate the WSDL <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***************** -->
--- 1209,1240 ----
</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>
! <eg xml:space="preserve">
<description targetNamespace="<emph>xs:anyURI</emph>" >
! <service name="<emph>xs:NCName</emph>" interface="<emph>xs:QName</emph>"
! <documentation />?
! <endpoint name="<emph>xs:NCName</emph>" binding="<emph>xs:QName</emph>" >
! <documentation />?
! </endpoint>+
! </service>*
</description>
</eg>
! <p>A <code>service</code> has a required <att>name</att> attribute (also see section @@@@ for service reference). Each <code>service</code> within a same namespace must be named uniquely. A <code>service</code> can only implement one single interface, and it must specify the single interface it implements via the <att>interface</att> attribute. </p>
! <p>A <code>service</code> may contain one or more alternate <code>endpoints</code>. An <code>endpoint</code> defines the particulars of a specific endpoint at which a given service is available.</p>
! <p>An <code>endpoint</code> has two required attributes: <att>name</att> and <att>binding</att>. All <code>endpoints</code> within a <code>service</code> must be named uniquely via the <att>name</att> attribute. The required <att>binding</att> attribute refers to, via QName, a <code>binding</code> definition. Note that if the refered <code>binding</code> specifies a particular interface, that interface MUST be the same as the one implmented by the parent <code>service</code>. </p>
! <p>Like the WSDL binding constructs explained in section @@@@, the WSDL <code>endpoint</code> construct is also like an anchor for hosting extension elements that are used to provide information specific to a
! particular endpoint in a server. The semantics of such extensions are defined by the specification for those extensions. Such specifications are expected to annotate the WSDL <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 <bibref ref="WSDL-PART3"/> also provide extensions to be used under a service <code>endpoint</code>. </p>
!
! </div1>
<!-- **********************************AdvancedTopics***************** -->
***************
*** 2758,2762 ****
</bibl>
- <!--
<bibl key="WSDL 2.0 Bindings" href="&w3c-designation-part3;" id="WSDL-PART3">
<titleref>Web Services Description Language (WSDL) Version
--- 2749,2752 ----
***************
*** 2774,2779 ****
Description Language (WSDL) Version 2.0 Part 3:
Bindings"</loc> is available at &part3.latest;.
! </bibl>
! -->
<!--
--- 2764,2768 ----
Description Language (WSDL) Version 2.0 Part 3:
Bindings"</loc> is available at &part3.latest;.
! </bibl>
<!--
Index: wsdl20-primer.html
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.html,v
retrieving revision 1.25
retrieving revision 1.26
diff -C2 -d -r1.25 -r1.26
*** wsdl20-primer.html 13 Apr 2005 04:40:45 -0000 1.25
--- wsdl20-primer.html 13 Apr 2005 20:19:44 -0000 1.26
***************
*** 193,202 ****
<p class="toc">1. <a href="#Introduction">Introduction</a><br />
2. <a href="#basics">WSDL 2.0 Basics</a><br />
! 3. <a href="#wsdl-xml-representation">WSDL 2.0 XML Infoset and
Component Model</a><br />
! 4. <a href="#advanced-topic-i">Advanced Topic I: More on Messages,
! Interfaces, Bindings, and Services Definitions</a><br />
! 5. <a href="#advanced-topic_ii">Advanced Topics II - TBD</a><br />
! 6. <a href="#References">References</a><br />
</p>
</div>
[...1943 lines suppressed...]
+ href="http://www.w3.org/TR/wsdl20-bindings">latest version of "Web
+ Services Description Language (WSDL) Version 2.0 Part 3:
+ Bindings"</a> is available at
+ http://www.w3.org/TR/wsdl20-bindings.</dd>
+
<dt class="label"><a id="webarch" name="webarch"></a>[Web
Architecture]</dt>
***************
*** 4990,4994 ****
<div class="div2">
<h3><a id="Informative-References"
! name="Informative-References"></a>6.2 Informative References</h3>
<dl>
--- 5137,5141 ----
<div class="div2">
<h3><a id="Informative-References"
! name="Informative-References"></a>9.2 Informative References</h3>
<dl>
Received on Wednesday, 13 April 2005 20:19:48 UTC