- From: Kevin Liu via cvs-syncmail <cvsmail@w3.org>
- Date: Fri, 17 Jun 2005 23:32:34 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20
In directory hutz:/tmp/cvs-serv27940/ws/desc/wsdl20
Modified Files:
wsdl20-primer.html wsdl20-primer.xml
Log Message:
minor editings for typos
Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.102
retrieving revision 1.103
diff -C2 -d -r1.102 -r1.103
*** wsdl20-primer.xml 17 Jun 2005 21:46:48 -0000 1.102
--- wsdl20-primer.xml 17 Jun 2005 23:32:32 -0000 1.103
***************
*** 208,213 ****
! </div2><div2 id="basics-getting-started"><head>Getting Started: Defining a WSDL 2.0 Target Namespace</head><p>Before writing our WSDL 2.0 document, we need to decide on a <emph>WSDL 2.0 target namespace</emph> URI for it. The WSDL 2.0 target namespace is analogous to an XML Schema target namespace. Interface, binding and service names that we define in our WSDL 2.0 document will be associated with the WSDL 2.0 target namespace, and thus will be distinguishable from similar names in a different WSDL 2.0 target namespace. (This will become important if using WSDL 2.0's import or interface inheritance mechanisms.) </p><p>The value of the WSDL 2.0 target namespace must be an absolute URI. Furthermore, it should be dereferenceable to a WSDL 2.0 document that describes the Web service that the WSDL 2.0 target namespace is used to describe. For example, the GreatH owners should make the WSDL 2.0 document available from this URI. (And if a WSDL 2.0 description is split into multiple documents, then the WSL 2.0 target namespace should resolve to a master document that includes all the WSDL 2.0 documents needed for that service description.) However, there is no absolute requirement for this URI to be dereferenceable, so a WSDL 2.0 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 2.0 document from anywhere -- not necessarily an authoritative source. But by dereferencing the WSDL 2.0 target namespace URI, a user should be able to obtain an authoritative version. Since GreatH will be the owner of the service, the WSDL 2.0 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 2.0 target namespace URI, we can begin our WSDL 2.0 2.0 document as the following empty shell.</p><example id="example-empty-shell">
! <head>An Initial Empty WSDL 2.0 2.0 Document</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
<description
--- 208,213 ----
! </div2><div2 id="basics-getting-started"><head>Getting Started: Defining a WSDL 2.0 Target Namespace</head><p>Before writing our WSDL 2.0 document, we need to decide on a <emph>WSDL 2.0 target namespace</emph> URI for it. The WSDL 2.0 target namespace is analogous to an XML Schema target namespace. Interface, binding and service names that we define in our WSDL 2.0 document will be associated with the WSDL 2.0 target namespace, and thus will be distinguishable from similar names in a different WSDL 2.0 target namespace. (This will become important if using WSDL 2.0's import or interface inheritance mechanisms.) </p><p>The value of the WSDL 2.0 target namespace must be an absolute URI. Furthermore, it should be dereferenceable to a WSDL 2.0 document that describes the Web service that the WSDL 2.0 target namespace is used to describe. For example, the GreatH owners should make the WSDL 2.0 document available from this URI. (And if a WSDL 2.0 description is split into multiple documents, then the WSL 2.0 target namespace should resolve to a master document that includes all the WSDL 2.0 documents needed for that service description.) However, there is no absolute requirement for this URI to be dereferenceable, so a WSDL 2.0 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 2.0 document from anywhere -- not necessarily an authoritative source. But by dereferencing the WSDL 2.0 target namespace URI, a user should be able to obtain an authoritative version. Since GreatH will be the owner of the service, the WSDL 2.0 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 2.0 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 2.0 Document</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
<description
***************
*** 219,229 ****
. . .
</description>]]></eg>
! </example><div3 id="example-empty-shell-explanation"><head>Explanation of Example</head><p><glist><gitem><label><code><description</code></label><def><p>Every WSDL 2.0 2.0 document has a <code>description</code> element as its top-most element. This merely acts as a container for the rest of the WSDL 2.0 2.0 document, and is used to declare namespaces that will be used throughout the document.</p></def></gitem><gitem><label><code>xmlns="http://www.w3.org/2005/05/wsdl"</code></label>
<def>
<p>
! This is the XML namespace for WSDL 2.0 2.0 itself.
Because we have not defined a prefix for it, any
unprefixed elements are expected
! to be WSDL 2.0 2.0 elements (such as
the
<code>description</code>
--- 219,229 ----
. . .
</description>]]></eg>
! </example><div3 id="example-empty-shell-explanation"><head>Explanation of Example</head><p><glist><gitem><label><code><description</code></label><def><p>Every WSDL 2.0 document has a <code>description</code> element as its top-most element. This merely acts as a container for the rest of the WSDL 2.0 document, and is used to declare namespaces that will be used throughout the document.</p></def></gitem><gitem><label><code>xmlns="http://www.w3.org/2005/05/wsdl"</code></label>
<def>
<p>
! This is the XML namespace for WSDL 2.0 itself.
Because we have not defined a prefix for it, any
unprefixed elements are expected
! to be WSDL 2.0 elements (such as
the
<code>description</code>
***************
*** 597,603 ****
</div2>
! <div2 id="component-model"><head>WSDL 2.0 Component Model</head><p>The WSDL 2.0 Infoset model above illustrates the required structure of a WSDL 2.0 document, using the XML Infoset. However, the WSDL 2.0 language also imposes many semantic constraints over and above structural conformance to this XML Infoset. In order to precisely describe these constraints, and as an aid in precisely defining the meaning of each WSDL 2.0 document, the WSDL 2.0 specification defines a <emph>component model</emph> as an additional layer of abstraction above the XML Infoset. Constraints and meaning are defined in terms of this component model, and the definition of each component includes a mapping that specifies how values in the component model are derived from corresponding items in the XML Infoset. The following diagram gives an overview of the WSDL 2.0 components and their containment hiearchy.
! <graphic source="images/WSDL20Components.png" alt="WSDL 2.0 Components Containment Hiearchy"/></p>
--- 597,603 ----
</div2>
! <div2 id="component-model"><head>WSDL 2.0 Component Model</head><p>The WSDL 2.0 Infoset model above illustrates the required structure of a WSDL 2.0 document, using the XML Infoset. However, the WSDL 2.0 language also imposes many semantic constraints over and above structural conformance to this XML Infoset. In order to precisely describe these constraints, and as an aid in precisely defining the meaning of each WSDL 2.0 document, the WSDL 2.0 specification defines a <emph>component model</emph> as an additional layer of abstraction above the XML Infoset. Constraints and meaning are defined in terms of this component model, and the definition of each component includes a mapping that specifies how values in the component model are derived from corresponding items in the XML Infoset. The following diagram gives an overview of the WSDL 2.0 components and their containment hierarchy.
! <graphic source="images/WSDL20Components.png" alt="WSDL 2.0 Components Containment hierarchy"/></p>
***************
*** 623,627 ****
element. The effect of the
<el>include</el>
! element is cummulative so that if document A includes document B
and document B includes document C, then the components defined
by document A consist of those whose definitions are contained
--- 623,627 ----
element. The effect of the
<el>include</el>
! element is cumulative so that if document A includes document B
and document B includes document C, then the components defined
by document A consist of those whose definitions are contained
***************
*** 927,931 ****
</p>
! <p>Let's say the GreatH hotel wants to maintain a a standard message log operation for all received messages. It wants this operation to be reusable across the whole reservation system, so each service will send out, for potential use of a logging service,
the content of each message it receives together with a timestamp and the originator of the message. One way to meet such requirement is to define the log operation in an interface which can be inherited by other interfaces. Assuming a <code>messageLog</code> element is already defined in the ghns namespace with the required content, the inheritance use case is illustrated in the following example. As a result of the inheritance, the <code>reservationInterface</code> now contains two operations: <code>opCheckAvailability</code> and <code>opLogMessage</code></p>
--- 927,931 ----
</p>
! <p>Let's say the GreatH hotel wants to maintain a standard message log operation for all received messages. It wants this operation to be reusable across the whole reservation system, so each service will send out, for potential use of a logging service,
the content of each message it receives together with a timestamp and the originator of the message. One way to meet such requirement is to define the log operation in an interface which can be inherited by other interfaces. Assuming a <code>messageLog</code> element is already defined in the ghns namespace with the required content, the inheritance use case is illustrated in the following example. As a result of the inheritance, the <code>reservationInterface</code> now contains two operations: <code>opCheckAvailability</code> and <code>opLogMessage</code></p>
***************
*** 1026,1030 ****
<p>An optional <att>style</att> attribute whose value is a list of absolute URIs. Each URI identifies a certain set of rules that were followed in defining this <code>operation</code>. It is an error if a particular style is indicated, but the associated rules are not followed. <bibref ref="WSDL-PART2"/> defines a set of styles, including</p>
<ulist>
! <item><p>RPC Style.The RPC style is selected when the <att>style</att> is assigned the value http://www.w3.org/2005/05/wsdl/style/rpc. It places restrictions for Remote Procedure Call-types of interactions. </p></item>
<item><p>URI Style. The URI style is selected when the <att>style</att> is assigned the value http://www.w3.org/2005/05/wsdl/style/uri. It places restrictions on message definitions so they may be serialized into something like HTTP URL encoded.</p></item>
<item><p>The Multipart style. The Multipart style is selected when the <att>style</att> is assigned the value http://www.w3.org/2005/05/wsdl/style/multipart. In the HTTP binding, for XForm clients, a message must be defined following the Multipart style and serialized as "Multipart/form-data". </p> </item>
--- 1026,1030 ----
<p>An optional <att>style</att> attribute whose value is a list of absolute URIs. Each URI identifies a certain set of rules that were followed in defining this <code>operation</code>. It is an error if a particular style is indicated, but the associated rules are not followed. <bibref ref="WSDL-PART2"/> defines a set of styles, including</p>
<ulist>
! <item><p>RPC Style. The RPC style is selected when the <att>style</att> is assigned the value http://www.w3.org/2005/05/wsdl/style/rpc. It places restrictions for Remote Procedure Call-types of interactions. </p></item>
<item><p>URI Style. The URI style is selected when the <att>style</att> is assigned the value http://www.w3.org/2005/05/wsdl/style/uri. It places restrictions on message definitions so they may be serialized into something like HTTP URL encoded.</p></item>
<item><p>The Multipart style. The Multipart style is selected when the <att>style</att> is assigned the value http://www.w3.org/2005/05/wsdl/style/multipart. In the HTTP binding, for XForm clients, a message must be defined following the Multipart style and serialized as "Multipart/form-data". </p> </item>
***************
*** 1412,1416 ****
<div2 id="adv-extensibility">
<head>Extensibility</head>
! <p>WSDL 2.0 provides two extensibility mechanisms: an open content model, which allows XML elements and attributes from other (non-WSDL 2.0) XML namespaces to be interspersed in a WSDL 2.0 document; and <xspecref href="&w3c-designation-part1;#Feature">Features</xspecref> and <xspecref href="&w3c-designation-part1;#Property">Properties</xspecref>. Both mechanisms use URIs to identify the semantics of the extensions. For extension XML elements and attributes, the namespace URI of the extension element or attribute acts as an unambiguous name for the semantics of that extension. For Features and Properties, the Feature or Property is named by a URI.</p><p>In either case, the URI that identifies the semantics of an extension should be dereferenceable to a document that describes the semantics of that extension. As of this writing, there is no generally accepted standard for what kind of document that should be. However, the <loc href="http://www.w3.org/2001/tag/">W3C TAG</loc> has been discussing th issue (see TAG issue <loc href="http://www.w3.org/2001/tag/issues.html?type=1#namespaceDocument-8">namespaceDocument-8</loc>) and is likely to provide guidance at some point.</p><div3 id="adv-optional-versus-required"><head>Optional Versus Required Extensions</head><p>Extensions can either be required or optional.</p><p>An <emph>optional</emph> extension is one that the client may either engage or ignore, entirely at its discretion, and is signaled by attribute <code>wsdl:required="false"</code> or the absence of the <code>wsdl:required</code> attribute (because it defaults to false). Thus, a WSDL 2.0 processor, acting on behalf of the client, that encounters an unknown optional extension can safely ignore it and continue to process the WSDL 2.0 document. However, it is important to stress that optional extensions are only optional to the <emph>client</emph> -- not the service. A service must support all optional and required extensions that it advertises in its WSDL 2.0 document. </p><p>A <emph>requred</emph> extension is one that must be supported and engaged by the client in order for the interaction to procede properly, and is signaled by attribute <code>wsdl:required="true"</code>. If a WSDL 2.0 processor, acting on behalf of the client, encounters a required extension that it does not recognize or does not support, then it cannot safely continue to process the WSDL 2.0 document. In most practical cases, this is likely to mean that the processor will require manual intervention to deal with the extension. For example, a client developer might manually provide an implementation for the required extension to the WSDL 2.0 processor. </p></div3>
<!-- removed per minutes 5-12-2005 AI div3 id="adv-scope-of-wsdl-required"><head>Scoping of the wsdl:required Attribute</head><ednote><name>dbooth</name><date>2005-04-15</date><edtext>ToDo: Need to check the scoping rules to see if this is correct.</edtext></ednote><p>As a convenience mechanism, the <code>wsdl:required</code> attribute need not be specified on every extension element. If it is omitted from an extension element, its effective value is inherited from the smallest enclosing scope that explicitly sets its value. If there is no enclosing scope that explicitly sets its value, then its value defaults to <code>false</code>. </p><p>Because portions of a Web service description can be written in different physical documents by different people, one should be cautious about setting <code>wsdl:required="false"</code> when an outer scope, written by someone else, had set <code>wsdl:required="true"</code>.</p></div3 -->
--- 1412,1416 ----
<div2 id="adv-extensibility">
<head>Extensibility</head>
! <p>WSDL 2.0 provides two extensibility mechanisms: an open content model, which allows XML elements and attributes from other (non-WSDL 2.0) XML namespaces to be interspersed in a WSDL 2.0 document; and <xspecref href="&w3c-designation-part1;#Feature">Features</xspecref> and <xspecref href="&w3c-designation-part1;#Property">Properties</xspecref>. Both mechanisms use URIs to identify the semantics of the extensions. For extension XML elements and attributes, the namespace URI of the extension element or attribute acts as an unambiguous name for the semantics of that extension. For Features and Properties, the Feature or Property is named by a URI.</p><p>In either case, the URI that identifies the semantics of an extension should be dereferenceable to a document that describes the semantics of that extension. As of this writing, there is no generally accepted standard for what kind of document that should be. However, the <loc href="http://www.w3.org/2001/tag/">W3C TAG</loc> has been discussing th issue (see TAG issue <loc href="http://www.w3.org/2001/tag/issues.html?type=1#namespaceDocument-8">namespaceDocument-8</loc>) and is likely to provide guidance at some point.</p><div3 id="adv-optional-versus-required"><head>Optional Versus Required Extensions</head><p>Extensions can either be required or optional.</p><p>An <emph>optional</emph> extension is one that the client may either engage or ignore, entirely at its discretion, and is signaled by attribute <code>wsdl:required="false"</code> or the absence of the <code>wsdl:required</code> attribute (because it defaults to false). Thus, a WSDL 2.0 processor, acting on behalf of the client, that encounters an unknown optional extension can safely ignore it and continue to process the WSDL 2.0 document. However, it is important to stress that optional extensions are only optional to the <emph>client</emph> -- not the service. A service must support all optional and required extensions that it advertises in its WSDL 2.0 document. </p><p>A <emph>requred</emph> extension is one that must be supported and engaged by the client in order for the interaction to proceed properly, and is signaled by attribute <code>wsdl:required="true"</code>. If a WSDL 2.0 processor, acting on behalf of the client, encounters a required extension that it does not recognize or does not support, then it cannot safely continue to process the WSDL 2.0 document. In most practical cases, this is likely to mean that the processor will require manual intervention to deal with the extension. For example, a client developer might manually provide an implementation for the required extension to the WSDL 2.0 processor. </p></div3>
<!-- removed per minutes 5-12-2005 AI div3 id="adv-scope-of-wsdl-required"><head>Scoping of the wsdl:required Attribute</head><ednote><name>dbooth</name><date>2005-04-15</date><edtext>ToDo: Need to check the scoping rules to see if this is correct.</edtext></ednote><p>As a convenience mechanism, the <code>wsdl:required</code> attribute need not be specified on every extension element. If it is omitted from an extension element, its effective value is inherited from the smallest enclosing scope that explicitly sets its value. If there is no enclosing scope that explicitly sets its value, then its value defaults to <code>false</code>. </p><p>Because portions of a Web service description can be written in different physical documents by different people, one should be cautious about setting <code>wsdl:required="false"</code> when an outer scope, written by someone else, had set <code>wsdl:required="true"</code>.</p></div3 -->
***************
*** 1521,1530 ****
<head>Defining New MEPs</head>
! <p>As we mentioned in <specref ref= "more-interfaces-meps"/>, even though the 8 MEPs defined by WSDL 2.0 are intented to cover most of the common use cases, there are situations that require new MEPs to be defined. In this section, we will explain how new MEPs can be defined to address special business requirements.</p>
<p>Following the wild success of its reservation service, GreatH discovered
that it could radically increase tourist interest by supplying information
on weather conditions, both to travel agents and to the general touring
! public. This produced a challenge for the service implementors: how could
this information be supplied to interested parties without requiring
knowledge of web service technology specifically, and of computers
--- 1521,1530 ----
<head>Defining New MEPs</head>
! <p>As we mentioned in <specref ref= "more-interfaces-meps"/>, even though the 8 MEPs defined by WSDL 2.0 are intended to cover most of the common use cases, there are situations that require new MEPs to be defined. In this section, we will explain how new MEPs can be defined to address special business requirements.</p>
<p>Following the wild success of its reservation service, GreatH discovered
that it could radically increase tourist interest by supplying information
on weather conditions, both to travel agents and to the general touring
! public. This produced a challenge for the service implementers: how could
this information be supplied to interested parties without requiring
knowledge of web service technology specifically, and of computers
***************
*** 1927,1931 ****
<item>
<p>
! With an incompatible change, the client receives a new version of the interface description and is expected to adjust to the new interface before old interface is terminated. Either the service will need to continue to support both versions of the interface during the hand over period, or the service and the clients are co-ordinated to change at the same time. An alternative is for the
client to continue until it encounters an error, at which point it uses the new version of the interface.
</p>
--- 1927,1931 ----
<item>
<p>
! With an incompatible change, the client receives a new version of the interface description and is expected to adjust to the new interface before old interface is terminated. Either the service will need to continue to support both versions of the interface during the hand over period, or the service and the clients are coordinated to change at the same time. An alternative is for the
client to continue until it encounters an error, at which point it uses the new version of the interface.
</p>
***************
*** 2681,2685 ****
<p>
! In the preceeding example, there was a single
endpoint associated with each Reservation Detail
Web service. Suppose GreatH hotel decided to
--- 2681,2685 ----
<p>
! In the preceding example, there was a single
endpoint associated with each Reservation Detail
Web service. Suppose GreatH hotel decided to
***************
*** 2693,2697 ****
which are each of type <code>reservationDetailsSOAPEndpointType</code>
and therefore contain the address of an endpoint that implements
! the <code>wdetails:reservationDetailsSOAPBinding</code> bindng.
</p>
<p>
--- 2693,2697 ----
which are each of type <code>reservationDetailsSOAPEndpointType</code>
and therefore contain the address of an endpoint that implements
! the <code>wdetails:reservationDetailsSOAPBinding</code> binding.
</p>
<p>
***************
*** 3136,3140 ****
service definitions. However, the namespaces are
not automatically visible to the other inline
! schemas. Each inline schema must explictly
import any other namespace it references. The
<code>schemaLocation</code>
--- 3136,3140 ----
service definitions. However, the namespaces are
not automatically visible to the other inline
! schemas. Each inline schema must explicitly
import any other namespace it references. The
<code>schemaLocation</code>
Index: wsdl20-primer.html
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.html,v
retrieving revision 1.73
retrieving revision 1.74
diff -C2 -d -r1.73 -r1.74
*** wsdl20-primer.html 17 Jun 2005 21:46:48 -0000 1.73
--- wsdl20-primer.html 17 Jun 2005 23:32:32 -0000 1.74
***************
*** 233,238 ****
</div><div class="div2">
! <h3><a name="basics-getting-started"></a>2.2 Getting Started: Defining a WSDL 2.0 Target Namespace</h3><p>Before writing our WSDL 2.0 document, we need to decide on a <em>WSDL 2.0 target namespace</em> URI for it. The WSDL 2.0 target namespace is analogous to an XML Schema target namespace. Interface, binding and service names that we define in our WSDL 2.0 document will be associated with the WSDL 2.0 target namespace, and thus will be distinguishable from similar names in a different WSDL 2.0 target namespace. (This will become important if using WSDL 2.0's import or interface inheritance mechanisms.) </p><p>The value of the WSDL 2.0 target namespace must be an absolute URI. Furthermore, it should be dereferenceable to a WSDL 2.0 document that describes the Web service that the WSDL 2.0 target namespace is used to describe. For example, the GreatH owners should make the WSDL 2.0 document available from this URI. (And if a WSDL 2.0 description is split into multiple documents, then the WSDL 2.0 trget namespace should resolve to a master document that includes all the WSDL 2.0 documents needed for that service description.) However, there is no absolute requirement for this URI to be dereferenceable, so a WSDL 2.0 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 2.0 document from anywhere -- not necessarily an authoritative source. But by dereferencing the WSDL 2.0 target namespace URI, a user should be able to obtain an authoritative version. Since GreatH will be the owner of the service, the WSDL 2.0 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 2.0 target namespace URI, we can begin our WSDL 2.0 2.0 document as the following empty shell.</p><div class="exampleOuter">
! <p style="text-align: left" class="exampleHead"><a name="example-empty-shell"></a><i><span>Example 2-2. </span>An Initial Empty WSDL 2.0 2.0 Document</i></p>
<div class="exampleInner"><pre><?xml version="1.0" encoding="utf-8" ?>
<description
--- 233,238 ----
</div><div class="div2">
! <h3><a name="basics-getting-started"></a>2.2 Getting Started: Defining a WSDL 2.0 Target Namespace</h3><p>Before writing our WSDL 2.0 document, we need to decide on a <em>WSDL 2.0 target namespace</em> URI for it. The WSDL 2.0 target namespace is analogous to an XML Schema target namespace. Interface, binding and service names that we define in our WSDL 2.0 document will be associated with the WSDL 2.0 target namespace, and thus will be distinguishable from similar names in a different WSDL 2.0 target namespace. (This will become important if using WSDL 2.0's import or interface inheritance mechanisms.) </p><p>The value of the WSDL 2.0 target namespace must be an absolute URI. Furthermore, it should be dereferenceable to a WSDL 2.0 document that describes the Web service that the WSDL 2.0 target namespace is used to describe. For example, the GreatH owners should make the WSDL 2.0 document available from this URI. (And if a WSDL 2.0 description is split into multiple documents, then the WSDL 2.0 trget namespace should resolve to a master document that includes all the WSDL 2.0 documents needed for that service description.) However, there is no absolute requirement for this URI to be dereferenceable, so a WSDL 2.0 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 2.0 document from anywhere -- not necessarily an authoritative source. But by dereferencing the WSDL 2.0 target namespace URI, a user should be able to obtain an authoritative version. Since GreatH will be the owner of the service, the WSDL 2.0 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 2.0 target namespace URI, we can begin our WSDL 2.0 document as the following empty shell.</p><div class="exampleOuter">
! <p style="text-align: left" class="exampleHead"><a name="example-empty-shell"></a><i><span>Example 2-2. </span>An Initial Empty WSDL 2.0 Document</i></p>
<div class="exampleInner"><pre><?xml version="1.0" encoding="utf-8" ?>
<description
***************
*** 245,255 ****
</description></pre></div>
</div><div class="div3">
! <h4><a name="example-empty-shell-explanation"></a>2.2.1 Explanation of Example</h4><p></p><dl><dt class="label"><code><description</code></dt><dd><p>Every WSDL 2.0 2.0 document has a <code>description</code> element as its top-most element. This merely acts as a container for the rest of the WSDL 2.0 2.0 document, and is used to declare namespaces that will be used throughout the document.</p></dd><dt class="label"><code>xmlns="http://www.w3.org/2005/05/wsdl"</code></dt>
<dd>
<p>
! This is the XML namespace for WSDL 2.0 2.0 itself.
Because we have not defined a prefix for it, any
unprefixed elements are expected
! to be WSDL 2.0 2.0 elements (such as
the
<code>description</code>
--- 245,255 ----
</description></pre></div>
</div><div class="div3">
! <h4><a name="example-empty-shell-explanation"></a>2.2.1 Explanation of Example</h4><p></p><dl><dt class="label"><code><description</code></dt><dd><p>Every WSDL 2.0 document has a <code>description</code> element as its top-most element. This merely acts as a container for the rest of the WSDL 2.0 document, and is used to declare namespaces that will be used throughout the document.</p></dd><dt class="label"><code>xmlns="http://www.w3.org/2005/05/wsdl"</code></dt>
<dd>
<p>
! This is the XML namespace for WSDL 2.0 itself.
Because we have not defined a prefix for it, any
unprefixed elements are expected
! to be WSDL 2.0 elements (such as
the
<code>description</code>
***************
*** 633,639 ****
<div class="div2">
! <h3><a name="component-model"></a>3.3 WSDL 2.0 Component Model</h3><p>The WSDL 2.0 Infoset model above illustrates the required structure of a WSDL 2.0 document, using the XML Infoset. However, the WSDL 2.0 language also imposes many semantic constraints over and above structural conformance to this XML Infoset. In order to precisely describe these constraints, and as an aid in precisely defining the meaning of each WSDL 2.0 document, the WSDL 2.0 specification defines a <em>component model</em> 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. The following diagram gives an overview of the WSDL 2.0 components and their containment hiearchy.
! <div class="figure" style="text-align: center"><br><img src="images/WSDL20Components.png" alt="WSDL 2.0 Components Containment Hiearchy"><p style="text-align:left"><i><span>Figure 3-2. </span>WSDL 2.0 Components Containment Hiearchy</i></p><br></div></p>
--- 633,639 ----
<div class="div2">
! <h3><a name="component-model"></a>3.3 WSDL 2.0 Component Model</h3><p>The WSDL 2.0 Infoset model above illustrates the required structure of a WSDL 2.0 document, using the XML Infoset. However, the WSDL 2.0 language also imposes many semantic constraints over and above structural conformance to this XML Infoset. In order to precisely describe these constraints, and as an aid in precisely defining the meaning of each WSDL 2.0 document, the WSDL 2.0 specification defines a <em>component model</em> 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. The following diagram gives an overview of the WSDL 2.0 components and their containment hierarchy.
! <div class="figure" style="text-align: center"><br><img src="images/WSDL20Components.png" alt="WSDL 2.0 Components Containment hierarchy"><p style="text-align:left"><i><span>Figure 3-2. </span>WSDL 2.0 Components Containment hierarchy</i></p><br></div></p>
***************
*** 659,663 ****
element. The effect of the
<code>include</code>
! element is cummulative so that if document A includes document B
and document B includes document C, then the components defined
by document A consist of those whose definitions are contained
--- 659,663 ----
element. The effect of the
<code>include</code>
! element is cumulative so that if document A includes document B
and document B includes document C, then the components defined
by document A consist of those whose definitions are contained
***************
*** 968,972 ****
</p>
! <p>Let's say the GreatH hotel wants to maintain a a standard message log operation for all received messages. It wants this operation to be reusable across the whole reservation system, so each service will send out, for potential use of a logging service,
the content of each message it receives together with a timestamp and the originator of the message. One way to meet such requirement is to define the log operation in an interface which can be inherited by other interfaces. Assuming a <code>messageLog</code> element is already defined in the ghns namespace with the required content, the inheritance use case is illustrated in the following example. As a result of the inheritance, the <code>reservationInterface</code> now contains two operations: <code>opCheckAvailability</code> and <code>opLogMessage</code></p>
--- 968,972 ----
</p>
! <p>Let's say the GreatH hotel wants to maintain a standard message log operation for all received messages. It wants this operation to be reusable across the whole reservation system, so each service will send out, for potential use of a logging service,
the content of each message it receives together with a timestamp and the originator of the message. One way to meet such requirement is to define the log operation in an interface which can be inherited by other interfaces. Assuming a <code>messageLog</code> element is already defined in the ghns namespace with the required content, the inheritance use case is illustrated in the following example. As a result of the inheritance, the <code>reservationInterface</code> now contains two operations: <code>opCheckAvailability</code> and <code>opLogMessage</code></p>
***************
*** 1070,1074 ****
<p>An optional <code>style</code> attribute whose value is a list of absolute URIs. Each URI identifies a certain set of rules that were followed in defining this <code>operation</code>. It is an error if a particular style is indicated, but the associated rules are not followed. [<cite><a href="#WSDL-PART2">WSDL 2.0 Adjuncts</a></cite>] defines a set of styles, including</p>
<ul>
! <li><p>RPC Style.The RPC style is selected when the <code>style</code> is assigned the value http://www.w3.org/2005/05/wsdl/style/rpc. It places restrictions for Remote Procedure Call-types of interactions. </p></li>
<li><p>URI Style. The URI style is selected when the <code>style</code> is assigned the value http://www.w3.org/2005/05/wsdl/style/uri. It places restrictions on message definitions so they may be serialized into something like HTTP URL encoded.</p></li>
<li><p>The Multipart style. The Multipart style is selected when the <code>style</code> is assigned the value http://www.w3.org/2005/05/wsdl/style/multipart. In the HTTP binding, for XForm clients, a message must be defined following the Multipart style and serialized as "Multipart/form-data". </p> </li>
--- 1070,1074 ----
<p>An optional <code>style</code> attribute whose value is a list of absolute URIs. Each URI identifies a certain set of rules that were followed in defining this <code>operation</code>. It is an error if a particular style is indicated, but the associated rules are not followed. [<cite><a href="#WSDL-PART2">WSDL 2.0 Adjuncts</a></cite>] defines a set of styles, including</p>
<ul>
! <li><p>RPC Style. The RPC style is selected when the <code>style</code> is assigned the value http://www.w3.org/2005/05/wsdl/style/rpc. It places restrictions for Remote Procedure Call-types of interactions. </p></li>
<li><p>URI Style. The URI style is selected when the <code>style</code> is assigned the value http://www.w3.org/2005/05/wsdl/style/uri. It places restrictions on message definitions so they may be serialized into something like HTTP URL encoded.</p></li>
<li><p>The Multipart style. The Multipart style is selected when the <code>style</code> is assigned the value http://www.w3.org/2005/05/wsdl/style/multipart. In the HTTP binding, for XForm clients, a message must be defined following the Multipart style and serialized as "Multipart/form-data". </p> </li>
***************
*** 1474,1478 ****
<h3><a name="adv-extensibility"></a>7.1 Extensibility</h3>
<p>WSDL 2.0 provides two extensibility mechanisms: an open content model, which allows XML elements and attributes from other (non-WSDL 2.0) XML namespaces to be interspersed in a WSDL 2.0 document; and <a href="wsdl20.html#Feature">Features</a> and <a href="wsdl20.html#Property">Properties</a>. Both mechanisms use URIs to identify the semantics of the extensions. For extension XML elements and attributes, the namespace URI of the extension element or attribute acts as an unambiguous name for the semantics of that extension. For Features and Properties, the Feature or Property is named by a URI.</p><p>In either case, the URI that identifies the semantics of an extension should be dereferenceable to a document that describes the semantics of that extension. As of this writing, there is no generally accepted standard for what kind of document that should be. However, the <a href="http://www.w3.org/2001/tag/">W3C TAG</a> has been discussing the issue (see TAG issue <a href="http://www.w3.org/2001/tg/issues.html?type=1#namespaceDocument-8">namespaceDocument-8</a>) and is likely to provide guidance at some point.</p><div class="div3">
! <h4><a name="adv-optional-versus-required"></a>7.1.1 Optional Versus Required Extensions</h4><p>Extensions can either be required or optional.</p><p>An <em>optional</em> extension is one that the client may either engage or ignore, entirely at its discretion, and is signaled by attribute <code>wsdl:required="false"</code> or the absence of the <code>wsdl:required</code> attribute (because it defaults to false). Thus, a WSDL 2.0 processor, acting on behalf of the client, that encounters an unknown optional extension can safely ignore it and continue to process the WSDL 2.0 document. However, it is important to stress that optional extensions are only optional to the <em>client</em> -- not the service. A service must support all optional and required extensions that it advertises in its WSDL 2.0 document. </p><p>A <em>required</em> extension is one that must be supported and engaged by the client in order for the interaction to procede properly, and is signaled by attribute <code>wsdl:required="true"<code>. If a WSDL 2.0 processor, acting on behalf of the client, encounters a required extension that it does not recognize or does not support, then it cannot safely continue to process the WSDL 2.0 document. In most practical cases, this is likely to mean that the processor will require manual intervention to deal with the extension. For example, a client developer might manually provide an implementation for the required extension to the WSDL 2.0 processor. </p></div>
--- 1474,1478 ----
<h3><a name="adv-extensibility"></a>7.1 Extensibility</h3>
<p>WSDL 2.0 provides two extensibility mechanisms: an open content model, which allows XML elements and attributes from other (non-WSDL 2.0) XML namespaces to be interspersed in a WSDL 2.0 document; and <a href="wsdl20.html#Feature">Features</a> and <a href="wsdl20.html#Property">Properties</a>. Both mechanisms use URIs to identify the semantics of the extensions. For extension XML elements and attributes, the namespace URI of the extension element or attribute acts as an unambiguous name for the semantics of that extension. For Features and Properties, the Feature or Property is named by a URI.</p><p>In either case, the URI that identifies the semantics of an extension should be dereferenceable to a document that describes the semantics of that extension. As of this writing, there is no generally accepted standard for what kind of document that should be. However, the <a href="http://www.w3.org/2001/tag/">W3C TAG</a> has been discussing the issue (see TAG issue <a href="http://www.w3.org/2001/tg/issues.html?type=1#namespaceDocument-8">namespaceDocument-8</a>) and is likely to provide guidance at some point.</p><div class="div3">
! <h4><a name="adv-optional-versus-required"></a>7.1.1 Optional Versus Required Extensions</h4><p>Extensions can either be required or optional.</p><p>An <em>optional</em> extension is one that the client may either engage or ignore, entirely at its discretion, and is signaled by attribute <code>wsdl:required="false"</code> or the absence of the <code>wsdl:required</code> attribute (because it defaults to false). Thus, a WSDL 2.0 processor, acting on behalf of the client, that encounters an unknown optional extension can safely ignore it and continue to process the WSDL 2.0 document. However, it is important to stress that optional extensions are only optional to the <em>client</em> -- not the service. A service must support all optional and required extensions that it advertises in its WSDL 2.0 document. </p><p>A <em>required</em> extension is one that must be supported and engaged by the client in order for the interaction to proceed properly, and is signaled by attribute <code>wsdl:required="true"<code>. If a WSDL 2.0 processor, acting on behalf of the client, encounters a required extension that it does not recognize or does not support, then it cannot safely continue to process the WSDL 2.0 document. In most practical cases, this is likely to mean that the processor will require manual intervention to deal with the extension. For example, a client developer might manually provide an implementation for the required extension to the WSDL 2.0 processor. </p></div>
***************
*** 1584,1593 ****
<h3><a name="adv-MEP"></a>7.3 Defining New MEPs</h3>
! <p>As we mentioned in <a href="#more-interfaces-meps"><b>5.4.3 Understanding Message Exchange Patterns (MEPs)</b></a>, even though the 8 MEPs defined by WSDL 2.0 are intented to cover most of the common use cases, there are situations that require new MEPs to be defined. In this section, we will explain how new MEPs can be defined to address special business requirements.</p>
<p>Following the wild success of its reservation service, GreatH discovered
that it could radically increase tourist interest by supplying information
on weather conditions, both to travel agents and to the general touring
! public. This produced a challenge for the service implementors: how could
this information be supplied to interested parties without requiring
knowledge of web service technology specifically, and of computers
--- 1584,1593 ----
<h3><a name="adv-MEP"></a>7.3 Defining New MEPs</h3>
! <p>As we mentioned in <a href="#more-interfaces-meps"><b>5.4.3 Understanding Message Exchange Patterns (MEPs)</b></a>, even though the 8 MEPs defined by WSDL 2.0 are intended to cover most of the common use cases, there are situations that require new MEPs to be defined. In this section, we will explain how new MEPs can be defined to address special business requirements.</p>
<p>Following the wild success of its reservation service, GreatH discovered
that it could radically increase tourist interest by supplying information
on weather conditions, both to travel agents and to the general touring
! public. This produced a challenge for the service implementers: how could
this information be supplied to interested parties without requiring
knowledge of web service technology specifically, and of computers
***************
*** 1997,2001 ****
<li>
<p>
! With an incompatible change, the client receives a new version of the interface description and is expected to adjust to the new interface before old interface is terminated. Either the service will need to continue to support both versions of the interface during the hand over period, or the service and the clients are co-ordinated to change at the same time. An alternative is for the
client to continue until it encounters an error, at which point it uses the new version of the interface.
</p>
--- 1997,2001 ----
<li>
<p>
! With an incompatible change, the client receives a new version of the interface description and is expected to adjust to the new interface before old interface is terminated. Either the service will need to continue to support both versions of the interface during the hand over period, or the service and the clients are coordinated to change at the same time. An alternative is for the
client to continue until it encounters an error, at which point it uses the new version of the interface.
</p>
***************
*** 2752,2756 ****
<p>
! In the preceeding example, there was a single
endpoint associated with each Reservation Detail
Web service. Suppose GreatH hotel decided to
--- 2752,2756 ----
<p>
! In the preceding example, there was a single
endpoint associated with each Reservation Detail
Web service. Suppose GreatH hotel decided to
***************
*** 2764,2768 ****
which are each of type <code>reservationDetailsSOAPEndpointType</code>
and therefore contain the address of an endpoint that implements
! the <code>wdetails:reservationDetailsSOAPBinding</code> bindng.
</p>
<p>
--- 2764,2768 ----
which are each of type <code>reservationDetailsSOAPEndpointType</code>
and therefore contain the address of an endpoint that implements
! the <code>wdetails:reservationDetailsSOAPBinding</code> binding.
</p>
<p>
***************
*** 3210,3214 ****
service definitions. However, the namespaces are
not automatically visible to the other inline
! schemas. Each inline schema must explictly
import any other namespace it references. The
<code>schemaLocation</code>
--- 3210,3214 ----
service definitions. However, the namespaces are
not automatically visible to the other inline
! schemas. Each inline schema must explicitly
import any other namespace it references. The
<code>schemaLocation</code>
Received on Friday, 17 June 2005 23:32:41 UTC