- From: Kevin Liu via cvs-syncmail <cvsmail@w3.org>
- Date: Thu, 28 Apr 2005 00:29:34 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20
In directory hutz:/tmp/cvs-serv28817/ws/desc/wsdl20
Modified Files:
wsdl20-primer.html wsdl20-primer.xml
Log Message:
Fixed typos and minor editings
Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.68
retrieving revision 1.69
diff -C2 -d -r1.68 -r1.69
*** wsdl20-primer.xml 27 Apr 2005 23:27:47 -0000 1.68
--- wsdl20-primer.xml 28 Apr 2005 00:29:32 -0000 1.69
***************
*** 460,464 ****
</service>]]></eg>
! </example><div3 id="example-initial-service-explanation"><head>Explanation of Example</head><glist><gitem><label><code><service name="reservationService"</code></label><def><p>This defines a name for this service, which must be unique among service names in the WSDL target namespace. The name attribute is required. It allows URIs to be created that indentify components in WSDL 2.0 description. (See <emph>WSDL 2.0 Core Language</emph> <bibref ref="WSDL-PART1"/> appendix C <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-20040803/#wsdl-uri-references">URI References for WSDL constructs</xspecref>.)</p></def></gitem><gitem><label><code>interface="tns:reservationInterface"></code></label><def><p>This specifies the name of the previously defined interface that these service endpoints will support. </p></def></gitem><gitem><label><code><endpoint name="reservationEndpoint"</code></label><def><p>This defines an endpoint for the service, and a name for this endpoint, which must be unique withn this service. </p></def></gitem><gitem><label><code>binding="tns:reservationSOAPBinding"</code></label><def><p>This specifies the name of the previously defined binding to be used by this endpoint. </p></def></gitem><gitem><label><code>address ="http://greath.example.com/2004/reservation"/></code></label><def><p>This specifies the physical address at which this service can be accessed using the binding specified by the <att>binding</att> attribute.</p></def></gitem></glist><p>That's it! Well, almost. </p></div3></div2><div2 id="basics-documentation"><head>Documenting the Service</head><p>As we have seen, a WSDL 2.0 document is inherently only a <emph>partial</emph> description of a service. Although it captures the basic mechanics of interacting with the service -- the message types, transmission protocols, service location, etc. -- in general, additional documention will need to explain other application-level requirements for its use. For example, such documentation should explain the purpose ad use of the service, the meanings of all messages, constraints on their use, and the sequence in which operations should be invoked.</p><p>The <code>documentation</code> element allows the WSDL author to include some human-readable documentation inside a WSDL 2.0 document. It is also a convenient place to reference any additional external documentation that a client developer may need in order to use the service. It can appear in a number of places in a WSDL 2.0 document (see <specref ref="wsdl-infoset-diagram"/>), though in this example we have only demonstrated its use at the beginning.</p><example id="example-initial-documentation">
<head>Documenting the GreatH Service</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
--- 460,466 ----
</service>]]></eg>
! </example><div3 id="example-initial-service-explanation"><head>Explanation of Example</head><glist><gitem><label><code><service name="reservationService"</code></label><def><p>This defines a name for this service, which must be unique among service names in the WSDL target namespace. The name attribute is required. It allows URIs to be created that identify components in WSDL 2.0 description. (See <emph>WSDL 2.0 Core Language</emph> <bibref ref="WSDL-PART1"/> appendix C <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-20040803/#wsdl-uri-references">URI References for WSDL constructs</xspecref>.)</p></def></gitem><gitem><label><code>interface="tns:reservationInterface"></code></label><def><p>This specifies the name of the previously defined interface that these service endpoints will support. </p></def></gitem><gitem><label><code><endpoint name="reservationEndpoint"</code></label><def><p>This defines an endpoint for the service, and a name for this endpoint, which must be unique withinthis service. </p></def></gitem><gitem><label><code>binding="tns:reservationSOAPBinding"</code></label><def><p>This specifies the name of the previously defined binding to be used by this endpoint. </p></def></gitem><gitem><label><code>address ="http://greath.example.com/2004/reservation"/></code></label><def><p>This specifies the physical address at which this service can be accessed using the binding specified by the <att>binding</att> attribute.</p></def></gitem></glist><p>That's it! Well, almost. </p></div3></div2>
!
! <div2 id="basics-documentation"><head>Documenting the Service</head><p>As we have seen, a WSDL 2.0 document is inherently only a <emph>partial</emph> description of a service. Although it captures the basic mechanics of interacting with the service -- the message types, transmission protocols, service location, etc. -- in general, additional documentation will need to explain other application-level requirements for its use. For example, such documentation should explain the purpose and use of the service, the meanings of all messages, constraints on their use, and the sequence in which operations should be invoked.</p><p>The <code>documentation</code> element allows the WSDL author to include some human-readable documentation inside a WSDL 2.0 document. It is also a convenient place to reference any additional external documentation that a client developer may need in order to use the service. It can appear in a number of places in a WSDL 2.0 document (see <specref ref="wsdl-infoset-diagram"/>) though in this example we have only demonstrated its use at the beginning.</p><example id="example-initial-documentation">
<head>Documenting the GreatH Service</head>
<eg><![CDATA[<?xml version="1.0" encoding="utf-8" ?>
***************
*** 724,729 ****
<div2 id="more-interfaces-inheritance">
<head>Interface Inheritance</head>
! <p>The optional <att>extends</att> attribute allows an interface to extend or inherit from one or more other interfaces. In such cases the interface contains the operations of the interfaces it extends, along with any operations it defines directly. Two things about extending interfaces deserve some attention. </p><p>First, an inheritance loop (or infinite recursion) is prohibited: the interfaces that a given interface extends MUST NOT themselves extend that interface either directly or indirectly. </p><p>Second, we must explain what happens when operations from two different interfaces have the same target namespace and operation name. There are two cases: either the component models of the operations are the same, or they are different. If the component models are the same (per the component comparison algorithm defined in WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> "<xspecref href="http://www.w3.org/TR/wsdl20-primer#compequiv">Equivalence of Components</xspecref>") then they are considered to b the same operation, i.e., they are collapsed into a single operation, and the fact that they were included more than once is not considered an error. (For operations, component equivalence basically means that the two operations have the same set of attributes and descendents.) In the second case, if two operations have the same name in the same WSDL target namespace but are not equivalent, then it is an error. For the above reason, it is considered good practice to ensure that all operations within the same target namespace are named uniquely. </p><p>Finally, since faults, features and properties can also be defined as children of the <code>interface</code> element (as descrbed later), the same name-collision rules apply to those constructs.</p>
! <p>Now let's have a look at the element children of <code>interface</code>, beginning with <code>fault</code>. In the next section, we will provide an example of leveraging interface inheritance for reusing faults and operations across multiple interfaces. </p>
</div2>
--- 726,731 ----
<div2 id="more-interfaces-inheritance">
<head>Interface Inheritance</head>
! <p>The optional <att>extends</att> attribute allows an interface to extend or inherit from one or more other interfaces. In such cases the interface contains the operations of the interfaces it extends, along with any operations it defines directly. Two things about extending interfaces deserve some attention. </p><p>First, an inheritance loop (or infinite recursion) is prohibited: the interfaces that a given interface extends MUST NOT themselves extend that interface either directly or indirectly. </p><p>Second, we must explain what happens when operations from two different interfaces have the same target namespace and operation name. There are two cases: either the component models of the operations are the same, or they are different. If the component models are the same (per the component comparison algorithm defined in WSDL 2.0 Part 1 <bibref ref="WSDL-PART1"/> "<xspecref href="http://www.w3.org/TR/wsdl20-primer#compequiv">Equivalence of Components</xspecref>") then they are considered to b the same operation, i.e., they are collapsed into a single operation, and the fact that they were included more than once is not considered an error. (For operations, component equivalence basically means that the two operations have the same set of attributes and descendents.) In the second case, if two operations have the same name in the same WSDL target namespace but are not equivalent, then it is an error. For the above reason, it is considered good practice to ensure that all operations within the same target namespace are named uniquely. </p><p>Finally, since faults, features and properties can also be defined as children of the <code>interface</code> element (as described in the following sections), the same name-collision rules apply to those constructs. In the next section, we will provide an example of leveraging interface inheritance for reusing faults and operations across multiple interfaces.</p>
! <p>Now let's have a look at the element children of <code>interface</code>, beginning with <code>fault</code>. </p>
</div2>
***************
*** 733,737 ****
<p>Faults are very similar to messages and can be viewed as a special kind of
message. Both faults and messages may carry a payload that is normally described
! by an element declaration. However, WSDL treats faults and messages slighly
differently. The messages of an operation directly refer to their element
declaration, however the faults of an operation indirectly refer to their
--- 735,739 ----
<p>Faults are very similar to messages and can be viewed as a special kind of
message. Both faults and messages may carry a payload that is normally described
! by an element declaration. However, WSDL treats faults and messages slightly
differently. The messages of an operation directly refer to their element
declaration, however the faults of an operation indirectly refer to their
***************
*** 747,754 ****
<p>The <code>fault</code> element has a required <att>name</att> attribute that must be unique within the WSDL document's target namespace, and permits it to be referenced from operation declarations. The optional <att>element</att> attribute can be used to indicate a schema for the content or payload of the fault message. Its value should be the QName of a global element defined in the <code>types</code> section. Please note when other type systems are used to define the schema for a fault message, additional attributes may need to be defined via WSDL's attribute extension mechanism to allow the schema to be associated with the fault.</p>
! <p>The following example shows one way to leverage interface inheritance for reusing faults and operations across multiple interfaces. In most cases, faults are defined under each inidividual interface like in the initial example @@TODO:Add reference to example 2-1@@. But some system may require a set of standard fault messages to be reused across a system. For example, let's say the GreatH hotel wants to maintain a set of standard fault messages and a standard error log operation for credit card and data validation errors that are reusable across the whole reservation system. One way to meet such requirement is to define the standard faults and the log operation in an interface which can be inherited by other interfaces. </p>
<example id="example-faults">
! <head>Reusalbe Faults and Interface Inheritance</head>
<eg xml:space="preserve">
--- 749,756 ----
<p>The <code>fault</code> element has a required <att>name</att> attribute that must be unique within the WSDL document's target namespace, and permits it to be referenced from operation declarations. The optional <att>element</att> attribute can be used to indicate a schema for the content or payload of the fault message. Its value should be the QName of a global element defined in the <code>types</code> section. Please note when other type systems are used to define the schema for a fault message, additional attributes may need to be defined via WSDL's attribute extension mechanism to allow the schema to be associated with the fault.</p>
! <p>The following example shows one way to leverage interface inheritance for reusing faults and operations across multiple interfaces. In most cases, faults are defined under each individual interface like in the initial example @@TODO:Add reference to example 2-1@@. But some system may require a set of standard fault messages to be reused across a system. For example, let's say the GreatH hotel wants to maintain a set of standard fault messages and a standard error log operation for credit card and data validation errors that are reusable across the whole reservation system. One way to meet such requirement is to define the standard faults and the log operation in an interface which can be inherited by other interfaces. </p>
<example id="example-faults">
! <head>Reusable Faults and Interface Inheritance</head>
<eg xml:space="preserve">
***************
*** 839,843 ****
<p>Depends on how the first message in the MEP is initiated, the 8 WSDL MEPs may be grouped into two groups: 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 in this primer).</p>
! <p> A frequently asked question about out-bound MEPs is how a service knows where to send the message. Services using out-bound MEPs are typically part of large scale intergration systems that rely on mapping and routing facilities. In such systems, out-bound MEPs are useful for abstractly specifing the functionality of a service, including its requirements for potential customers, while endpoint address information can be provided at deployment or runtime by integration infrastructure. For example, the GreatH hotel reservation system may require that everytime a customer interacts with the system to check availability, data about the customer must be logged by a CRM system. At design time, it's unknown which particular CRM system would be used together with the reservation system. To address this requirement, we may change the "reservationInterface" in <specref ref="example-initial"/> to include an out-bound logInquiry operation. This logInquiry operation advertises to potential service clients thatcustomer data will be made available by the reservation service at run time. When the reservation service is deployed to GreatH's IT landscape, appropriate configuration time and run time infrastructure will help determine which CRM system will get the customer data and log it appropriately. It's worth noting that in addition to being used by a CRM system for customer management purpose, the same data may also be used by a system performance analysis tool for different purpose. Providing an out-bound operation in the reservation service enables loose coupling and so improves the overall GreatH IT landscape's flexbility and scalability. </p>
<example id="example-outbound-operation">
--- 841,845 ----
<p>Depends on how the first message in the MEP is initiated, the 8 WSDL MEPs may be grouped into two groups: 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 in this primer).</p>
! <p> A frequently asked question about out-bound MEPs is how a service knows where to send the message. Services using out-bound MEPs are typically part of large scale integration systems that rely on mapping and routing facilities. In such systems, out-bound MEPs are useful for abstractly specifying the functionality of a service, including its requirements for potential customers, while endpoint address information can be provided at deployment or runtime by integration infrastructure. For example, the GreatH hotel reservation system may require that every time a customer interacts with the system to check availability, data about the customer must be logged by a CRM system. At design time, it's unknown which particular CRM system would be used together with the reservation system. To address this requirement, we may change the "reservationInterface" in <specref ref="example-initial"/> to include an out-bound logInquiry operation. This logInquiry operation advertises to potential service clients tha customer data will be made available by the reservation service at run time. When the reservation service is deployed to GreatH's IT landscape, appropriate configuration time and run time infrastructure will help determine which CRM system will get the customer data and log it appropriately. It's worth noting that in addition to being used by a CRM system for customer management purpose, the same data may also be used by a system performance analysis tool for different purpose. Providing an out-bound operation in the reservation service enables loose coupling and so improves the overall GreatH IT landscape's flexibility and scalability. </p>
<example id="example-outbound-operation">
***************
*** 914,918 ****
<div2 id="more-bindings-reusable"><head>Reusable Bindings</head><p>A binding can either be reusable (applicable to any
interface) or non-reusable (specified for a particular interface). Non-reusable bindings may be specified at the granularity of the interface (assuming the binding extension provides suitable defaulting rules), or on a per-operation basis if needed. A non-reusable binding was demonstrated in <specref ref="basics-binding"/>.</p><p>To define a reusable binding, the <code>binding</code> element simply omits the <code>interface</code> attribute and omits specifying any
! operation-specific and fault-specific binding details. Endpoints can later refer to a resuable binding in the same manner as for a non-reusable binding. Thus, a reusable binding becomes associated with a particular interface when it is referenced from an endpoint, because an endpoint is part of a service, and the service specifies a particular interface that it implements. Since a reusable binding does not specify an interface, reusable bindings cannot specify operation-specific details. Therefore, reusable bindings can only be defined using binding extensions that have suitable defaulting rules, such that the binding information only needs to be explicitly supplied at the interface level.</p></div2><div2 id="more-bindings-faults">
<head>Binding Faults</head>
--- 916,920 ----
<div2 id="more-bindings-reusable"><head>Reusable Bindings</head><p>A binding can either be reusable (applicable to any
interface) or non-reusable (specified for a particular interface). Non-reusable bindings may be specified at the granularity of the interface (assuming the binding extension provides suitable defaulting rules), or on a per-operation basis if needed. A non-reusable binding was demonstrated in <specref ref="basics-binding"/>.</p><p>To define a reusable binding, the <code>binding</code> element simply omits the <code>interface</code> attribute and omits specifying any
! operation-specific and fault-specific binding details. Endpoints can later refer to a reusable binding in the same manner as for a non-reusable binding. Thus, a reusable binding becomes associated with a particular interface when it is referenced from an endpoint, because an endpoint is part of a service, and the service specifies a particular interface that it implements. Since a reusable binding does not specify an interface, reusable bindings cannot specify operation-specific details. Therefore, reusable bindings can only be defined using binding extensions that have suitable defaulting rules, such that the binding information only needs to be explicitly supplied at the interface level.</p></div2><div2 id="more-bindings-faults">
<head>Binding Faults</head>
***************
*** 949,953 ****
! <p>The WSDL 2.0 SOAP Binding Extension (see WSDL 2.0 Part 2 <bibref ref="WSDL-PART2"/>) was primarily designed to support the features of SOAP 1.2 <bibref ref="SOAP12-PART1"/>. However, for backwards compatibility, it also provides some support for SOAP 1.1 <bibref ref="SOAP11"/>. </p><p>An example using the WSDL 2.0 SOAP binding extension was already presented in <specref ref="basics-binding"/>, but some additional points are worth mentioning:<ulist><item><p>Because the same binding extension is used for both SOAP 1.2 and SOAP 1.1, a <code>wsoap:version</code> attribute is provided to allow you to indicate which version of SOAP you want. If this attribute is not specified, it defaults to SOAP 1.2.</p></item><item><p>The WSDL 2.0 SOAP binding extension defines a set of default rules, so that bindings can be specified at the interface level or at the operation level (or both), with the operation level taking precedence. However, it does not define default binding rules for faults. Thus, if a iven interface defines any faults, then corresponding binding infomation must be explicitly provided for each such fault.</p></item><item><p>If HTTP is used as the underlying protocol, then the binding can (and should) control whether each operation will use HTTP GET or POST. (See <specref ref="adv-get-vs-post"/>.)</p></item></ulist></p><p>Here is an example that illustrates both a SOAP 1.2 binding (as seen before) and a SOAP 1.1 binding.</p><example id="example-binding-soap">
<head>SOAP 1.2 and SOAP 1.1 Bindings</head>
--- 951,955 ----
! <p>The WSDL 2.0 SOAP Binding Extension (see WSDL 2.0 Part 2 <bibref ref="WSDL-PART2"/>) was primarily designed to support the features of SOAP 1.2 <bibref ref="SOAP12-PART1"/>. However, for backwards compatibility, it also provides some support for SOAP 1.1 <bibref ref="SOAP11"/>. </p><p>An example using the WSDL 2.0 SOAP binding extension was already presented in <specref ref="basics-binding"/>, but some additional points are worth mentioning:<ulist><item><p>Because the same binding extension is used for both SOAP 1.2 and SOAP 1.1, a <code>wsoap:version</code> attribute is provided to allow you to indicate which version of SOAP you want. If this attribute is not specified, it defaults to SOAP 1.2.</p></item><item><p>The WSDL 2.0 SOAP binding extension defines a set of default rules, so that bindings can be specified at the interface level or at the operation level (or both), with the operation level taking precedence. However, it does not define default binding rules for faults. Thus, if a iven interface defines any faults, then corresponding binding information must be explicitly provided for each such fault.</p></item><item><p>If HTTP is used as the underlying protocol, then the binding can (and should) control whether each operation will use HTTP GET or POST. (See <specref ref="adv-get-vs-post"/>.)</p></item></ulist></p><p>Here is an example that illustrates both a SOAP 1.2 binding (as seen before) and a SOAP 1.1 binding.</p><example id="example-binding-soap">
<head>SOAP 1.2 and SOAP 1.1 Bindings</head>
***************
*** 1061,1065 ****
</gitem><gitem>
<label><code>xmlns:whttp="http://www.w3.org/@@@@/@@/wsdl/http" ></code></label><def><p>This defines the namespace prefix for elements and attributes defined by the WSDL 2.0 HTTP binding extension.</p></def></gitem><gitem><label><code>whttp:methodDefault="GET"></code></label><def><p>The default method for operations in this interface will be HTTP GET.</p></def></gitem><gitem><label><code>whttp:location="{checkInDate}" ></code></label><def><p>The <code>whttp:location</code> attribute specifies a pattern for serializing input message instance data into the path component of the request URI. The default binding rules for HTTP specify that the default input
! serialization for GET is <code>application/x-www-form-urlencoded</code>. Curly braces are used to specify the name of a schema type in the input message schema, which determines what input instance data will be inserted into the path component of the request URI. The curly brace-enclosed name will be replaced with instance data in constructing the path component. Remaining input instance data (not specified by <code>whttp:location</code>) will either be serialized into the query string portion of the URI or into the message body, as follows: if a "/" is appended to a curly brace-enclosed type name, then any remaining input message instance data will be serialized into the message body. Otherwise it will be serialized into query parameters.</p><p>Thus, in this example, each of the elements in the <code>tCheckAvailability</code> type will be serialized into the query parameters.A sample resulting URI for would therefore be
<code>http://greath.example.com/2004/5-5-5?checkOutDate=6-6-5&roomType=foo</code>. </p></def></gitem></glist></p>
--- 1063,1067 ----
</gitem><gitem>
<label><code>xmlns:whttp="http://www.w3.org/@@@@/@@/wsdl/http" ></code></label><def><p>This defines the namespace prefix for elements and attributes defined by the WSDL 2.0 HTTP binding extension.</p></def></gitem><gitem><label><code>whttp:methodDefault="GET"></code></label><def><p>The default method for operations in this interface will be HTTP GET.</p></def></gitem><gitem><label><code>whttp:location="{checkInDate}" ></code></label><def><p>The <code>whttp:location</code> attribute specifies a pattern for serializing input message instance data into the path component of the request URI. The default binding rules for HTTP specify that the default input
! serialization for GET is <code>application/x-www-form-urlencoded</code>. Curly braces are used to specify the name of a schema type in the input message schema, which determines what input instance data will be inserted into the path component of the request URI. The curly brace-enclosed name will be replaced with instance data in constructing the path component. Remaining input instance data (not specified by <code>whttp:location</code>) will either be serialized into the query string portion of the URI or into the message body, as follows: if a "/" is appended to a curly brace-enclosed type name, then any remaining input message instance data will be serialized into the message body. Otherwise it will be serialized into query parameters.</p><p>Thus, in this example, each of the elements in the <code>tCheckAvailability</code> type will be serialized into the query parameters. A sample resulting URI for would therefore be
<code>http://greath.example.com/2004/5-5-5?checkOutDate=6-6-5&roomType=foo</code>. </p></def></gitem></glist></p>
***************
*** 1094,1098 ****
<head>Features and Properties</head>
! <p>After a few successful trials of the reservation service, GreatH decides that it is time to make the makeReservation operation secure, so that sensitive credit-card information is not being sent across the public network in a snoopable fashion. We will do this using the WSDL 2.0 Features and Properties mechanisms <bibref ref="WSDL-PART1"/>, which is modeled after the Features and Properties mechanism defined in SOAP 1.2 <bibref ref="SOAP12-PART1"/>.</p><p>To facilitate presentation, this section will assume the existence of a hypothetical security feature named "<code>http://features.example.com/2005/securityFeature</code>", which defines, in the abstract, the idea of message confidentiality. This feature has an associated property, named "<code>http://features.example.com/2005/securityFeature/securityLevel</code>", which defines various safety levels (from 0 meaning cleartext, all the way through 10, involving highly complex cryptographic algorithms with keys in the tens of thousands of bits). We also assume that a SOAP module, named "<code>http://features.example.com/2005/modules/Security</code>", has been defined, which implements the security feature described above.</p><p>GreatH has chosen an abstract security feature which is standard in the fictitious hotels community, and has integrated both a SOAP module and a new secure HTTP binding into its infrastructure – both of which implement the security feature (the SOAP module does this inside the SOAP envelope using headers, and the secure binding does it at the transport layer). Now they'd like to advertise and control the usage of these extensions using WSDL 2.0.</p>
<div3 id="adv-FP-soap-modules"><head>SOAP Modules</head><p>The first step GreatH takes is to require the usage of the SOAP module in their normal SOAP/HTTP endpoint, which looks like this:</p><example id="example-fp-requiring-soap-module">
--- 1096,1100 ----
<head>Features and Properties</head>
! <p>After a few successful trials of the reservation service, GreatH decides that it is time to make the makeReservation operation secure, so that sensitive credit-card information is not being sent across the public network in a snoopable fashion. We will do this using the WSDL 2.0 Features and Properties mechanisms <bibref ref="WSDL-PART1"/>, which is modeled after the Features and Properties mechanism defined in SOAP 1.2 <bibref ref="SOAP12-PART1"/>.</p><p>To facilitate presentation, this section will assume the existence of a hypothetical security feature named "<code>http://features.example.com/2005/securityFeature</code>", which defines, in the abstract, the idea of message confidentiality. This feature has an associated property, named "<code>http://features.example.com/2005/securityFeature/securityLevel</code>", which defines various safety levels (from 0 meaning clear text, all the way through 10, involving highly complex cryptographic algorithms with keys in the tens of thousands of bits). We also assume that a SOAP module, named "<code>http://features.example.com/2005/modules/Security</code>", has been defined, which implements the security feature described above.</p><p>GreatH has chosen an abstract security feature which is standard in the fictitious hotels community, and has integrated both a SOAP module and a new secure HTTP binding into its infrastructure – both of which implement the security feature (the SOAP module does this inside the SOAP envelope using headers, and the secure binding does it at the transport layer). Now they'd like to advertise and control the usage of these extensions using WSDL 2.0.</p>
<div3 id="adv-FP-soap-modules"><head>SOAP Modules</head><p>The first step GreatH takes is to require the usage of the SOAP module in their normal SOAP/HTTP endpoint, which looks like this:</p><example id="example-fp-requiring-soap-module">
***************
*** 1354,1358 ****
respect: that versioning is difficult, but you SHOULD
anticipate and plan for change.</p><p>The draft finding on Versioning and Extensibility details two key
! approaches to versioning:</p><ulist><item><p>comaptible evolution; and</p></item><item><p>big bang.</p></item></ulist><div3 id="adv-versioning-compatible-evolution"><head>Compatible Evolution</head><p>In <emph>compatible evolution</emph>, designers are expected to limit changes to
those that are either backward or forward compatible, or both:</p><glist><gitem><label>Backward compatible</label><def><p>The receiver behaves
correctly if it receives a message in an <emph>older</emph> version of the interaction
--- 1356,1360 ----
respect: that versioning is difficult, but you SHOULD
anticipate and plan for change.</p><p>The draft finding on Versioning and Extensibility details two key
! approaches to versioning:</p><ulist><item><p>compatible evolution; and</p></item><item><p>big bang.</p></item></ulist><div3 id="adv-versioning-compatible-evolution"><head>Compatible Evolution</head><p>In <emph>compatible evolution</emph>, designers are expected to limit changes to
those that are either backward or forward compatible, or both:</p><glist><gitem><label>Backward compatible</label><def><p>The receiver behaves
correctly if it receives a message in an <emph>older</emph> version of the interaction
***************
*** 1508,1512 ****
<div2 id="adv-RPCstyle">
<head>RPC Style</head>
! <p>Section <specref ref="more-interfaces-op-attr"/> mentioned that the (optional) <code>style</code> attribute of an interface operation is used to indicate that the operation conforms to a particular pre-defined operation style, or set of constraints. Actually, if desired the <code>style</code> attribute can hold a list of URIs, indicating that the operation simultaneously conforms to multiple styles.</p><p>Operation styles are named using URIs, in order to be unambigous while still permitted new styles to be defined without requiring updates to the WSDL 2.0 language. WSDL 2.0 Part 2 <bibref ref="WSDL-PART2"/> defines three such operation styles; one of these is the RPC Style (<xspecref href="http://www.w3.org/2002/ws/desc/wsdl20-adjuncts#RPCStyle">RPC Style</xspecref>).</p><p>The <emph>RPC Style</emph> is designed to facilitate programming language
bindings to WSDL 2.0 constructs. It allows a WSDL 2.0 interface
operation to be easily mapped to a method or function signature, such as a method signature in
--- 1510,1514 ----
<div2 id="adv-RPCstyle">
<head>RPC Style</head>
! <p>Section <specref ref="more-interfaces-op-attr"/> mentioned that the (optional) <code>style</code> attribute of an interface operation is used to indicate that the operation conforms to a particular pre-defined operation style, or set of constraints. Actually, if desired the <code>style</code> attribute can hold a list of URIs, indicating that the operation simultaneously conforms to multiple styles.</p><p>Operation styles are named using URIs, in order to be unambiguous while still permitted new styles to be defined without requiring updates to the WSDL 2.0 language. WSDL 2.0 Part 2 <bibref ref="WSDL-PART2"/> defines three such operation styles; one of these is the RPC Style (<xspecref href="http://www.w3.org/2002/ws/desc/wsdl20-adjuncts#RPCStyle">RPC Style</xspecref>).</p><p>The <emph>RPC Style</emph> is designed to facilitate programming language
bindings to WSDL 2.0 constructs. It allows a WSDL 2.0 interface
operation to be easily mapped to a method or function signature, such as a method signature in
***************
*** 1590,1594 ****
<div2 id="adv-message-dispatch">
<head>Enabling Easy Message Dispatch</head>
! <p>Suppose a WSDL 2.0 document has two input-output operations and uses the same input message schema for both. When the service receives the input message, how will the service know which operation is supposed to be invoked? Although the data contained in a runtime message may be sufficient to distinguish between the operations, this can be a problem for WSDL 2.0 toolkits that are looking only at the message schema, rather than the actual messages. (For example, the toolkit may be operating at designtime, without access to the runtime messages.) This is the problem of <emph>dispatch</emph>. How can a WSDL 2.0 document be written to ensure easy message dispatch? Strategies include:</p>
<ulist><item><p><b>Use unique top-level elements</b>, i.e., ensure that the top-level elements declared in the message schemas are different for different operations. This is probably the most general solution, since it is guaranteed to provide a way to perform dispatch, without preventing toolkits from potentially using other dispatch techniques.</p></item><item><p><b>Include a required extension</b> that enables a particular dispatching convention. This approach makes the dispatching convention explicit, although it may not be supported by every WSDL toolkit. However, as explained in <specref ref="adv-optional-versus-required"/>, toolkits that do not natively support the extension could seek manual input, thus permitting a client developer to supply an appropriate module that implements the necessary extension. This strategy has thus permits future WSDL toolkits to support and process the extension automatically, while also ensuring that the extension will be handled properly by toolkits that re not yet able to process it automatically.</p></item></ulist>
<p>To ensure that client and service implementations can easily determine the interface operation under which a received message was sent (even though not every client or service may need to make such a determination), it is considered good practice to follow one of the above strategies when authoring WSDL 2.0 documents.</p>
--- 1592,1596 ----
<div2 id="adv-message-dispatch">
<head>Enabling Easy Message Dispatch</head>
! <p>Suppose a WSDL 2.0 document has two input-output operations and uses the same input message schema for both. When the service receives the input message, how will the service know which operation is supposed to be invoked? Although the data contained in a runtime message may be sufficient to distinguish between the operations, this can be a problem for WSDL 2.0 toolkits that are looking only at the message schema, rather than the actual messages. (For example, the toolkit may be operating at design time, without access to the runtime messages.) This is the problem of <emph>dispatch</emph>. How can a WSDL 2.0 document be written to ensure easy message dispatch? Strategies include:</p>
<ulist><item><p><b>Use unique top-level elements</b>, i.e., ensure that the top-level elements declared in the message schemas are different for different operations. This is probably the most general solution, since it is guaranteed to provide a way to perform dispatch, without preventing toolkits from potentially using other dispatch techniques.</p></item><item><p><b>Include a required extension</b> that enables a particular dispatching convention. This approach makes the dispatching convention explicit, although it may not be supported by every WSDL toolkit. However, as explained in <specref ref="adv-optional-versus-required"/>, toolkits that do not natively support the extension could seek manual input, thus permitting a client developer to supply an appropriate module that implements the necessary extension. This strategy has thus permits future WSDL toolkits to support and process the extension automatically, while also ensuring that the extension will be handled properly by toolkits that re not yet able to process it automatically.</p></item></ulist>
<p>To ensure that client and service implementations can easily determine the interface operation under which a received message was sent (even though not every client or service may need to make such a determination), it is considered good practice to follow one of the above strategies when authoring WSDL 2.0 documents.</p>
***************
*** 1821,1825 ****
element that has the interface and binding for the Reservation
Details service and whose endpoint address is that of the
! corresponing reservation. This element is used in the definition
of the Reservation List Web service.
</p>
--- 1823,1827 ----
element that has the interface and binding for the Reservation
Details service and whose endpoint address is that of the
! corresponding reservation. This element is used in the definition
of the Reservation List Web service.
</p>
***************
*** 2105,2109 ****
</example>
</div3>
! <div3 id="reservationDetails_HTTP"><head>Reservation Details Web Service Using HTTP Transfer</head><p>This section presents a variation on the example in <specref ref="reservationDetails"/>. It illustrates the use of HTTP transfer operations, GET and PUT, to retrieve and update GreatH hotel reservation details using the Representational State Transfer (REST) architectural style described by Roy Fielding @@bibref@@. REST is a distillation of the architectural properties that Dr. Fielding identified as being vital to the Web's robustness and enormous scalabilty. </p><p>Since each reservation in our example will have a distinct URI, the Reservation Details Web
service can be offered using HTTP GET and HTTP PUT. The binding would be modified as follows:</p><example id="reservationDetails_HTTP_example">
<head>
--- 2107,2111 ----
</example>
</div3>
! <div3 id="reservationDetails_HTTP"><head>Reservation Details Web Service Using HTTP Transfer</head><p>This section presents a variation on the example in <specref ref="reservationDetails"/>. It illustrates the use of HTTP transfer operations, GET and PUT, to retrieve and update GreatH hotel reservation details using the Representational State Transfer (REST) architectural style described by Roy Fielding @@bibref@@. REST is a distillation of the architectural properties that Dr. Fielding identified as being vital to the Web's robustness and enormous scalability. </p><p>Since each reservation in our example will have a distinct URI, the Reservation Details Web
service can be offered using HTTP GET and HTTP PUT. The binding would be modified as follows:</p><example id="reservationDetails_HTTP_example">
<head>
***************
*** 2593,2597 ****
In both of these examples, the <code>schemaLocation</code> attribute was omitted since the WSDL processor was assumed to know how to locate the imported
schemas because they were part of the WSDL documents being processed. The <code>schemaLocation</code> attribute can be used to give the processor a URI reference
! that explictly locates the schemas. A URI reference is a URI plus an optional fragment identifier that indicates part of the resource. For schemas, the fragment should identify
the <code>schema</code> element. The simplest way to accomplish this is to use the <code>id</code> attribute, however XPointer can also be used.
</p><div4><head>Using the id Attribute to Identify Inline
--- 2595,2599 ----
In both of these examples, the <code>schemaLocation</code> attribute was omitted since the WSDL processor was assumed to know how to locate the imported
schemas because they were part of the WSDL documents being processed. The <code>schemaLocation</code> attribute can be used to give the processor a URI reference
! that explicitly locates the schemas. A URI reference is a URI plus an optional fragment identifier that indicates part of the resource. For schemas, the fragment should identify
the <code>schema</code> element. The simplest way to accomplish this is to use the <code>id</code> attribute, however XPointer can also be used.
</p><div4><head>Using the id Attribute to Identify Inline
***************
*** 2707,2711 ****
is the URI of the resource)</p></item><item><p>Operation styles (similarly to MEPs, the URI of an
operation style is the URI of the resource)</p></item></olist></p></item><item><p>All the resources above are given the appropriate types using
! rdf:type stataments (an interface will belong to the class
Interface and an operation within an interface will belong to
the class InterfaceOperation, for example).</p></item><item><p>All relationships in WSDL 2.0 (like an Operation belonging to an
--- 2709,2713 ----
is the URI of the resource)</p></item><item><p>Operation styles (similarly to MEPs, the URI of an
operation style is the URI of the resource)</p></item></olist></p></item><item><p>All the resources above are given the appropriate types using
! rdf:type statements (an interface will belong to the class
Interface and an operation within an interface will belong to
the class InterfaceOperation, for example).</p></item><item><p>All relationships in WSDL 2.0 (like an Operation belonging to an
Index: wsdl20-primer.html
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.html,v
retrieving revision 1.48
retrieving revision 1.49
diff -C2 -d -r1.48 -r1.49
*** wsdl20-primer.html 27 Apr 2005 23:27:47 -0000 1.48
--- wsdl20-primer.html 28 Apr 2005 00:29:32 -0000 1.49
***************
*** 94,99 ****
<hr><div class="toc">
<h2><a name="shortcontents">Short Table of Contents</a></h2><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 Infoset, Schema and Component Model</a><br>4. <a href="#more-types">More on Message Types</a><br>5. <a href="#more-interfaces">More on Interfaces</a><br>6. <a href="#more-bindings">More on Bindings</a><br>7. <a href="#advanced-topic_ii">Advanced Topics</a><br>8. <a href="#References">References</a><br></p></div><hr><div class="toc">
! <h2><a name="contents">Table of Contents</a></h2><p class="toc">1. <a href="#Introduction">Introduction</a><br> 1.1 <a href="#Prerequisites">Prerequisites</a><br> 1.2 <a href="#PrimerStructure">Structure of this Primer</a><br> 1.3 <a href="#notation">Notational Conventions</a><br>2. <a href="#basics">WSDL 2.0 Basics</a><br> 2.1 <a href="#basics-greath-scenario">Example Scenario: The GreatH Hotel Reservation Service</a><br> 2.2 <a href="#basics-getting-started">Getting Started: Defining a WSDL Target Namespace</a><br> 2.2.1 <a href="#example-empty-shell-explanation">Explanation of Example</a><br> 2.3 <a href="#basics-types">Defining Message Types</a><br> 2.3.1 <a href="#example-initial-types-explanation">Explanation of Example</a><br> 2.4 <a href="#basics-nterface">Defining an Interface</a><br> 2.4.1 <a href="#example-initial-interface-explanation">Explanation of Example</a><br> 2.5 <a href="#basics-binding">Defining a Binding</a><br> 2.5.1 <a href="#example-initial-binding-explanation">Explanation of Example</a><br> 2.6 <a href="#basics-service">Defining a Service</a><br> 2.6.1 <a href="#example-initial-service-explanation">Explanation of Example</a><br> 2.7 <a href="#basics-documentation">Documenting the Service</a><br> 2.7.1 <a href="#example-initial-documentation-explanation">Explanation of Example</a><br>3. <a href="#wsdl-xml-representation">WSDL 2.0 Infoset, Schema and Component Model</a><br> 3.1 <a href="#wsdl-infoset-diagram">WSDL 2.0 Infoset</a><br> 3. <a href="#wsdl-schema">WSDL 2.0 Schema and Element Ordering</a><br> 3.3 <a href="#component-model">WSDL 2.0 Component Model</a><br>4. <a href="#more-types">More on Message Types</a><br> 4.1 <a href="#more-types-schema-embed">Embedding XML Schema</a><br> 4.2 <a href="#more-types-schema-import">Importing XML Schema</a><br> 4.3 <a href="#more-types-import-include-summary">Summary of Import and Include Mechanisms</a><br>5. <a href="#more-interfaces">More on Interfaces</a><br> 5.1 <a href="#more-interfaces-interfaces">Interface Syntax </a><br> 5.2 <a href="#more-interfaces-inheritance">Interface Inheritance</a><br> 5.3 <a href="#more-interfaces-faults">Interface Faults</a><br> 5.4 <a href="#more-interfaces-operations">Interface Operations</a><br> 5.4.1 <a href="#more-interfaces-op-att">Operation Attributes</a><br> 5.4.2 <a href="#N1089A">Operation Message References</a><br> 5.4.2.1 <a href="#N108B7">The messageLabel Attribute</a><br> 5.4.2.2 <a href="#N108CB">The element Attribute</a><br> 5.4.2.3 <a href="#N108F2">Multiple infault or outfault Elements</a><br> 5.4.3 <a href="#more-interfaces-meps">Understanding Message Exchange Patterns (MEPs)</a><br> 5.4.4 <a href="#more-interfaces-defining-meps">Defining New Message Exchange Patterns (MEPs)</a><br>6. <a href="#more-bindings">More on Bindings</a><br> 6.1 <a href="#more-bindings-wsdl">Syntax Summary for Bindings</a><br> 6.2 <a href="#more-bindins-reusable">Reusable Bindings</a><br> 6.3 <a href="#more-bindings-faults">Binding Faults</a><br> 6.4 <a href="#bindingOperations">Binding Operations</a><br> 6.5 <a href="#more-bindings-soap">The SOAP Binding Extension</a><br> 6.5.1 <a href="#more-bindings-soap-example-explanation">Explanation of Example</a><br> 6.6 <a href="#more-bindings-http">The HTTP Binding Extension</a><br> 6.6.1 <a href="#N10AB6">Explanation of
! Example</a><br> 6.7 <a href="#adv-get-vs-post">HTTP GET Versus POST: Which to Use?</a><br>7. <a href="#advanced-topic_ii">Advanced Topics</a><br> 7.1 <a href="#adv-extensibility">Extensibility</a><br> 7.1.1 <a href="#adv-optional-versus-required">Optional Versus Required Extensions</a><br> 7.1.2 <a href="#adv-scope-of-wsdl-required">Scoping of the wsdl:required Attribute</a><br> 7.2 <a href="#adv-FP">Features and Properties</a><br> 7.2.1 <a href="#adv-FP-soap-modules">SOAP Modules</a><br> 7.2.2 <a href="#adv-FP-abstract-features">Abstract Features</a><br> 7.2.3 <a href="#adv-fp-properties">Properties</a><br> 7.3 <a href="#adv-import-and-authoring">Import mechanism and authoring stye</a><br> 7.4 <a href="#adv-multiple-docs-describing-same-service">Multiple Interfaces for the Same Service</a><br> 7.5 <a href="#adv-versioning">Web Service Versioning</a><br> 7.5.1 <a href="#adv-versioning-compatible-evolution">Compatible Evolution</a><br> 7.5.2 <a href="#adv-versioning-big-bang">Big Bang</a><br> 7.5.3 <a href="#adv-versioning-combined">Combined Approaches</a><br> 7.6 <a href="#adv-MTOM">MTOM Support</a><br> 7.7 <a href="#adv-RPCstyle">RPC Style</a><br> 7.8 <a href="#adv-message-dispatch">Enabling Easy Message Dispatch</a><br> 7.9 <a href="#adv-service-references">Service References</a><br> 7.9.1 <a href="#reservationDetails">The Reservation Details Web Service</a><br>nbsp; 7.9.2 <a href="#reservationList">The Reservation List Web Service</a><br> 7.9.3 <a href="#reservationDetails_HTTP">Reservation Details Web Service Using HTTP Transfer</a><br> 7.9.4 <a href="#reservationList_HTTP_GET">Reservation List Web Service Using HTTP GET</a><br> 7.10 <a href="#adv-multiple-inline-schemas">Importing Schemas</a><br> 7.10.1 <a href="#N10FC6">Schemas in Imported Documents</a><br> 7.10.2 <a href="#N11051">Multiple Inline Schemas in One Document</a><br> 7.10.3 <a href="#adv-schema-location">The schemaLocation Attribute</a><br> 7.10.3.1 <a href="#N110AE">Using the id Attribute to Identify Inline
Schemas</a><br> 7.11 <a href="#adv-rdf-mapping">Mapping to RDF and Semantic Web</a><br> 7.11.1 <a href="#adv-rdf-rep-wsdl">RDF Representation of WSDL 2.0</a><br> 7.12 <a href="#adv-notes-on-uris">Notes on URIs</a><br> 7.12.1 <a href="#adv-namespaces-and-schema-locations">XML Namespaces and Schema Locations</a><br> 7.12.2 <a href="#adv-relative-uris">Relative URIs</a><br> 7.12.3 <a href="#adv-generating-uris">Generating Temporary URIs</a><br>8. <a href="#References">References</a><br> 8.1 <a href="#Normative-References">Normative References</a><br> 8.2 <a href="#Informative-References">Informative References</a><br></p></div><hr><div class="body">
--- 94,99 ----
<hr><div class="toc">
<h2><a name="shortcontents">Short Table of Contents</a></h2><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 Infoset, Schema and Component Model</a><br>4. <a href="#more-types">More on Message Types</a><br>5. <a href="#more-interfaces">More on Interfaces</a><br>6. <a href="#more-bindings">More on Bindings</a><br>7. <a href="#advanced-topic_ii">Advanced Topics</a><br>8. <a href="#References">References</a><br></p></div><hr><div class="toc">
! <h2><a name="contents">Table of Contents</a></h2><p class="toc">1. <a href="#Introduction">Introduction</a><br> 1.1 <a href="#Prerequisites">Prerequisites</a><br> 1.2 <a href="#PrimerStructure">Structure of this Primer</a><br> 1.3 <a href="#notation">Notational Conventions</a><br>2. <a href="#basics">WSDL 2.0 Basics</a><br> 2.1 <a href="#basics-greath-scenario">Example Scenario: The GreatH Hotel Reservation Service</a><br> 2.2 <a href="#basics-getting-started">Getting Started: Defining a WSDL Target Namespace</a><br> 2.2.1 <a href="#example-empty-shell-explanation">Explanation of Example</a><br> 2.3 <a href="#basics-types">Defining Message Types</a><br> 2.3.1 <a href="#example-initial-types-explanation">Explanation of Example</a><br> 2.4 <a href="#basics-nterface">Defining an Interface</a><br> 2.4.1 <a href="#example-initial-interface-explanation">Explanation of Example</a><br> 2.5 <a href="#basics-binding">Defining a Binding</a><br> 2.5.1 <a href="#example-initial-binding-explanation">Explanation of Example</a><br> 2.6 <a href="#basics-service">Defining a Service</a><br> 2.6.1 <a href="#example-initial-service-explanation">Explanation of Example</a><br> 2.7 <a href="#basics-documentation">Documenting the Service</a><br> 2.7.1 <a href="#example-initial-documentation-explanation">Explanation of Example</a><br>3. <a href="#wsdl-xml-representation">WSDL 2.0 Infoset, Schema and Component Model</a><br> 3.1 <a href="#wsdl-infoset-diagram">WSDL 2.0 Infoset</a><br> 3. <a href="#wsdl-schema">WSDL 2.0 Schema and Element Ordering</a><br> 3.3 <a href="#component-model">WSDL 2.0 Component Model</a><br>4. <a href="#more-types">More on Message Types</a><br> 4.1 <a href="#more-types-schema-embed">Embedding XML Schema</a><br> 4.2 <a href="#more-types-schema-import">Importing XML Schema</a><br> 4.3 <a href="#more-types-import-include-summary">Summary of Import and Include Mechanisms</a><br>5. <a href="#more-interfaces">More on Interfaces</a><br> 5.1 <a href="#more-interfaces-interfaces">Interface Syntax </a><br> 5.2 <a href="#more-interfaces-inheritance">Interface Inheritance</a><br> 5.3 <a href="#more-interfaces-faults">Interface Faults</a><br> 5.4 <a href="#more-interfaces-operations">Interface Operations</a><br> 5.4.1 <a href="#more-interfaces-op-att">Operation Attributes</a><br> 5.4.2 <a href="#N1089B">Operation Message References</a><br> 5.4.2.1 <a href="#N108B8">The messageLabel Attribute</a><br> 5.4.2.2 <a href="#N108CC">The element Attribute</a><br> 5.4.2.3 <a href="#N108F3">Multiple infault or outfault Elements</a><br> 5.4.3 <a href="#more-interfaces-meps">Understanding Message Exchange Patterns (MEPs)</a><br> 5.4.4 <a href="#more-interfaces-defining-meps">Defining New Message Exchange Patterns (MEPs)</a><br>6. <a href="#more-bindings">More on Bindings</a><br> 6.1 <a href="#more-bindings-wsdl">Syntax Summary for Bindings</a><br> 6.2 <a href="#more-bindins-reusable">Reusable Bindings</a><br> 6.3 <a href="#more-bindings-faults">Binding Faults</a><br> 6.4 <a href="#bindingOperations">Binding Operations</a><br> 6.5 <a href="#more-bindings-soap">The SOAP Binding Extension</a><br> 6.5.1 <a href="#more-bindings-soap-example-explanation">Explanation of Example</a><br> 6.6 <a href="#more-bindings-http">The HTTP Binding Extension</a><br> 6.6.1 <a href="#N10AB7">Explanation of
! Example</a><br> 6.7 <a href="#adv-get-vs-post">HTTP GET Versus POST: Which to Use?</a><br>7. <a href="#advanced-topic_ii">Advanced Topics</a><br> 7.1 <a href="#adv-extensibility">Extensibility</a><br> 7.1.1 <a href="#adv-optional-versus-required">Optional Versus Required Extensions</a><br> 7.1.2 <a href="#adv-scope-of-wsdl-required">Scoping of the wsdl:required Attribute</a><br> 7.2 <a href="#adv-FP">Features and Properties</a><br> 7.2.1 <a href="#adv-FP-soap-modules">SOAP Modules</a><br> 7.2.2 <a href="#adv-FP-abstract-features">Abstract Features</a><br> 7.2.3 <a href="#adv-fp-properties">Properties</a><br> 7.3 <a href="#adv-import-and-authoring">Import mechanism and authoring stye</a><br> 7.4 <a href="#adv-multiple-docs-describing-same-service">Multiple Interfaces for the Same Service</a><br> 7.5 <a href="#adv-versioning">Web Service Versioning</a><br> 7.5.1 <a href="#adv-versioning-compatible-evolution">Compatible Evolution</a><br> 7.5.2 <a href="#adv-versioning-big-bang">Big Bang</a><br> 7.5.3 <a href="#adv-versioning-combined">Combined Approaches</a><br> 7.6 <a href="#adv-MTOM">MTOM Support</a><br> 7.7 <a href="#adv-RPCstyle">RPC Style</a><br> 7.8 <a href="#adv-message-dispatch">Enabling Easy Message Dispatch</a><br> 7.9 <a href="#adv-service-references">Service References</a><br> 7.9.1 <a href="#reservationDetails">The Reservation Details Web Service</a><br>nbsp; 7.9.2 <a href="#reservationList">The Reservation List Web Service</a><br> 7.9.3 <a href="#reservationDetails_HTTP">Reservation Details Web Service Using HTTP Transfer</a><br> 7.9.4 <a href="#reservationList_HTTP_GET">Reservation List Web Service Using HTTP GET</a><br> 7.10 <a href="#adv-multiple-inline-schemas">Importing Schemas</a><br> 7.10.1 <a href="#N10FC7">Schemas in Imported Documents</a><br> 7.10.2 <a href="#N11052">Multiple Inline Schemas in One Document</a><br> 7.10.3 <a href="#adv-schema-location">The schemaLocation Attribute</a><br> 7.10.3.1 <a href="#N110AF">Using the id Attribute to Identify Inline
Schemas</a><br> 7.11 <a href="#adv-rdf-mapping">Mapping to RDF and Semantic Web</a><br> 7.11.1 <a href="#adv-rdf-rep-wsdl">RDF Representation of WSDL 2.0</a><br> 7.12 <a href="#adv-notes-on-uris">Notes on URIs</a><br> 7.12.1 <a href="#adv-namespaces-and-schema-locations">XML Namespaces and Schema Locations</a><br> 7.12.2 <a href="#adv-relative-uris">Relative URIs</a><br> 7.12.3 <a href="#adv-generating-uris">Generating Temporary URIs</a><br>8. <a href="#References">References</a><br> 8.1 <a href="#Normative-References">Normative References</a><br> 8.2 <a href="#Informative-References">Informative References</a><br></p></div><hr><div class="body">
***************
*** 492,497 ****
</service></pre></div>
</div><div class="div3">
! <h4><a name="example-initial-service-explanation"></a>2.6.1 Explanation of Example</h4><dl><dt class="label"><code><service name="reservationService"</code></dt><dd><p>This defines a name for this service, which must be unique among service names in the WSDL target namespace. The name attribute is required. It allows URIs to be created that indentify components in WSDL 2.0 description. (See <em>WSDL 2.0 Core Language</em> [<cite><a href="#WSDL-PART1">WSDL 2.0 Core Language</a></cite>] appendix C <a href="http://www.w3.org/TR/2004/WD-wsdl20-20040803/#wsdl-uri-references">URI References for WSDL constructs</a>.)</p></dd><dt class="label"><code>interface="tns:reservationInterface"></code></dt><dd><p>This specifies the name of the previously defined interface that these service endpoints will support. </p></dd><dt class="label"><code><endpoint name="reservationEndpoint"</code></dt><dd><p>This defines an endpoint for the service, and a name for this endpoint, which must be unique within this serice. </p></dd><dt class="label"><code>binding="tns:reservationSOAPBinding"</code></dt><dd><p>This specifies the name of the previously defined binding to be used by this endpoint. </p></dd><dt class="label"><code>address ="http://greath.example.com/2004/reservation"/></code></dt><dd><p>This specifies the physical address at which this service can be accessed using the binding specified by the <code>binding</code> attribute.</p></dd></dl><p>That's it! Well, almost. </p></div></div><div class="div2">
! <h3><a name="basics-documentation"></a>2.7 Documenting the Service</h3><p>As we have seen, a WSDL 2.0 document is inherently only a <em>partial</em> description of a service. Although it captures the basic mechanics of interacting with the service -- the message types, transmission protocols, service location, etc. -- in general, additional documention will need to explain other application-level requirements for its use. For example, such documentation should explain the purpose and use of the service, the meanings of all messages, constraints on their use, and the sequence in which operations should be invoked.</p><p>The <code>documentation</code> element allows the WSDL author to include some human-readable documentation inside a WSDL 2.0 document. It is also a convenient place to reference any additional external documentation that a client developer may need in order to use the service. It can appear in a number of places in a WSDL 2.0 document (see <a href="#wsdl-infoset-diagram"><b>3.1 WSDL 20 Infoset</b></a>), though in this example we have only demonstrated its use at the beginning.</p><div class="exampleOuter">
<p class="exampleHead" style="text-align: left"><a name="example-initial-documentation"></a><i><span>Example 2-7. </span>Documenting the GreatH Service</i></p>
<div class="exampleInner"><pre><?xml version="1.0" encoding="utf-8" ?>
--- 492,499 ----
</service></pre></div>
</div><div class="div3">
! <h4><a name="example-initial-service-explanation"></a>2.6.1 Explanation of Example</h4><dl><dt class="label"><code><service name="reservationService"</code></dt><dd><p>This defines a name for this service, which must be unique among service names in the WSDL target namespace. The name attribute is required. It allows URIs to be created that identify components in WSDL 2.0 description. (See <em>WSDL 2.0 Core Language</em> [<cite><a href="#WSDL-PART1">WSDL 2.0 Core Language</a></cite>] appendix C <a href="http://www.w3.org/TR/2004/WD-wsdl20-20040803/#wsdl-uri-references">URI References for WSDL constructs</a>.)</p></dd><dt class="label"><code>interface="tns:reservationInterface"></code></dt><dd><p>This specifies the name of the previously defined interface that these service endpoints will support. </p></dd><dt class="label"><code><endpoint name="reservationEndpoint"</code></dt><dd><p>This defines an endpoint for the service, and a name for this endpoint, which must be unique within this servie. </p></dd><dt class="label"><code>binding="tns:reservationSOAPBinding"</code></dt><dd><p>This specifies the name of the previously defined binding to be used by this endpoint. </p></dd><dt class="label"><code>address ="http://greath.example.com/2004/reservation"/></code></dt><dd><p>This specifies the physical address at which this service can be accessed using the binding specified by the <code>binding</code> attribute.</p></dd></dl><p>That's it! Well, almost. </p></div></div>
!
! <div class="div2">
! <h3><a name="basics-documentation"></a>2.7 Documenting the Service</h3><p>As we have seen, a WSDL 2.0 document is inherently only a <em>partial</em> description of a service. Although it captures the basic mechanics of interacting with the service -- the message types, transmission protocols, service location, etc. -- in general, additional documentation will need to explain other application-level requirements for its use. For example, such documentation should explain the purpose and use of the service, the meanings of all messages, constraints on their use, and the sequence in which operations should be invoked.</p><p>The <code>documentation</code> element allows the WSDL author to include some human-readable documentation inside a WSDL 2.0 document. It is also a convenient place to reference any additional external documentation that a client developer may need in order to use the service. It can appear in a number of places in a WSDL 2.0 document (see <a href="#wsdl-infoset-diagram"><b>3.1 WSDL2.0 Infoset</b></a>), though in this example we have only demonstrated its use at the beginning.</p><div class="exampleOuter">
<p class="exampleHead" style="text-align: left"><a name="example-initial-documentation"></a><i><span>Example 2-7. </span>Documenting the GreatH Service</i></p>
<div class="exampleInner"><pre><?xml version="1.0" encoding="utf-8" ?>
***************
*** 769,774 ****
<h3><a name="more-interfaces-inheritance"></a>5.2 Interface Inheritance</h3>
! <p>The optional <code>extends</code> attribute allows an interface to extend or inherit from one or more other interfaces. In such cases the interface contains the operations of the interfaces it extends, along with any operations it defines directly. Two things about extending interfaces deserve some attention. </p><p>First, an inheritance loop (or infinite recursion) is prohibited: the interfaces that a given interface extends MUST NOT themselves extend that interface either directly or indirectly. </p><p>Second, we must explain what happens when operations from two different interfaces have the same target namespace and operation name. There are two cases: either the component models of the operations are the same, or they are different. If the component models are the same (per the component comparison algorithm defined in WSDL 2.0 Part 1 [<cite><a href="#WSDL-PART1">WSDL 2.0 Core Language</a></cite>] "<a href="http://www.w3.org/TR/wsdl20-primer#compequiv">Equivalence of Components</a>") the they are considered to be the same operation, i.e., they are collapsed into a single operation, and the fact that they were included more than once is not considered an error. (For operations, component equivalence basically means that the two operations have the same set of attributes and descendents.) In the second case, if two operations have the same name in the same WSDL target namespace but are not equivalent, then it is an error. For the above reason, it is considered good practice to ensure that all operations within the same target namespace are named uniquely. </p><p>Finally, since faults, features and properties can also be defined as children of the <code>interface</code> element (as descrbed later), the same name-collision rules apply to those constructs.</p>
! <p>Now let's have a look at the element children of <code>interface</code>, beginning with <code>fault</code>. In the next section, we will provide an example of leveraging interface inheritance for reusing faults and operations across multiple interfaces. </p>
</div>
--- 771,776 ----
<h3><a name="more-interfaces-inheritance"></a>5.2 Interface Inheritance</h3>
! <p>The optional <code>extends</code> attribute allows an interface to extend or inherit from one or more other interfaces. In such cases the interface contains the operations of the interfaces it extends, along with any operations it defines directly. Two things about extending interfaces deserve some attention. </p><p>First, an inheritance loop (or infinite recursion) is prohibited: the interfaces that a given interface extends MUST NOT themselves extend that interface either directly or indirectly. </p><p>Second, we must explain what happens when operations from two different interfaces have the same target namespace and operation name. There are two cases: either the component models of the operations are the same, or they are different. If the component models are the same (per the component comparison algorithm defined in WSDL 2.0 Part 1 [<cite><a href="#WSDL-PART1">WSDL 2.0 Core Language</a></cite>] "<a href="http://www.w3.org/TR/wsdl20-primer#compequiv">Equivalence of Components</a>") the they are considered to be the same operation, i.e., they are collapsed into a single operation, and the fact that they were included more than once is not considered an error. (For operations, component equivalence basically means that the two operations have the same set of attributes and descendents.) In the second case, if two operations have the same name in the same WSDL target namespace but are not equivalent, then it is an error. For the above reason, it is considered good practice to ensure that all operations within the same target namespace are named uniquely. </p><p>Finally, since faults, features and properties can also be defined as children of the <code>interface</code> element (as described in the following sections), the same name-collision rules apply to those constructs. In the next section, we will provide an example of leveraging interface inheritance for reusing faults and operations across multiple interfaces.</p>
! <p>Now let's have a look at the element children of <code>interface</code>, beginning with <code>fault</code>. </p>
</div>
***************
*** 779,783 ****
<p>Faults are very similar to messages and can be viewed as a special kind of
message. Both faults and messages may carry a payload that is normally described
! by an element declaration. However, WSDL treats faults and messages slighly
differently. The messages of an operation directly refer to their element
declaration, however the faults of an operation indirectly refer to their
--- 781,785 ----
<p>Faults are very similar to messages and can be viewed as a special kind of
message. Both faults and messages may carry a payload that is normally described
! by an element declaration. However, WSDL treats faults and messages slightly
differently. The messages of an operation directly refer to their element
declaration, however the faults of an operation indirectly refer to their
***************
*** 793,800 ****
<p>The <code>fault</code> element has a required <code>name</code> attribute that must be unique within the WSDL document's target namespace, and permits it to be referenced from operation declarations. The optional <code>element</code> attribute can be used to indicate a schema for the content or payload of the fault message. Its value should be the QName of a global element defined in the <code>types</code> section. Please note when other type systems are used to define the schema for a fault message, additional attributes may need to be defined via WSDL's attribute extension mechanism to allow the schema to be associated with the fault.</p>
! <p>The following example shows one way to leverage interface inheritance for reusing faults and operations across multiple interfaces. In most cases, faults are defined under each inidividual interface like in the initial example @@TODO:Add reference to example 2-1@@. But some system may require a set of standard fault messages to be reused across a system. For example, let's say the GreatH hotel wants to maintain a set of standard fault messages and a standard error log operation for credit card and data validation errors that are reusable across the whole reservation system. One way to meet such requirement is to define the standard faults and the log operation in an interface which can be inherited by other interfaces. </p>
<div class="exampleOuter">
! <p class="exampleHead" style="text-align: left"><a name="example-faults"></a><i><span>Example 5-1. </span>Reusalbe Faults and Interface Inheritance</i></p>
<div class="exampleInner"><pre>
--- 795,802 ----
<p>The <code>fault</code> element has a required <code>name</code> attribute that must be unique within the WSDL document's target namespace, and permits it to be referenced from operation declarations. The optional <code>element</code> attribute can be used to indicate a schema for the content or payload of the fault message. Its value should be the QName of a global element defined in the <code>types</code> section. Please note when other type systems are used to define the schema for a fault message, additional attributes may need to be defined via WSDL's attribute extension mechanism to allow the schema to be associated with the fault.</p>
! <p>The following example shows one way to leverage interface inheritance for reusing faults and operations across multiple interfaces. In most cases, faults are defined under each individual interface like in the initial example @@TODO:Add reference to example 2-1@@. But some system may require a set of standard fault messages to be reused across a system. For example, let's say the GreatH hotel wants to maintain a set of standard fault messages and a standard error log operation for credit card and data validation errors that are reusable across the whole reservation system. One way to meet such requirement is to define the standard faults and the log operation in an interface which can be inherited by other interfaces. </p>
<div class="exampleOuter">
! <p class="exampleHead" style="text-align: left"><a name="example-faults"></a><i><span>Example 5-1. </span>Reusable Faults and Interface Inheritance</i></p>
<div class="exampleInner"><pre>
***************
*** 872,880 ****
</li>
</ul></div><div class="div3">
! <h4><a name="N1089A"></a>5.4.2 Operation Message References</h4><p>An <code>operation</code> will also have <code>input</code>, <code>output</code>,<code>infault</code>, and/or <code>outfault</code> element children that specify the ordinary and fault message types to be used by that operation. The MEP specified by the <code>pattern</code> attribute determines which of these elements should be included, since each MEP has placeholders for the message types involved in its pattern. </p><p>Since operations were already discussed in <a href="#basics-interface"><b>2.4 Defining an Interface</b></a>, this section will merely comment on additional capabilities that were not previously explained.</p>
<div class="div4">
! <h5><a name="N108B7"></a>5.4.2.1 The messageLabel Attribute</h5><p>The <code>messageLabel</code> attribute of the <code>input</code> and <code>output</code> elements is optional: it is not necessary to explicitly set the <code>messageLabel</code> when the MEP in use is one of the eight MEPs predefined in WSDL 2.0 Part 2 [<cite><a href="#WSDL-PART2">WSDL 2.0 Adjuncts</a></cite>] and it has only one message with a given direction. </p></div><div class="div4">
! <h5><a name="N108CB"></a>5.4.2.2 The element Attribute</h5><p>The <code>element</code> attribute of the <code>input</code> and <code>output</code> elements is used to specify the message content schema (a/k/a payload schema) when the content model is defined using XML Schema. As we have seen already, it can specify the QName of an element schema that was defined in the <code>types</code> section. However, alternatively it can specify one of the following tokens: </p><dl><dt class="label"><code>#any</code></dt><dd><p>The message content is any single element.</p></dd><dt class="label"><code>#none</code></dt><dd><p>There is no message content, i.e., the message payload is empty.</p></dd></dl><p>The <code>element</code> attribute is also optional. If it is not specified, then @@@@. <table border="1" summary="Editorial note"><tr><td width="50%" valign="top" align="left"><b>Editorial note</b></td><td width="50%" valign="top" align="right"> </td></tr><tr><td valign="top" align="left" colspan="2">ToDo: ay what happens if the element attribute is not specified, after issue LC99 is resolved. See http://www.w3.org/2002/ws/desc/4/lc-issues/issues.html#LC99 </td></tr></table></p></div><div class="div4">
! <h5><a name="N108F2"></a>5.4.2.3 Multiple infault or outfault Elements</h5><p>When <code>infault</code> and/or <code>outfault</code> occur multiple times within an <code>operation</code>, they define alternative fault messages. </p></div></div>
--- 874,882 ----
</li>
</ul></div><div class="div3">
! <h4><a name="N1089B"></a>5.4.2 Operation Message References</h4><p>An <code>operation</code> will also have <code>input</code>, <code>output</code>,<code>infault</code>, and/or <code>outfault</code> element children that specify the ordinary and fault message types to be used by that operation. The MEP specified by the <code>pattern</code> attribute determines which of these elements should be included, since each MEP has placeholders for the message types involved in its pattern. </p><p>Since operations were already discussed in <a href="#basics-interface"><b>2.4 Defining an Interface</b></a>, this section will merely comment on additional capabilities that were not previously explained.</p>
<div class="div4">
! <h5><a name="N108B8"></a>5.4.2.1 The messageLabel Attribute</h5><p>The <code>messageLabel</code> attribute of the <code>input</code> and <code>output</code> elements is optional: it is not necessary to explicitly set the <code>messageLabel</code> when the MEP in use is one of the eight MEPs predefined in WSDL 2.0 Part 2 [<cite><a href="#WSDL-PART2">WSDL 2.0 Adjuncts</a></cite>] and it has only one message with a given direction. </p></div><div class="div4">
! <h5><a name="N108CC"></a>5.4.2.2 The element Attribute</h5><p>The <code>element</code> attribute of the <code>input</code> and <code>output</code> elements is used to specify the message content schema (a/k/a payload schema) when the content model is defined using XML Schema. As we have seen already, it can specify the QName of an element schema that was defined in the <code>types</code> section. However, alternatively it can specify one of the following tokens: </p><dl><dt class="label"><code>#any</code></dt><dd><p>The message content is any single element.</p></dd><dt class="label"><code>#none</code></dt><dd><p>There is no message content, i.e., the message payload is empty.</p></dd></dl><p>The <code>element</code> attribute is also optional. If it is not specified, then @@@@. <table border="1" summary="Editorial note"><tr><td width="50%" valign="top" align="left"><b>Editorial note</b></td><td width="50%" valign="top" align="right"> </td></tr><tr><td valign="top" align="left" colspan="2">ToDo: ay what happens if the element attribute is not specified, after issue LC99 is resolved. See http://www.w3.org/2002/ws/desc/4/lc-issues/issues.html#LC99 </td></tr></table></p></div><div class="div4">
! <h5><a name="N108F3"></a>5.4.2.3 Multiple infault or outfault Elements</h5><p>When <code>infault</code> and/or <code>outfault</code> occur multiple times within an <code>operation</code>, they define alternative fault messages. </p></div></div>
***************
*** 892,896 ****
<p>Depends on how the first message in the MEP is initiated, the 8 WSDL MEPs may be grouped into two groups: 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 in this primer).</p>
! <p> A frequently asked question about out-bound MEPs is how a service knows where to send the message. Services using out-bound MEPs are typically part of large scale intergration systems that rely on mapping and routing facilities. In such systems, out-bound MEPs are useful for abstractly specifing the functionality of a service, including its requirements for potential customers, while endpoint address information can be provided at deployment or runtime by integration infrastructure. For example, the GreatH hotel reservation system may require that everytime a customer interacts with the system to check availability, data about the customer must be logged by a CRM system. At design time, it's unknown which particular CRM system would be used together with the reservation system. To address this requirement, we may change the "reservationInterface" in <a href="#example-initial">Example 2-1</a> to include an out-bound logInquiry operation. This logInquiry operation advertises to potential service clents that customer data will be made available by the reservation service at run time. When the reservation service is deployed to GreatH's IT landscape, appropriate configuration time and run time infrastructure will help determine which CRM system will get the customer data and log it appropriately. It's worth noting that in addition to being used by a CRM system for customer management purpose, the same data may also be used by a system performance analysis tool for different purpose. Providing an out-bound operation in the reservation service enables loose coupling and so improves the overall GreatH IT landscape's flexbility and scalability. </p>
<div class="exampleOuter">
--- 894,898 ----
<p>Depends on how the first message in the MEP is initiated, the 8 WSDL MEPs may be grouped into two groups: 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 in this primer).</p>
! <p> A frequently asked question about out-bound MEPs is how a service knows where to send the message. Services using out-bound MEPs are typically part of large scale integration systems that rely on mapping and routing facilities. In such systems, out-bound MEPs are useful for abstractly specifying the functionality of a service, including its requirements for potential customers, while endpoint address information can be provided at deployment or runtime by integration infrastructure. For example, the GreatH hotel reservation system may require that every time a customer interacts with the system to check availability, data about the customer must be logged by a CRM system. At design time, it's unknown which particular CRM system would be used together with the reservation system. To address this requirement, we may change the "reservationInterface" in <a href="#example-initial">Example 2-1</a> to include an out-bound logInquiry operation. This logInquiry operation advertises to potential service cients that customer data will be made available by the reservation service at run time. When the reservation service is deployed to GreatH's IT landscape, appropriate configuration time and run time infrastructure will help determine which CRM system will get the customer data and log it appropriately. It's worth noting that in addition to being used by a CRM system for customer management purpose, the same data may also be used by a system performance analysis tool for different purpose. Providing an out-bound operation in the reservation service enables loose coupling and so improves the overall GreatH IT landscape's flexibility and scalability. </p>
<div class="exampleOuter">
***************
*** 971,975 ****
<h3><a name="more-bindings-reusable"></a>6.2 Reusable Bindings</h3><p>A binding can either be reusable (applicable to any
interface) or non-reusable (specified for a particular interface). Non-reusable bindings may be specified at the granularity of the interface (assuming the binding extension provides suitable defaulting rules), or on a per-operation basis if needed. A non-reusable binding was demonstrated in <a href="#basics-binding"><b>2.5 Defining a Binding</b></a>.</p><p>To define a reusable binding, the <code>binding</code> element simply omits the <code>interface</code> attribute and omits specifying any
! operation-specific and fault-specific binding details. Endpoints can later refer to a resuable binding in the same manner as for a non-reusable binding. Thus, a reusable binding becomes associated with a particular interface when it is referenced from an endpoint, because an endpoint is part of a service, and the service specifies a particular interface that it implements. Since a reusable binding does not specify an interface, reusable bindings cannot specify operation-specific details. Therefore, reusable bindings can only be defined using binding extensions that have suitable defaulting rules, such that the binding information only needs to be explicitly supplied at the interface level.</p></div><div class="div2">
<h3><a name="more-bindings-faults"></a>6.3 Binding Faults</h3>
--- 973,977 ----
<h3><a name="more-bindings-reusable"></a>6.2 Reusable Bindings</h3><p>A binding can either be reusable (applicable to any
interface) or non-reusable (specified for a particular interface). Non-reusable bindings may be specified at the granularity of the interface (assuming the binding extension provides suitable defaulting rules), or on a per-operation basis if needed. A non-reusable binding was demonstrated in <a href="#basics-binding"><b>2.5 Defining a Binding</b></a>.</p><p>To define a reusable binding, the <code>binding</code> element simply omits the <code>interface</code> attribute and omits specifying any
! operation-specific and fault-specific binding details. Endpoints can later refer to a reusable binding in the same manner as for a non-reusable binding. Thus, a reusable binding becomes associated with a particular interface when it is referenced from an endpoint, because an endpoint is part of a service, and the service specifies a particular interface that it implements. Since a reusable binding does not specify an interface, reusable bindings cannot specify operation-specific details. Therefore, reusable bindings can only be defined using binding extensions that have suitable defaulting rules, such that the binding information only needs to be explicitly supplied at the interface level.</p></div><div class="div2">
<h3><a name="more-bindings-faults"></a>6.3 Binding Faults</h3>
***************
*** 1009,1013 ****
! <p>The WSDL 2.0 SOAP Binding Extension (see WSDL 2.0 Part 2 [<cite><a href="#WSDL-PART2">WSDL 2.0 Adjuncts</a></cite>]) was primarily designed to support the features of SOAP 1.2 [<cite><a href="#SOAP12-PART1">SOAP 1.2 Part 1: Messaging Framework</a></cite>]. However, for backwards compatibility, it also provides some support for SOAP 1.1 [<cite><a href="#SOAP11">SOAP 1.1</a></cite>]. </p><p>An example using the WSDL 2.0 SOAP binding extension was already presented in <a href="#basics-binding"><b>2.5 Defining a Binding</b></a>, but some additional points are worth mentioning:<ul><li><p>Because the same binding extension is used for both SOAP 1.2 and SOAP 1.1, a <code>wsoap:version</code> attribute is provided to allow you to indicate which version of SOAP you want. If this attribute is not specified, it defaults to SOAP 1.2.</p></li><li><p>The WSDL 2.0 SOAP binding extension defines a set of default rules, so that bindings can be specified at the interface level or at the operation level (or bth), with the operation level taking precedence. However, it does not define default binding rules for faults. Thus, if a given interface defines any faults, then corresponding binding infomation must be explicitly provided for each such fault.</p></li><li><p>If HTTP is used as the underlying protocol, then the binding can (and should) control whether each operation will use HTTP GET or POST. (See <a href="#adv-get-vs-post"><b>6.7 HTTP GET Versus POST: Which to Use?</b></a>.)</p></li></ul></p><p>Here is an example that illustrates both a SOAP 1.2 binding (as seen before) and a SOAP 1.1 binding.</p><div class="exampleOuter">
<p class="exampleHead" style="text-align: left"><a name="example-binding-soap"></a><i><span>Example 6-1. </span>SOAP 1.2 and SOAP 1.1 Bindings</i></p>
--- 1011,1015 ----
! <p>The WSDL 2.0 SOAP Binding Extension (see WSDL 2.0 Part 2 [<cite><a href="#WSDL-PART2">WSDL 2.0 Adjuncts</a></cite>]) was primarily designed to support the features of SOAP 1.2 [<cite><a href="#SOAP12-PART1">SOAP 1.2 Part 1: Messaging Framework</a></cite>]. However, for backwards compatibility, it also provides some support for SOAP 1.1 [<cite><a href="#SOAP11">SOAP 1.1</a></cite>]. </p><p>An example using the WSDL 2.0 SOAP binding extension was already presented in <a href="#basics-binding"><b>2.5 Defining a Binding</b></a>, but some additional points are worth mentioning:<ul><li><p>Because the same binding extension is used for both SOAP 1.2 and SOAP 1.1, a <code>wsoap:version</code> attribute is provided to allow you to indicate which version of SOAP you want. If this attribute is not specified, it defaults to SOAP 1.2.</p></li><li><p>The WSDL 2.0 SOAP binding extension defines a set of default rules, so that bindings can be specified at the interface level or at the operation level (or bth), with the operation level taking precedence. However, it does not define default binding rules for faults. Thus, if a given interface defines any faults, then corresponding binding information must be explicitly provided for each such fault.</p></li><li><p>If HTTP is used as the underlying protocol, then the binding can (and should) control whether each operation will use HTTP GET or POST. (See <a href="#adv-get-vs-post"><b>6.7 HTTP GET Versus POST: Which to Use?</b></a>.)</p></li></ul></p><p>Here is an example that illustrates both a SOAP 1.2 binding (as seen before) and a SOAP 1.1 binding.</p><div class="exampleOuter">
<p class="exampleHead" style="text-align: left"><a name="example-binding-soap"></a><i><span>Example 6-1. </span>SOAP 1.2 and SOAP 1.1 Bindings</i></p>
***************
*** 1114,1118 ****
</div>
<div class="div3">
! <h4><a name="N10AB6"></a>6.6.1 Explanation of
Example</h4><table border="1" summary="Editorial note: dbooth"><tr><td width="50%" valign="top" align="left"><b>Editorial note: dbooth</b></td><td width="50%" valign="top" align="right">2005-04-15</td></tr><tr><td valign="top" align="left" colspan="2">ToDo: Check this section. I'm not sure I got it all right, particularly regarding whttp:location. Is the first sample request URI correct? Shouldn't instance data for tCheckAvailability be in the path component? What happens if a non-leaf element type is specified, such as tCheckAvailability?</td></tr></table><p></p><dl>
<dt class="label"><code>type="http://www.w3.org/@@@@/@@/wsdl/http"</code></dt>
--- 1116,1120 ----
</div>
<div class="div3">
! <h4><a name="N10AB7"></a>6.6.1 Explanation of
Example</h4><table border="1" summary="Editorial note: dbooth"><tr><td width="50%" valign="top" align="left"><b>Editorial note: dbooth</b></td><td width="50%" valign="top" align="right">2005-04-15</td></tr><tr><td valign="top" align="left" colspan="2">ToDo: Check this section. I'm not sure I got it all right, particularly regarding whttp:location. Is the first sample request URI correct? Shouldn't instance data for tCheckAvailability be in the path component? What happens if a non-leaf element type is specified, such as tCheckAvailability?</td></tr></table><p></p><dl>
<dt class="label"><code>type="http://www.w3.org/@@@@/@@/wsdl/http"</code></dt>
***************
*** 1124,1128 ****
<dt class="label"><code>xmlns:whttp="http://www.w3.org/@@@@/@@/wsdl/http" ></code></dt><dd><p>This defines the namespace prefix for elements and attributes defined by the WSDL 2.0 HTTP binding extension.</p></dd><dt class="label"><code>whttp:methodDefault="GET"></code></dt><dd><p>The default method for operations in this interface will be HTTP GET.</p></dd><dt class="label"><code>whttp:location="{checkInDate}" ></code></dt><dd><p>The <code>whttp:location</code> attribute specifies a pattern for serializing input message instance data into the path component of the request URI. The default binding rules for HTTP specify that the default input
! serialization for GET is <code>application/x-www-form-urlencoded</code>. Curly braces are used to specify the name of a schema type in the input message schema, which determines what input instance data will be inserted into the path component of the request URI. The curly brace-enclosed name will be replaced with instance data in constructing the path component. Remaining input instance data (not specified by <code>whttp:location</code>) will either be serialized into the query string portion of the URI or into the message body, as follows: if a "/" is appended to a curly brace-enclosed type name, then any remaining input message instance data will be serialized into the message body. Otherwise it will be serialized into query parameters.</p><p>Thus, in this example, each of the elements in the <code>tCheckAvailability</code> type will be serialized into the query parameters.A sample resulting URI for would therefore be
<code>http://greath.example.com/2004/5-5-5?checkOutDate=6-6-5&roomType=foo</code>. </p></dd></dl><p></p>
--- 1126,1130 ----
<dt class="label"><code>xmlns:whttp="http://www.w3.org/@@@@/@@/wsdl/http" ></code></dt><dd><p>This defines the namespace prefix for elements and attributes defined by the WSDL 2.0 HTTP binding extension.</p></dd><dt class="label"><code>whttp:methodDefault="GET"></code></dt><dd><p>The default method for operations in this interface will be HTTP GET.</p></dd><dt class="label"><code>whttp:location="{checkInDate}" ></code></dt><dd><p>The <code>whttp:location</code> attribute specifies a pattern for serializing input message instance data into the path component of the request URI. The default binding rules for HTTP specify that the default input
! serialization for GET is <code>application/x-www-form-urlencoded</code>. Curly braces are used to specify the name of a schema type in the input message schema, which determines what input instance data will be inserted into the path component of the request URI. The curly brace-enclosed name will be replaced with instance data in constructing the path component. Remaining input instance data (not specified by <code>whttp:location</code>) will either be serialized into the query string portion of the URI or into the message body, as follows: if a "/" is appended to a curly brace-enclosed type name, then any remaining input message instance data will be serialized into the message body. Otherwise it will be serialized into query parameters.</p><p>Thus, in this example, each of the elements in the <code>tCheckAvailability</code> type will be serialized into the query parameters. A sample resulting URI for would therefore be
<code>http://greath.example.com/2004/5-5-5?checkOutDate=6-6-5&roomType=foo</code>. </p></dd></dl><p></p>
***************
*** 1163,1167 ****
<h3><a name="adv-FP"></a>7.2 Features and Properties</h3>
! <p>After a few successful trials of the reservation service, GreatH decides that it is time to make the makeReservation operation secure, so that sensitive credit-card information is not being sent across the public network in a snoopable fashion. We will do this using the WSDL 2.0 Features and Properties mechanisms [<cite><a href="#WSDL-PART1">WSDL 2.0 Core Language</a></cite>], which is modeled after the Features and Properties mechanism defined in SOAP 1.2 [<cite><a href="#SOAP12-PART1">SOAP 1.2 Part 1: Messaging Framework</a></cite>].</p><p>To facilitate presentation, this section will assume the existence of a hypothetical security feature named "<code>http://features.example.com/2005/securityFeature</code>", which defines, in the abstract, the idea of message confidentiality. This feature has an associated property, named "<code>http://features.example.com/2005/securityFeature/securityLevel</code>", which defines various safety levels (from 0 meaning cleartext, all the way through 10, involvin highly complex cryptographic algorithms with keys in the tens of thousands of bits). We also assume that a SOAP module, named "<code>http://features.example.com/2005/modules/Security</code>", has been defined, which implements the security feature described above.</p><p>GreatH has chosen an abstract security feature which is standard in the fictitious hotels community, and has integrated both a SOAP module and a new secure HTTP binding into its infrastructure – both of which implement the security feature (the SOAP module does this inside the SOAP envelope using headers, and the secure binding does it at the transport layer). Now they'd like to advertise and control the usage of these extensions using WSDL 2.0.</p>
<div class="div3">
--- 1165,1169 ----
<h3><a name="adv-FP"></a>7.2 Features and Properties</h3>
! <p>After a few successful trials of the reservation service, GreatH decides that it is time to make the makeReservation operation secure, so that sensitive credit-card information is not being sent across the public network in a snoopable fashion. We will do this using the WSDL 2.0 Features and Properties mechanisms [<cite><a href="#WSDL-PART1">WSDL 2.0 Core Language</a></cite>], which is modeled after the Features and Properties mechanism defined in SOAP 1.2 [<cite><a href="#SOAP12-PART1">SOAP 1.2 Part 1: Messaging Framework</a></cite>].</p><p>To facilitate presentation, this section will assume the existence of a hypothetical security feature named "<code>http://features.example.com/2005/securityFeature</code>", which defines, in the abstract, the idea of message confidentiality. This feature has an associated property, named "<code>http://features.example.com/2005/securityFeature/securityLevel</code>", which defines various safety levels (from 0 meaning clear text, all the way through 10, involvig highly complex cryptographic algorithms with keys in the tens of thousands of bits). We also assume that a SOAP module, named "<code>http://features.example.com/2005/modules/Security</code>", has been defined, which implements the security feature described above.</p><p>GreatH has chosen an abstract security feature which is standard in the fictitious hotels community, and has integrated both a SOAP module and a new secure HTTP binding into its infrastructure – both of which implement the security feature (the SOAP module does this inside the SOAP envelope using headers, and the secure binding does it at the transport layer). Now they'd like to advertise and control the usage of these extensions using WSDL 2.0.</p>
<div class="div3">
***************
*** 1429,1433 ****
respect: that versioning is difficult, but you SHOULD
anticipate and plan for change.</p><p>The draft finding on Versioning and Extensibility details two key
! approaches to versioning:</p><ul><li><p>comaptible evolution; and</p></li><li><p>big bang.</p></li></ul><div class="div3">
<h4><a name="adv-versioning-compatible-evolution"></a>7.5.1 Compatible Evolution</h4><p>In <em>compatible evolution</em>, designers are expected to limit changes to
those that are either backward or forward compatible, or both:</p><dl><dt class="label">Backward compatible</dt><dd><p>The receiver behaves
--- 1431,1435 ----
respect: that versioning is difficult, but you SHOULD
anticipate and plan for change.</p><p>The draft finding on Versioning and Extensibility details two key
! approaches to versioning:</p><ul><li><p>compatible evolution; and</p></li><li><p>big bang.</p></li></ul><div class="div3">
<h4><a name="adv-versioning-compatible-evolution"></a>7.5.1 Compatible Evolution</h4><p>In <em>compatible evolution</em>, designers are expected to limit changes to
those that are either backward or forward compatible, or both:</p><dl><dt class="label">Backward compatible</dt><dd><p>The receiver behaves
***************
*** 1588,1592 ****
<h3><a name="adv-RPCstyle"></a>7.7 RPC Style</h3>
! <p>Section <a href="#more-interfaces-op-attr"><b>5.4.1 Operation Attributes</b></a> mentioned that the (optional) <code>style</code> attribute of an interface operation is used to indicate that the operation conforms to a particular pre-defined operation style, or set of constraints. Actually, if desired the <code>style</code> attribute can hold a list of URIs, indicating that the operation simultaneously conforms to multiple styles.</p><p>Operation styles are named using URIs, in order to be unambigous while still permitted new styles to be defined without requiring updates to the WSDL 2.0 language. WSDL 2.0 Part 2 [<cite><a href="#WSDL-PART2">WSDL 2.0 Adjuncts</a></cite>] defines three such operation styles; one of these is the RPC Style (<a href="http://www.w3.org/2002/ws/desc/wsdl20-adjuncts#RPCStyle">RPC Style</a>).</p><p>The <em>RPC Style</em> is designed to facilitate programming language
bindings to WSDL 2.0 constructs. It allows a WSDL 2.0 interface
operation to be easily mapped to a method or function signature, such as a method signature in
--- 1590,1594 ----
<h3><a name="adv-RPCstyle"></a>7.7 RPC Style</h3>
! <p>Section <a href="#more-interfaces-op-attr"><b>5.4.1 Operation Attributes</b></a> mentioned that the (optional) <code>style</code> attribute of an interface operation is used to indicate that the operation conforms to a particular pre-defined operation style, or set of constraints. Actually, if desired the <code>style</code> attribute can hold a list of URIs, indicating that the operation simultaneously conforms to multiple styles.</p><p>Operation styles are named using URIs, in order to be unambiguous while still permitted new styles to be defined without requiring updates to the WSDL 2.0 language. WSDL 2.0 Part 2 [<cite><a href="#WSDL-PART2">WSDL 2.0 Adjuncts</a></cite>] defines three such operation styles; one of these is the RPC Style (<a href="http://www.w3.org/2002/ws/desc/wsdl20-adjuncts#RPCStyle">RPC Style</a>).</p><p>The <em>RPC Style</em> is designed to facilitate programming language
bindings to WSDL 2.0 constructs. It allows a WSDL 2.0 interface
operation to be easily mapped to a method or function signature, such as a method signature in
***************
*** 1671,1675 ****
<h3><a name="adv-message-dispatch"></a>7.8 Enabling Easy Message Dispatch</h3>
! <p>Suppose a WSDL 2.0 document has two input-output operations and uses the same input message schema for both. When the service receives the input message, how will the service know which operation is supposed to be invoked? Although the data contained in a runtime message may be sufficient to distinguish between the operations, this can be a problem for WSDL 2.0 toolkits that are looking only at the message schema, rather than the actual messages. (For example, the toolkit may be operating at designtime, without access to the runtime messages.) This is the problem of <em>dispatch</em>. How can a WSDL 2.0 document be written to ensure easy message dispatch? Strategies include:</p>
<ul><li><p><b>Use unique top-level elements</b>, i.e., ensure that the top-level elements declared in the message schemas are different for different operations. This is probably the most general solution, since it is guaranteed to provide a way to perform dispatch, without preventing toolkits from potentially using other dispatch techniques.</p></li><li><p><b>Include a required extension</b> that enables a particular dispatching convention. This approach makes the dispatching convention explicit, although it may not be supported by every WSDL toolkit. However, as explained in <a href="#adv-optional-versus-required"><b>7.1.1 Optional Versus Required Extensions</b></a>, toolkits that do not natively support the extension could seek manual input, thus permitting a client developer to supply an appropriate module that implements the necessary extension. This strategy has thus permits future WSDL toolkits to support and process the extension automatically, while also ensuring that the extension willbe handled properly by toolkits that are not yet able to process it automatically.</p></li></ul>
<p>To ensure that client and service implementations can easily determine the interface operation under which a received message was sent (even though not every client or service may need to make such a determination), it is considered good practice to follow one of the above strategies when authoring WSDL 2.0 documents.</p>
--- 1673,1677 ----
<h3><a name="adv-message-dispatch"></a>7.8 Enabling Easy Message Dispatch</h3>
! <p>Suppose a WSDL 2.0 document has two input-output operations and uses the same input message schema for both. When the service receives the input message, how will the service know which operation is supposed to be invoked? Although the data contained in a runtime message may be sufficient to distinguish between the operations, this can be a problem for WSDL 2.0 toolkits that are looking only at the message schema, rather than the actual messages. (For example, the toolkit may be operating at design time, without access to the runtime messages.) This is the problem of <em>dispatch</em>. How can a WSDL 2.0 document be written to ensure easy message dispatch? Strategies include:</p>
<ul><li><p><b>Use unique top-level elements</b>, i.e., ensure that the top-level elements declared in the message schemas are different for different operations. This is probably the most general solution, since it is guaranteed to provide a way to perform dispatch, without preventing toolkits from potentially using other dispatch techniques.</p></li><li><p><b>Include a required extension</b> that enables a particular dispatching convention. This approach makes the dispatching convention explicit, although it may not be supported by every WSDL toolkit. However, as explained in <a href="#adv-optional-versus-required"><b>7.1.1 Optional Versus Required Extensions</b></a>, toolkits that do not natively support the extension could seek manual input, thus permitting a client developer to supply an appropriate module that implements the necessary extension. This strategy has thus permits future WSDL toolkits to support and process the extension automatically, while also ensuring that the extension willbe handled properly by toolkits that are not yet able to process it automatically.</p></li></ul>
<p>To ensure that client and service implementations can easily determine the interface operation under which a received message was sent (even though not every client or service may need to make such a determination), it is considered good practice to follow one of the above strategies when authoring WSDL 2.0 documents.</p>
***************
*** 1904,1908 ****
element that has the interface and binding for the Reservation
Details service and whose endpoint address is that of the
! corresponing reservation. This element is used in the definition
of the Reservation List Web service.
</p>
--- 1906,1910 ----
element that has the interface and binding for the Reservation
Details service and whose endpoint address is that of the
! corresponding reservation. This element is used in the definition
of the Reservation List Web service.
</p>
***************
*** 2186,2190 ****
</div>
<div class="div3">
! <h4><a name="reservationDetails_HTTP"></a>7.9.3 Reservation Details Web Service Using HTTP Transfer</h4><p>This section presents a variation on the example in <a href="#reservationDetails"><b>7.9.1 The Reservation Details Web Service</b></a>. It illustrates the use of HTTP transfer operations, GET and PUT, to retrieve and update GreatH hotel reservation details using the Representational State Transfer (REST) architectural style described by Roy Fielding @@bibref@@. REST is a distillation of the architectural properties that Dr. Fielding identified as being vital to the Web's robustness and enormous scalabilty. </p><p>Since each reservation in our example will have a distinct URI, the Reservation Details Web
service can be offered using HTTP GET and HTTP PUT. The binding would be modified as follows:</p><div class="exampleOuter">
<p class="exampleHead" style="text-align: left"><a name="reservationDetails_HTTP_example"></a><i><span>Example 7-19. </span>
--- 2188,2192 ----
</div>
<div class="div3">
! <h4><a name="reservationDetails_HTTP"></a>7.9.3 Reservation Details Web Service Using HTTP Transfer</h4><p>This section presents a variation on the example in <a href="#reservationDetails"><b>7.9.1 The Reservation Details Web Service</b></a>. It illustrates the use of HTTP transfer operations, GET and PUT, to retrieve and update GreatH hotel reservation details using the Representational State Transfer (REST) architectural style described by Roy Fielding @@bibref@@. REST is a distillation of the architectural properties that Dr. Fielding identified as being vital to the Web's robustness and enormous scalability. </p><p>Since each reservation in our example will have a distinct URI, the Reservation Details Web
service can be offered using HTTP GET and HTTP PUT. The binding would be modified as follows:</p><div class="exampleOuter">
<p class="exampleHead" style="text-align: left"><a name="reservationDetails_HTTP_example"></a><i><span>Example 7-19. </span>
***************
*** 2337,2341 ****
<div class="div3">
! <h4><a name="N10FC6"></a>7.10.1 Schemas in Imported Documents</h4>
<p>
In this example, we consider some GreatH Hotel
--- 2339,2343 ----
<div class="div3">
! <h4><a name="N10FC7"></a>7.10.1 Schemas in Imported Documents</h4>
<p>
In this example, we consider some GreatH Hotel
***************
*** 2544,2548 ****
<div class="div3">
! <h4><a name="N11051"></a>7.10.2 Multiple Inline Schemas in One Document</h4>
<p>
A WSDL 2.0 document may define multiple inline
--- 2546,2550 ----
<div class="div3">
! <h4><a name="N11052"></a>7.10.2 Multiple Inline Schemas in One Document</h4>
<p>
A WSDL 2.0 document may define multiple inline
***************
*** 2675,2682 ****
In both of these examples, the <code>schemaLocation</code> attribute was omitted since the WSDL processor was assumed to know how to locate the imported
schemas because they were part of the WSDL documents being processed. The <code>schemaLocation</code> attribute can be used to give the processor a URI reference
! that explictly locates the schemas. A URI reference is a URI plus an optional fragment identifier that indicates part of the resource. For schemas, the fragment should identify
the <code>schema</code> element. The simplest way to accomplish this is to use the <code>id</code> attribute, however XPointer can also be used.
</p><div class="div4">
! <h5><a name="N110AE"></a>7.10.3.1 Using the id Attribute to Identify Inline
Schemas</h5><p>
<a href="#schemaIds.wsdl">Example 7-26</a>
--- 2677,2684 ----
In both of these examples, the <code>schemaLocation</code> attribute was omitted since the WSDL processor was assumed to know how to locate the imported
schemas because they were part of the WSDL documents being processed. The <code>schemaLocation</code> attribute can be used to give the processor a URI reference
! that explicitly locates the schemas. A URI reference is a URI plus an optional fragment identifier that indicates part of the resource. For schemas, the fragment should identify
the <code>schema</code> element. The simplest way to accomplish this is to use the <code>id</code> attribute, however XPointer can also be used.
</p><div class="div4">
! <h5><a name="N110AF"></a>7.10.3.1 Using the id Attribute to Identify Inline
Schemas</h5><p>
<a href="#schemaIds.wsdl">Example 7-26</a>
***************
*** 2792,2796 ****
is the URI of the resource)</p></li><li><p>Operation styles (similarly to MEPs, the URI of an
operation style is the URI of the resource)</p></li></ol></p></li><li><p>All the resources above are given the appropriate types using
! rdf:type stataments (an interface will belong to the class
Interface and an operation within an interface will belong to
the class InterfaceOperation, for example).</p></li><li><p>All relationships in WSDL 2.0 (like an Operation belonging to an
--- 2794,2798 ----
is the URI of the resource)</p></li><li><p>Operation styles (similarly to MEPs, the URI of an
operation style is the URI of the resource)</p></li></ol></p></li><li><p>All the resources above are given the appropriate types using
! rdf:type statements (an interface will belong to the class
Interface and an operation within an interface will belong to
the class InterfaceOperation, for example).</p></li><li><p>All relationships in WSDL 2.0 (like an Operation belonging to an
Received on Thursday, 28 April 2005 00:29:47 UTC