- From: Paul Downey via cvs-syncmail <cvsmail@w3.org>
- Date: Thu, 23 Jun 2005 17:35:00 +0000
- To: public-ws-desc-eds@w3.org
Update of /sources/public/2002/ws/desc/wsdl20
In directory hutz:/tmp/cvs-serv13510/2002/ws/desc/wsdl20
Modified Files:
wsdl20-primer.xml wsdl20-primer.html
Log Message:
added Dave Orchard's text and examples for Versioning and Extensibility
Index: wsdl20-primer.xml
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.xml,v
retrieving revision 1.104
retrieving revision 1.105
diff -C2 -d -r1.104 -r1.105
*** wsdl20-primer.xml 22 Jun 2005 14:35:01 -0000 1.104
--- wsdl20-primer.xml 23 Jun 2005 17:34:57 -0000 1.105
***************
*** 1955,1959 ****
--- 1955,2151 ----
</div3>
+
+
+ <div3 id="adv-versioning-examples">
+ <head>Examples of Versioning and Extending a Service</head>
+ <div4>
+ <head>Additional Optional Elements Added in Content</head>
+ <p> The following example demonstrates how content may be extended with
+ additional content. The reservation service can accept an optional
+ number of guests parameter. The service provider wants existing clients
+ to continue to be able to use the service. The author adds the element
+ into the schema as an optional element. </p>
+ <example id="example-versioning-additional-elements">
+ <head>XML Schema with Optional Elements</head>
+ <eg><![CDATA[
+ <xs:complexType name="tCheckAvailability">
+ <xs:sequence>
+ <xs:element name="checkInDate" type="xs:date"/>
+ <xs:element name="checkOutDate" type="xs:date"/>
+ <xs:element name="roomType" type="xs:string"/>
+ <xs:element name="numberOfGuests" type="xs:integer" minOccurs="0"/>
+ <xs:any namespace="##other" processContents="lax"/>
+ </xs:sequence>
+ </xs:complexType>
+ ]]></eg>
+ </example>
+ <p> The author has the choice of keeping the same namesapce or using a
+ different namespace for the additional content and the existing content.
+ In this scenario, it is a compatible change and the author decides to
+ keep the same namespace. This allows existing clients to interact with a
+ new service, and it allows newer clients to interact with older
+ services. </p>
+ </div4>
+ <div4>
+ <head>Additional Optional Elements Added to a Header</head>
+ <p> Another option is to add the extension as a header block. This is
+ accomplished by defining an element for the extension and adding a
+ header element that references the element into the binding operation as
+ child of the input. </p>
+ <example id="example-versioning-additional-header-elements">
+ <head>Additional optional elements added to a SOAP header</head>
+ <eg><![CDATA[
+ <xs:element name="NumberOfGuests" type="tNumberOfGuests"/>
+ <xs:complexType name="tNumberOfGuests">
+ <xs:sequence>
+ <xs:element name="numberOfGuests" type="xs:integer" minOccurs="0"/>
+ </xs:sequence>
+ </xs:complexType>
+
+ <binding name="reservationSOAPBinding"
+ interface="tns:reservationInterface"
+ type="http://www.w3.org/2005/05/wsdl/soap"
+ wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP">
+
+ <operation ref="tns:opCheckAvailability">
+ <input>
+ <wsoap:header element="tns:NumberOfGuests"/>
+ </input>
+ </operation>
+ ...
+ </binding>
+ ]]></eg>
+ </example>
+ <p> It is also possible for the header to be marked with soap:mustUnderstand
+ set to true. The HTTP Binding has similar functionality though without a
+ mustUnderstand attribute.</p>
+ </div4>
+ <div4>
+ <head>Additional Mandatory Elements in Content</head>
+ <p> This following example demonstrates an extention with additional
+ content. The reservation service requires a number of guests parameter.
+ The service provider wants existing clients to be unable to use the
+ service. The author adds the element into the schema as a mandatory
+ element.</p>
+ <example id="example-versioning-additional-mandatory-elements">
+ <head>Additional Mandadtory Elements in Content</head>
+ <eg><![CDATA[
+ <xs:complexType name="tCheckAvailabilityV2">
+ <xs:sequence>
+ <xs:element name="checkInDate" type="xs:date"/>
+ <xs:element name="checkOutDate" type="xs:date"/>
+ <xs:element name="roomType" type="xs:string"/>
+ <xs:element name="numberOfGuests" type="xs:integer"/>
+ <xs:any namespace="##other" processContents="lax"/>
+ </xs:sequence>
+ </xs:complexType>
+ ]]></eg>
+ </example>
+ <p> The author has the choice of keeping the same namespace or using a
+ different namespace for the additional content and the existing content.
+ In this scenario, it is an incompatible change and the author decides to
+ use a new name but the same namespace. This type is then used in the
+ interface operation, and then binding and service endpoints.</p>
+ </div4>
+ <div4>
+ <head>Additional Optional Operation Added to Interface</head>
+ <p> Section <specref ref="more-interfaces-inheritance"/> shows another type
+ of versioning or extension, where the reservationInterface extends the
+ MessageLogInterface. By definition of interface inheritance, a client
+ that understands just the MessageLogInterface will continue to work with
+ the reservationInterface, that it is backwards compatible.</p>
+ </div4>
+ <div4>
+ <head>Additional Mandatory Operation Added to Interface</head>
+ <p> Often mandatory operations are added to an interface. The Hotel service
+ decides to add an operation to the reservation service which is a
+ confirmation. The Hotel service requires that all clients upgrade to the
+ new interface to use the service. They have a variety of options for
+ indicating that the old interface is deprecated.</p>
+ <p> By the definition of interface inheritance, they cannot use interface
+ inheritance for defining the extension.</p>
+ <example id="example-versioning-additional-mandatory-operation">
+ <head>Additional Mandatory Operation Added to the Interface</head>
+ <eg><![CDATA[
+ <interface name="reservationWithConfirmation" extends="cc:creditCardFaults">
+ ...
+ <operation name="makeReservation"
+ <input messageLabel="In" element="ghns:makeReservation" />
+ <output messageLabel="Out" element="ghns:makeReservationResponse" />
+ <outfault ref="invalidDataFault" messageLabel="Out" />
+ <outfault ref="cc:cancelledCreditCard" messageLabel="Out" />
+ <outfault ref="cc:expiredCreditCard" messageLabel="Out" />
+ <outfault ref="cc:invalidCreditCardNumber" messageLabel="Out" />
+ <outfault ref="cc:invalidExpirationDate" messageLabel="Out" />
+ </operation>
+ <operation name="confirmReservation"
+ <input messageLabel="In" element="ghns:makeReservationResponse" />
+ <output messageLabel="Out" element="ghns:confirmReservationResponse" />
+ <outfault ref="expiredReservation" messageLabel="Out" />
+ </operation>
+ </interface>
+ ]]></eg>
+ </example>
+ <p> This interface cannot be bound and deployed at the existing URI and
+ indicate incompatibility, as the service will still accept the
+ makeReservation request. Changing the name of the interface from
+ reservation to reservationWithConfirmation or changing the name of the
+ operation from makeReservation to makeReservationV2 does not affect the
+ messages that are exchanged. Thus it can't be used as a mechanism for
+ indicating incompatibility. To indicate incompatibility, a change must
+ be made to something that appears in the message. For a SOAP over HTTP
+ request, the list is roughly the URI, the SOAP Action HTTP Header, or
+ the Message content.</p>
+ </div4>
+ <div4>
+ <head>Indicating Incompatibility by Changing the Endpoint URI</head>
+ <p> To indicate incompatibility, the URI of the Hotel Endpoint can be
+ changed and messages send to the old Endpoint return a Fault.</p>
+ </div4>
+ <div4>
+ <head>Indicating Incompatibility by Changing the SOAP Action</head>
+ <p> The SOAP Action can be set for the makeReservation request, and making
+ it different than the earlier version should indicate incompatibility.</p>
+ <example id="example-versioning-SOAP-Action">
+ <head>Indicating Incompatibility by changing the SOAP Action</head>
+ <eg><![CDATA[
+ <binding name="reservationSOAPBinding"
+ interface="tns:reservationInterface"
+ type="http://www.w3.org/2005/05/wsdl/soap"
+ wsoap:protocol="http://www.w3.org/2003/05/soap/bindings/HTTP">
+ <operation ref="tns:makeReservation"
+ wsoap:action="tns:makeReservationV2"/>
+ . . .
+ ]]></eg>
+ </example>
+ <p> Note that this mechanism is applicable on a per-binding basis. The SOAP
+ HTTP Binding provides for setting Action, but other bindings may not
+ provide such a facility.</p>
+ </div4>
+ <div4>
+ <head>Indicating Incompatibility by Changing the Element Content</head>
+ <p> The namespace or name of the makeReservation element can be changed, and
+ then the interface and bindings changed. To indicate incompatibility,
+ requests using the old makeReservation Qname should probably return a
+ fault. The new interface, with a changed makeReservation, is:</p>
+ <example id="example-versioning-changing-element-content">
+ <head>Indicating incompatibility by changing the element content</head>
+ <eg><![CDATA[
+ <interface>
+ <xs:element name="ghns2:makeReservation" type="ghns:tmakeReservation"/>
+ <interface . . .>
+ . . .
+ <input messageLabel="In" element="ghns2:makeReservation" />
+ ]]></eg>
+ </example>
+ <p> The binding and service endpoints require no change.</p>
+ <p> Finally, the service could also provide an interface for
+ ghns:makeReservation that only returns a fault.</p>
+ </div4>
+ </div3>
+
+
</div2>
+
Index: wsdl20-primer.html
===================================================================
RCS file: /sources/public/2002/ws/desc/wsdl20/wsdl20-primer.html,v
retrieving revision 1.76
retrieving revision 1.77
diff -C2 -d -r1.76 -r1.77
*** wsdl20-primer.html 22 Jun 2005 14:35:01 -0000 1.76
--- wsdl20-primer.html 23 Jun 2005 17:34:57 -0000 1.77
***************
*** 1,4 ****
! <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
! <html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Web Services Description Language (WSDL) Version 2.0 Part 0: Primer</title><style type="text/css">
code { font-family: monospace; }
--- 1,15 ----
! <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
! "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
! <html lang="en" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
! <head>
! <meta name="generator" content=
[...8698 lines suppressed...]
! Mahan (Nokia), Bryan Thompson (Hicks & Associates), Ingo Melzer
! (DaimlerChrysler Research and Technology), Sandeep Kumar (Cisco
! Systems), Alan Davies (SeeBeyond), Jacek Kopecky (Systinet), Mike
! Ballantyne (Electronic Data Systems), Mike Davoren (W. W.
! Grainger), Dan Kulp (IONA Technologies), Mike McHugh (W. W.
! Grainger), Michael Mealling (Verisign), Waqar Sadiq (Electronic
! Data Systems), Yaron Goland (BEA Systems, Inc.), Ümit Yalçınalp
! (Oracle Corporation), Peter Madziak (Agfa-Gevaert N. V.), Jeffrey
! Schlimmer (Microsoft Corporation), Hao He (The Thomson
! Corporation), Erik Ackerman (Lexmark), Jerry Thrasher (Lexmark),
! Prasad Yendluri (webMethods, Inc.), William Vambenepe
! (Hewlett-Packard Company), David Booth (W3C), Sanjiva Weerawarana
! (IBM).</p>
! <p>The people who have contributed to <a href=
! "http://lists.w3.org/Archives/Public/www-ws-desc/">discussions on
! www-ws-desc@w3.org</a> are also gratefully acknowledged.</p>
! </div>
! </div>
! </body>
! </html>
Received on Thursday, 23 June 2005 17:35:07 UTC