- From: Liu, Kevin <kevin.liu@sap.com>
- Date: Wed, 15 Jun 2005 00:52:18 +0200
- To: "David Orchard" <dorchard@bea.com>, "WS-Description WG" <www-ws-desc@w3.org>
- Message-ID: <3470F33FF8ED12498D07F3A9651AA18E2078EF@uspale20.pal.sap.corp>
Hi David,
Thanks a lot for the contribution.
Just wonder if this contribution is based on an AI? I have no problem to
add these examples to the Advanced Topic section as long as the group
are OK.
Best Regards,
Kevin
_____
From: www-ws-desc-request@w3.org [mailto:www-ws-desc-request@w3.org] On
Behalf Of David Orchard
Sent: Tuesday, Jun 14, 2005 2:27 PM
To: WS-Description WG
Subject: Many primer Versioning examples.
I offer a number of examples for new sections in Primer section 7.5.
7.5.5. Additional optional elements added in content
This section shows how content is 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.
<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 targetNamespace="##other" processContents="lax"/>
</xs:sequence>
</xs:complexType>
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 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.
7.5.6. Additional optional elements added in header
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. For SOAP, an example is:
<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>
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.
7.5.7 Additional Mandatory elements in content
This section shows how content is extended 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.
<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 targetNamespace="##other" processContents="lax"/>
</xs:sequence>
</xs:complexType>
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.
7.5.8. Additional optional operation added to interface
Section 5.2 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.
7.5.9 Additional mandatory operation added to interface
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.
By the definition of interface inheritance, they cannot use interface
inheritance for defining the extension.
<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>
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.
7.5.9.1 Indicating incompatibility by changing the endpoint URI.
To indicate incompatibility, the URI of the Hotel Endpoint can be
changed and messages send to the old Endpoint return a Fault.
7.5.9.2 Indicating incompatibility by changing the SOAP Action
The SOAP Action can be set for the makeReservation request, and making
it different than the earlier version should indicate incompatibility.
<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"/>
. . .
</interface>
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.
7.5.9.3 Indicating incompatibility by changing the element content
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:
<xs:element name="ghns2:makeReservation" type="ghns:tmakeReservation"/>
<interface . . .>
. . .
<input messageLabel="In" element="ghns2:makeReservation" />
The binding and service endpoints require no change.
Finally, the service could also provide an interface for
ghns:makeReservation that only returns a fault.
------------------------------------------------------------------------
--------
Join CEO Alfred Chuang and CTO Mark Carges on June 15 for a unique
online
event, giving you the first look at a new category of enterprise
software
built specifically for Service-Oriented Architecture (SOA).
Register Now. It's Free!
http://www.bea.com/events/june15
Received on Tuesday, 14 June 2005 22:52:37 UTC