- From: David Booth via cvs-syncmail <cvsmail@w3.org>
- Date: Fri, 01 Apr 2005 18:06:51 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20
In directory hutz:/tmp/cvs-serv7488
Modified Files:
wsdl20-primer.xml
Log Message:
incorporated suggestions from GlenD
Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.43
retrieving revision 1.44
diff -C2 -d -r1.43 -r1.44
*** wsdl20-primer.xml 30 Mar 2005 03:18:26 -0000 1.43
--- wsdl20-primer.xml 1 Apr 2005 18:06:48 -0000 1.44
***************
*** 46,50 ****
Part 1: Core Language
</emph>
! <bibref ref="WSDL-PART1" />
,
<emph>
--- 46,50 ----
Part 1: Core Language
</emph>
! <bibref ref="WSDL-PART1"/>
,
<emph>
***************
*** 52,56 ****
Part 2: Adjuncts
</emph>
! <bibref ref="WSDL-PART2" />
). It is intended for readers who wish to have an
easier, less technical introduction to the main features
--- 52,56 ----
Part 2: Adjuncts
</emph>
! <bibref ref="WSDL-PART2"/>
). It is intended for readers who wish to have an
easier, less technical introduction to the main features
***************
*** 122,126 ****
<p>This section introduces the basic concepts used in WSDL 2.0 through the description of a hypothetical hotel reservation service. We start with a simple scenario, and later add more requirements to illustrate how more advanced WSDL2.0 features may be used. </p>
! <!-- ************************ GreatH *************************** --><div2 id="basics-greath-scenario"><head>Example Scenario: The GreatH Hotel Reservation Service</head><p>Hotel GreatH is located in a remote island. It has been relying on fax and phone to provide room reservations. Even though the facilities and prices at GreatH are better than what its competitor offers, GreatH notices that its competitor is getting more customers than GreatH. After research, GreatH realizes that this is because the competitor offers a Web service that permits travel agent reservation systems to reserve rooms directly over the Internet. GreatH then hires us to build a reservation Web service with the following functionality: <ulist><item><p><emph>CheckAvailability</emph>. To check availability, the client must specify a check-in date, a check-out date, and room type room, and the Web service will provide the room rate if such a room is available. If any input data is invalid, the service should return an error. hus, the service will accept a <code>checkAvailability</code> message and return a <code>checkAvailabilityResponse</code> or <code>invalidDataFault</code> message.</p> </item><item><p><emph>MakeReservation</emph>. To make a reservation, a client must provide a name, address, and credit card information, and the service will return a confirmation number if the reservation is successful. The service will return an error message if the credit card number or any other data field is invalid. Thus, the service will accept a <code>makeReservation</code> message and return a <code>makeReservationResponse</code> or <code>invalidCreditCardFault</code> message.</p></item></ulist> We know that we will later need to build a complete system that supports transactions and secured transmission, but initially we will implement only minimal functionality. In fact, to simplify our first example, we will implement only the <emph>CheckAvailability</emph> operation. </p><p>The next several sections proceed step-by-step thrugh the process of developing a WSDL 2.0 document that describes the desired Web service. However, for those who can't wait to see a complete example, here is the WSDL 2.0 document that we'll be creating.</p><example id="example-initial">
<head>WSDL 2.0 Document for the GreatH Web Service (Initial Example)</head>
<eg><![CDATA[
--- 122,126 ----
<p>This section introduces the basic concepts used in WSDL 2.0 through the description of a hypothetical hotel reservation service. We start with a simple scenario, and later add more requirements to illustrate how more advanced WSDL2.0 features may be used. </p>
! <!-- ************************ GreatH *************************** --><div2 id="basics-greath-scenario"><head>Example Scenario: The GreatH Hotel Reservation Service</head><p>Hotel GreatH is located in a remote island. It has been relying on fax and phone to provide room reservations. Even though the facilities and prices at GreatH are better than what its competitor offers, GreatH notices that its competitor is getting more customers than GreatH. After research, GreatH realizes that this is because the competitor offers a Web service that permits travel agent reservation systems to reserve rooms directly over the Internet. GreatH then hires us to build a reservation Web service with the following functionality: <ulist><item><p><emph>CheckAvailability</emph>. To check availability, the client must specify a check-in date, a check-out date, and room type. The Web service will return a room rate (a floating point number in $USD) if such a room is available, or a zero room rate if not. If any input dat is invalid, the service should return an error. Thus, the service will accept a <code>checkAvailability</code> message and return a <code>checkAvailabilityResponse</code> or <code>invalidDataFault</code> message.</p> </item><item><p><emph>MakeReservation</emph>. To make a reservation, a client must provide a name, address, and credit card information, and the service will return a confirmation number if the reservation is successful. The service will return an error message if the credit card number or any other data field is invalid. Thus, the service will accept a <code>makeReservation</code> message and return a <code>makeReservationResponse</code> or <code>invalidCreditCardFault</code> message.</p></item></ulist> We know that we will later need to build a complete system that supports transactions and secured transmission, but initially we will implement only minimal functionality. In fact, to simplify our first example, we will implement only the <emph>CheckAvailability</emph> operation. </p><pThe next several sections proceed step-by-step through the process of developing a WSDL 2.0 document that describes the desired Web service. However, for those who can't wait to see a complete example, here is the WSDL 2.0 document that we'll be creating.</p><example id="example-initial">
<head>WSDL 2.0 Document for the GreatH Web Service (Initial Example)</head>
<eg><![CDATA[
***************
*** 295,299 ****
. . .
! </description>]]></eg></example><div3 id="example-initial-interface-explanation"><head>Explanation of Example</head><glist><gitem><label><code><interface name = "reservationInterface" ></code></label><def><p>Interfaces are declared directly inside the <code>description</code> element. In this example, we are declaring only one interface, but in general a WSDL document may declare more than one interface (each one for use with a different service). Thus, each interface must be given a name that is unique within the set of interfaces defined in this WSDL target namespace. Interface names are tokens that must not contain a space or colon (":").</p></def></gitem><gitem><label><code><fault name = "invalidDataFault"
</code></label><def><p>The <code>name</code> attribute defines a name for this fault. The name is required so that when an operation is defined, it can reference the desired fault by name. Fault names must unique within an interface.</p></def></gitem><gitem><label><code>element = "ghns:invalidDataError"/></code></label><def><p>The <code>element</code> attribute specifies the schema type of the fault message, as previously defined in the <code>types</code> section. </p></def></gitem><gitem><label><code><operation name="opCheckAvailability"</code></label><def><p>The <code>name</code> attribute defines a name for this operation, so that it can be referenced later when bindings are defined. Operation names must also be unique within an interface. (WSDL 2.0 uses separate symbol spaces for operation and fault names, so operation name "foo" is distinct from fault name "foo".)</p></def></gitem><gitem><label><code>pattern="http://www.w3.org/2004/03/wsdl/in-out" ></code></label><def><p>Ths line specifies that this operation will use the <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref> pattern as described above. WSDL 2.0 uses URIs to identify message exchange patterns in order to ensure that they are uambiguously identified, while also permitting future new patterns to be defined by anyone. (However, just because someone defines a new pattern and creates a URI to identify it, that does <emph>not</emph> mean that other WSDL processors will automatically recognize or understand that pattern. As with any other extension, it can be used among processors that do recognize and understand it.)</p></def></gitem><gitem><label><code><input messageLabel="In"</code></label><def><p>The <code>input</code> element specifies an input message. Even though we have already specified which message exchange pattern the operation will use, a message exchange pattern represents a template for a message sequence, and in general it may consist of multiple inpt and/or output messages. Thus we must also indicate which potential input message in the pattern this particular input message represents. This is the purpose of the <code>messageLabel</code> attribute. Since the <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref> pattern that we've chosen to use only has one input message, it is trivial in this case: we simply fill in the message label "In" that was defined in <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSDL-PART2"/> section 2.2.3 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">In-Out</xspecref> for the <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref> pattern. However, in theory, new patterns could be defined that involve multiple input messages, and the different input messages in the pattern would be distinguished by having different labels.</p></def></gitem><gitem><label><code>element="ghns:checkAvailabiliy" /></code></label><def><p>This specifies the message type for this input message, as defined previously in the <code>types</code> section.</p></def></gitem><gitem><label><code><output messageLabel="Out" . . .</code></label><def><p>This is similar to defining an input message.</p></def></gitem><gitem><label><code><outfault ref="tns:invalidDataFault" messageLabel="Out"/></code></label><def><p>This associates an output fault with this operation. Faults are declared a little differently than normal messages. The <code>ref</code> attribute refers to the name of a previously defined fault in this interface -- not a message schema type directly. Since message exchange patterns could in general involve a sequence of several messages, a fault could potentially occur at various points within the message sequence. Because one may wish to associate a different fault with each permitted point in the sequence, the messageLabel is used to indicate the desired point for this particular fault. It does so idirectly by specifying the message that will either trigger this fault or that this fault will replace, depending on the pattern. (Some patterns use a <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-trigger">message-triggers-fault rule</xspecref>; others use a <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-replacement">fault-replaces-message</xspecref> rule. See <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSDL-PART2"/> section 2.1.2 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-trigger">Message Triggers Fault</xspecref> and section 2.1.1 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-replacement">Fault Replaces Message</xspecref>.) </p></def></gitem></glist><p>Now that we've defined the abstract interface for the GreatH service, we're ready to define a binding for it.</p><ednote><name>dbooth</name><edtext>[This note is only relevant to the editors.] Hmm, I just reaized that in the source XML for this primer, in some cases we've been using <el> to indicate an element name, and in other cases we've been using <code>. At present, the xmlspec XSLT script seems to translate them both into <code> elements in the generated HTML, but we should probably make them consistent, in case that changes. </edtext></ednote></div3></div2>
--- 295,299 ----
. . .
! </description>]]></eg></example><div3 id="example-initial-interface-explanation"><head>Explanation of Example</head><glist><gitem><label><code><interface name = "reservationInterface" ></code></label><def><p>Interfaces are declared directly inside the <code>description</code> element. In this example, we are declaring only one interface, but in general a WSDL document may declare more than one interface. Thus, each interface must be given a name that is unique within the set of interfaces defined in this WSDL target namespace. Interface names are tokens that must not contain a space or colon (":").</p></def></gitem><gitem><label><code><fault name = "invalidDataFault"
</code></label><def><p>The <code>name</code> attribute defines a name for this fault. The name is required so that when an operation is defined, it can reference the desired fault by name. Fault names must unique within an interface.</p></def></gitem><gitem><label><code>element = "ghns:invalidDataError"/></code></label><def><p>The <code>element</code> attribute specifies the schema type of the fault message, as previously defined in the <code>types</code> section. </p></def></gitem><gitem><label><code><operation name="opCheckAvailability"</code></label><def><p>The <code>name</code> attribute defines a name for this operation, so that it can be referenced later when bindings are defined. Operation names must also be unique within an interface. (WSDL 2.0 uses separate symbol spaces for operation and fault names, so operation name "foo" is distinct from fault name "foo".)</p></def></gitem><gitem><label><code>pattern="http://www.w3.org/2004/03/wsdl/in-out" ></code></label><def><p>Ths line specifies that this operation will use the <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref> pattern as described above. WSDL 2.0 uses URIs to identify message exchange patterns in order to ensure that they are uambiguously identified, while also permitting future new patterns to be defined by anyone. (However, just because someone defines a new pattern and creates a URI to identify it, that does <emph>not</emph> mean that other WSDL processors will automatically recognize or understand that pattern. As with any other extension, it can be used among processors that do recognize and understand it.)</p></def></gitem><gitem><label><code><input messageLabel="In"</code></label><def><p>The <code>input</code> element specifies an input message. Even though we have already specified which message exchange pattern the operation will use, a message exchange pattern represents a template for a message sequence, and in general it may consist of multiple inpt and/or output messages. Thus we must also indicate which potential input message in the pattern this particular input message represents. This is the purpose of the <code>messageLabel</code> attribute. Since the <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref> pattern that we've chosen to use only has one input message, it is trivial in this case: we simply fill in the message label "In" that was defined in <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSDL-PART2"/> section 2.2.3 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">In-Out</xspecref> for the <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#in-out">in-out</xspecref> pattern. However, in theory, new patterns could be defined that involve multiple input messages, and the different input messages in the pattern would be distinguished by having different labels.</p></def></gitem><gitem><label><code>element="ghns:checkAvailabiliy" /></code></label><def><p>This specifies the message type for this input message, as defined previously in the <code>types</code> section.</p></def></gitem><gitem><label><code><output messageLabel="Out" . . .</code></label><def><p>This is similar to defining an input message.</p></def></gitem><gitem><label><code><outfault ref="tns:invalidDataFault" messageLabel="Out"/></code></label><def><p>This associates an output fault with this operation. Faults are declared a little differently than normal messages. The <code>ref</code> attribute refers to the name of a previously defined fault in this interface -- not a message schema type directly. Since message exchange patterns could in general involve a sequence of several messages, a fault could potentially occur at various points within the message sequence. Because one may wish to associate a different fault with each permitted point in the sequence, the messageLabel is used to indicate the desired point for this particular fault. It does so idirectly by specifying the message that will either trigger this fault or that this fault will replace, depending on the pattern. (Some patterns use a <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-trigger">message-triggers-fault rule</xspecref>; others use a <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-replacement">fault-replaces-message</xspecref> rule. See <emph>WSDL 2.0 Predefined Extensions</emph> <bibref ref="WSDL-PART2"/> section 2.1.2 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-trigger">Message Triggers Fault</xspecref> and section 2.1.1 <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-extensions-20040803/#fault-replacement">Fault Replaces Message</xspecref>.) </p></def></gitem></glist><p>Now that we've defined the abstract interface for the GreatH service, we're ready to define a binding for it.</p><ednote><name>dbooth</name><edtext>[This note is only relevant to the editors.] Hmm, I just reaized that in the source XML for this primer, in some cases we've been using <el> to indicate an element name, and in other cases we've been using <code>. At present, the xmlspec XSLT script seems to translate them both into <code> elements in the generated HTML, but we should probably make them consistent, in case that changes. </edtext></ednote></div3></div2>
***************
*** 329,336 ****
Part 2: Adjuncts
</emph>
! <bibref ref="WSDL-PART2" />
, section 4.3
! <xspecref
! href="http://www.w3.org/TR/2004/WD-wsdl20-adjuncts/#soap-defaults">
Default Binding Rules
</xspecref>
--- 329,335 ----
Part 2: Adjuncts
</emph>
! <bibref ref="WSDL-PART2"/>
, section 4.3
! <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-adjuncts/#soap-defaults">
Default Binding Rules
</xspecref>
***************
*** 380,384 ****
. . .
</description>]]></eg>
! </example><div3 id="example-initial-binding-explanation"><head>Explanation of Example</head><glist><gitem><label><code>xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"</code></label><def><p>We've added two more namespace declarations. This one is the namespace for the SOAP 1.2 binding construct that is defined in WSDL 2.0 Part 3 <bibref ref="SOAP12-PART1"/>. Elements and attributes prefixed with <code>wsoap:</code> are constructs defined there. </p></def></gitem><gitem><label><code>xmlns:soap="http://www.w3.org/2003/05/soap-envelope"</code></label><def><p>This namespace is defined by the SOAP 1.2 specification itself. The SOAP 1.2 specification defines certain terms within this namespace to unambiguously identify particular concepts. Thus, we will use the <code>soap:</code> prefix when we need to refer to one of those terms.</p></def></gitem><gitem><label><code><binding name="reservationSOAPBinding"</code></label><def><p>Bindings are declared directly inside the <code>description</code>element. The <att>name</att> attribute defines a name for this binding. Each name must be unique among all bindings in this WSDL target namespace, and will be used later when we define a service endpoint that references this binding. WSDL 2.0 uses separate symbol spaces for interfaces, bindings and services, so interface "foo", binding "foo" and service "foo" are all distinct. </p></def></gitem><gitem><label><code>interface="tns:reservationInterface"</code></label><def><p>This is the name of the interface whose message format and transmission protocols we are specifying. As discussed in <specref ref="more-bindings"/>, a reusable binding can be defined by omitting the <att>interface</att> attribute. Note also the use of the <code>tns:</code> prefix, which refers to the previously defined WSDL target namespace for this WSDL document. In this case it may seem silly to have to specify the <code>tns:</code> prefix, but in <specref ref="adv-import-and-authoring"/>we will see how WSDL 2.0's import mechanismcan be used to combine components that are defined in different WSDL target namespaces.</p></def></gitem><gitem><label><code>type="http://www.w3.org/2004/08/wsdl/soap12"</code></label><def><p>This specifies the type of concrete message format to use, in this case SOAP 1.2.</p></def></gitem><gitem><label><code>wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP"</code></label><def><p>This attribute is specific to WSDL 2.0's SOAP binding (thus it uses the <code>wsoap:</code> prefix). It specifies the underlying transmission protocol that should be used, in this case HTTP. </p></def></gitem><gitem><label><code><operation ref="tns:opCheckAvailability"</code></label><def>
<p>
This not defining a new operation. Rather, it is referencing the
--- 379,383 ----
. . .
</description>]]></eg>
! </example><div3 id="example-initial-binding-explanation"><head>Explanation of Example</head><glist><gitem><label><code>xmlns:wsoap= "http://www.w3.org/2004/08/wsdl/soap12"</code></label><def><p>We've added two more namespace declarations. This one is the namespace for the SOAP 1.2 binding construct that is defined in WSDL 2.0 Part 3 <bibref ref="SOAP12-PART1"/>. Elements and attributes prefixed with <code>wsoap:</code> are constructs defined there. </p></def></gitem><gitem><label><code>xmlns:soap="http://www.w3.org/2003/05/soap-envelope"</code></label><def><p>This namespace is defined by the SOAP 1.2 specification itself. The SOAP 1.2 specification defines certain terms within this namespace to unambiguously identify particular concepts. Thus, we will use the <code>soap:</code> prefix when we need to refer to one of those terms.</p></def></gitem><gitem><label><code><binding name="reservationSOAPBinding"</code></label><def><p>Bindings are declared directly inside the <code>description</code>element. The <att>name</att> attribute defines a name for this binding. Each name must be unique among all bindings in this WSDL target namespace, and will be used later when we define a service endpoint that references this binding. WSDL 2.0 uses separate symbol spaces for interfaces, bindings and services, so interface "foo", binding "foo" and service "foo" are all distinct. </p></def></gitem><gitem><label><code>interface="tns:reservationInterface"</code></label><def><p>This is the name of the interface whose message format and transmission protocols we are specifying. As discussed in <specref ref="more-bindings"/>, a reusable binding can be defined by omitting the <att>interface</att> attribute. Note also the use of the <code>tns:</code> prefix, which refers to the previously defined WSDL target namespace for this WSDL document. In this case it may seem silly to have to specify the <code>tns:</code> prefix, but in <specref ref="adv-import-and-authoring"/> we will see how WSDL 2.0's import mechanis can be used to combine components that are defined in different WSDL target namespaces.</p></def></gitem><gitem><label><code>type="http://www.w3.org/2004/08/wsdl/soap12"</code></label><def><p>This specifies the type of concrete message format to use, in this case SOAP 1.2.</p></def></gitem><gitem><label><code>wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP"</code></label><def><p>This attribute is specific to WSDL 2.0's SOAP binding (thus it uses the <code>wsoap:</code> prefix). It specifies the underlying transmission protocol that should be used, in this case HTTP. </p></def></gitem><gitem><label><code><operation ref="tns:opCheckAvailability"</code></label><def>
<p>
This not defining a new operation. Rather, it is referencing the
***************
*** 389,396 ****
supply the necessary information. (See the SOAP binding in
<emph>WSDL 2.0 Bindings</emph>
! <bibref ref="WSDL-PART2" />
section 4.3
! <xspecref
! href="http://www.w3.org/TR/2004/WD-wsdl20-adjuncts/#soap-defaults">
Default Binding Rules
</xspecref>.)
--- 388,394 ----
supply the necessary information. (See the SOAP binding in
<emph>WSDL 2.0 Bindings</emph>
! <bibref ref="WSDL-PART2"/>
section 4.3
! <xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-adjuncts/#soap-defaults">
Default Binding Rules
</xspecref>.)
***************
*** 561,565 ****
<head>Order of WSDL Elements and Placement of Extensions</head>
! <p>The order of the WSDL2.0 elmenets matters. Though the WSDL2.0 schema doesn't require the elements be placed in any order, the specification (part 1 section 2.1.2) clearly states a set of constraints about how the children elements of the <code>description</code> element should be ordered. The following is a pseudo-content model of <code>description</code> </p>
<eg xml:space="preserve">
--- 559,563 ----
<head>Order of WSDL Elements and Placement of Extensions</head>
! <p>The order of the WSDL2.0 elements matters. Though the WSDL2.0 schema doesn't require the elements be placed in any order, the specification (part 1 section 2.1.2) clearly states a set of constraints about how the children elements of the <code>description</code> element should be ordered. The following is a pseudo-content model of <code>description</code> </p>
<eg xml:space="preserve">
***************
*** 1085,1089 ****
which allow one to specify default bindings for all operations
(for example, see the SOAP binding in <emph>WSDL 2.0 Bindings</emph>
! <bibref ref="WSDL-PART2" />
section 4.3
<xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-adjuncts/#soap-defaults">Default Binding Rules</xspecref>) or by directly
--- 1083,1087 ----
which allow one to specify default bindings for all operations
(for example, see the SOAP binding in <emph>WSDL 2.0 Bindings</emph>
! <bibref ref="WSDL-PART2"/>
section 4.3
<xspecref href="http://www.w3.org/TR/2004/WD-wsdl20-adjuncts/#soap-defaults">Default Binding Rules</xspecref>) or by directly
***************
*** 1485,1489 ****
The hotel reservation service declares that it is using
components from another namespace via the
! <code>import</code>>
element. The import element has a required
<code>namespace</code>
--- 1483,1487 ----
The hotel reservation service declares that it is using
components from another namespace via the
! <code>import</code>>
element. The import element has a required
<code>namespace</code>
***************
*** 1516,1521 ****
</div2><div2 id="adv-multiple-docs-describing-same-service">
! <head>Multiple Logical WSDL Documents Describing the Same Service</head>
! <p>[Acknowledge that multiple logical WSDL documents might try to describe the same service. Explain why some might do this intentionally, why it might cause problems for some systems, and explain that this is outside scope of the WSDL language. See thread starting at http://lists.w3.org/Archives/Public/www-ws-desc/2003Dec/0045.html ]</p>
</div2><div2 id="adv-versioning">
<head>Versioning and Service Equivalency</head>
--- 1514,1521 ----
</div2><div2 id="adv-multiple-docs-describing-same-service">
! <head>Multiple Interfaces for the Same Service</head>
! <p>Suppose a Web service wishes to expose two different interfaces: a customer interface for its regular users, and a management interface for its operator. WSDL 2.0 limits a wsdl:service to a single wsdl:interface, and does not provide any mechanisms to formally indicate this kind of relationship between interfaces. How can service providers work around this limitation? Conventions outside of the WSDL 2.0 language can be used, but since they are outside of the WSDL 2.0 language (and therefore neither endorsed nor forbidden by the WSDL 2.0 specification) the WSDL 2.0 specification cannot define or standardize their semantics. With that caveat in mind, potential workarounds include:<ulist><item><p><b>Declare both interfaces in the same wsdl:description element.</b> Although WSDL 2.0 does not ascribe any particular significance to the fact that two wsdl:services are declared within the same wsdl:description, an application or toolkit could interpret this to mean that they are related in some way.<p></item><item><p><b>Declare both interfaces in the same wsdl:targetNamespace.</b> Again, although WSDL 2.0 does not ascribe any particular significance to the fact that two wsdl:services are declared within the same wsdl:targetNamespace, an application or toolkit could interpret this to mean that they are related in some way.
! </p></item><item><p><b>Add an extension to WSDL 2.0</b> that links together all services that are related in this way. WSDL 2.0's open content model permits extension elements from other namespaces to appear in a WSDL document.</p></item><item><p><b>Declare them in completely separate WSDL documents, but use the same endpoint address for both.</b> I.e., declare a wsdl:interface and wsdl:service for the customer interface in one WSDL document, and a wsdl:interface and wsdl:service for the management interface in a different WSDL document, but use the same endpoint address for both. (By "different WSDL document" we mean that both documents are never included or imported into the same WSDL 2.0 descriptions component.) Although this approach may work in some circumstances, it means that the same endpoint address would be used for two different purposes, which is apt to cause confusion or ambiguity. Furthermore, it is contrary to the Web architectural principle that different URIs should be used to identiy different Web resources. [Ref W3C TAB WebArch http://www.w3.org/TR/webarch/#URI-collision ]
! </p></item><item><p><b>Use inheritance to combine the customer interface and management interface</b> into a single, larger wsdl:interface. Of course, this reduces modularity and means that the management interface becomes exposed to the customers, which is not good. </p></item></ulist></p>
</div2><div2 id="adv-versioning">
<head>Versioning and Service Equivalency</head>
***************
*** 1724,1728 ****
Reservation Detail Web service that can retrieve and
update the state of a reservation.
! <specref ref='reservationDetails-OMX736.xml' />
shows the format of the reservation detail.
</p>
--- 1724,1728 ----
Reservation Detail Web service that can retrieve and
update the state of a reservation.
! <specref ref="reservationDetails-OMX736.xml"/>
shows the format of the reservation detail.
</p>
***************
*** 1813,1817 ****
<p>
! <specref ref="reservationDetails.xsd" /> shows the XML schema elements that are used in this Web service.
</p>
--- 1813,1817 ----
<p>
! <specref ref="reservationDetails.xsd"/> shows the XML schema elements that are used in this Web service.
</p>
***************
*** 1962,1966 ****
</ednote>
<p>
! <specref ref="reservationList-all.xml" />
shows the format of the response from the
Reservation List service.
--- 1962,1966 ----
</ednote>
<p>
! <specref ref="reservationList-all.xml"/>
shows the format of the response from the
Reservation List service.
***************
*** 2048,2052 ****
<p>
! <specref ref="reservationList.wsdl" />
shows the description of the Reservation List
Web service. Note that is contains operations to
--- 2048,2052 ----
<p>
! <specref ref="reservationList.wsdl"/>
shows the description of the Reservation List
Web service. Note that is contains operations to
***************
*** 2265,2269 ****
<p>
! <specref ref="retrieveDetails.wsdl" />
shows the definition of the retrieval Web
service in the
--- 2265,2269 ----
<p>
! <specref ref="retrieveDetails.wsdl"/>
shows the definition of the retrieval Web
service in the
***************
*** 2337,2341 ****
<p>
! <specref ref="updateDetails.wsdl" />
shows the definition of the updating Web service
in the
--- 2337,2341 ----
<p>
! <specref ref="updateDetails.wsdl"/>
shows the definition of the updating Web service
in the
***************
*** 2480,2484 ****
<p>
To illustrate this, consider
! <specref ref="retrieveItems.wsdl" />
which contains two inline schemas. The
<code>
--- 2480,2484 ----
<p>
To illustrate this, consider
! <specref ref="retrieveItems.wsdl"/>
which contains two inline schemas. The
<code>
***************
*** 2609,2613 ****
</head>
<p>
! <specref ref="schemaIds.wsdl" />
shows the use of the
<code>id</code>
--- 2609,2613 ----
</head>
<p>
! <specref ref="schemaIds.wsdl"/>
shows the use of the
<code>id</code>
***************
*** 2821,2830 ****
</bibl>
! <bibl key="WSDL 2.0 Adjuncts"
! href="&w3c-designation-part2;" id="WSDL-PART2">
<titleref>
Web Services Description Language (WSDL)
Version 2.0 Part 2: Adjuncts
! </titleref>, M. Gudgin, H. Haas, P. Le Hégaret, A.
Lewis, J-J. Moreau, D. Orchard, J. Schlimmer, S.
Weerawarana, Editors. World Wide Web Consortium,
--- 2821,2829 ----
</bibl>
! <bibl key="WSDL 2.0 Adjuncts" href="&w3c-designation-part2;" id="WSDL-PART2">
<titleref>
Web Services Description Language (WSDL)
Version 2.0 Part 2: Adjuncts
! </titleref>, M. Gudgin, H. Haas, P. Le Hégaret, A.
Lewis, J-J. Moreau, D. Orchard, J. Schlimmer, S.
Weerawarana, Editors. World Wide Web Consortium,
***************
*** 2975,2980 ****
-->
! <bibl key="SOAP MTOM" id="SOAP-MTOM"
! href="http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/">
<titleref>
SOAP Message Transmission Optimization
--- 2974,2978 ----
-->
! <bibl key="SOAP MTOM" id="SOAP-MTOM" href="http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/">
<titleref>
SOAP Message Transmission Optimization
***************
*** 2985,2990 ****
Transmission Optimization Mechanism is available
at
! <loc
! href="http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/"/>
http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/.
</bibl>
--- 2983,2987 ----
Transmission Optimization Mechanism is available
at
! <loc href="http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/"/>
http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/.
</bibl>
Received on Friday, 1 April 2005 18:06:56 UTC