RE: Many primer Versioning examples.

I think PaulD suggested that if I had more examples, they'd be welcome.
I gave him some feedback with some of these suggestions (optional
extensions, mandatory extensions, optional operations, mandatory
operations) and he suggested that I could probably write them up :-)

 

Cheers,

Dave

 

  _____  

From: Liu, Kevin [mailto:kevin.liu@sap.com] 
Sent: Tuesday, June 14, 2005 3:52 PM
To: David Orchard; WS-Description WG
Subject: RE: Many primer Versioning examples.

 

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

--------------------------------------------------------------------------------

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