Example related to proposal for issue 1008 - Fault Handling

Hi,

I've attached the example from myself and Charlton, as well as including it in the email below (as the formatting is not preserved).

Regards
Gary




Examples: 

CDL

<?xml version="1.0" encoding="UTF-8"?>

<package xmlns="http://www.w3.org/2004/12/ws-chor/cdl"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:tns="http://www.example.com/ConsumerRetailerChoreographysample"

targetNamespace="http://www.example.com/ConsumerRetailerChoreographysample"

name="ConsumerRetailerChoreography" version="1.0">

<informationType name="purchaseOrderType" type="tns:PurchaseOrder"/>

<informationType name="purchaseOrderAckType" type="tns:PurchaseOrderAck"/>

<!-- NOTE: Information type representing the payload of the fault. Can be

a general type, does not have to be specifically identified

as a fault type, so definition can be reused in other places. -->

<informationType name="faultDetailsType" type="tns:FaultDetails"/>

<roleType name="Consumer">

<behavior name="consumerForRetailer" interface="tns:ConsumerRetailerPT"/>

<behavior name="consumerForWarehouse" interface="tns:ConsumerWarehousePT"/>

</roleType>

<roleType name="Retailer">

<behavior name="retailerForConsumer" interface="tns:RetailerConsumerPT"/>

</roleType>

<relationshipType name="ConsumerRetailerRelationship">

<roleType typeRef="tns:Consumer" behavior="consumerForRetailer"/>

<roleType typeRef="tns:Retailer" behavior="retailerForConsumer"/>

</relationshipType>

<channelType name="ConsumerChannel">

<roleType typeRef="tns:Consumer"/> .... </channelType>

<channelType name="RetailerChannel">

<roleType typeRef="tns:Retailer" behavior="retailerForConsumer"/>

.... 

</channelType>

<choreography name="ConsumerRetailerChoreography" root="true">

<relationship type="tns:ConsumerRetailerRelationship"/>

<variableDefinitions>

<variable name="purchaseOrder" informationType="tns:purchaseOrderType"/>

<variable name="purchaseOrderAck" informationType="tns:purchaseOrderAckType"/>

<variable name="retailer-channel" channelType="tns:RetailerChannel"/>

<variable name="badPurchaseOrderAck" informationType="tns:FaultDetailsType"/>

</variableDefinitions>

<interaction name="createPO" channelVariable="tns:retailer-channel"

operation="handlePurchaseOrder" align="true" initiate="true">

<participate relationshipType="tns:ConsumerRetailerRelationship"

fromRoleTypeRef="tns:Consumer" toRoleTypeRef="tns:Retailer"/>

<exchange name="request" informationType="tns:purchaseOrderType" action="request">

<send variable="cdl:getVariable('tns:purchaseOrder','','')"/>

<receive variable="cdl:getVariable('tns:purchaseOrder','','')"

recordReference="record-the-channel-info"/>

</exchange>

<exchange name="response" informationType="tns:purchaseOrderAckType" action="respond">

<send variable="cdl:getVariable('tns:purchaseOrderAck','','')"/>

<receive variable="cdl:getVariable('tns:purchaseOrderAck','','')"/>

</exchange>

<!-- NOTE: Explicitly specifying the faultName enables WSDL1.1 operations, that

have multiple faults of the same information types, to have their

faults distinguished by name. Not currently possible in CDL spec. -->

<exchange name="badPurchaseOrderAckException" faultName="badPOAck"

informationType="tns:faultDetailsType" action="respond">

<!-- NOTE: Use of any qualified name within the causeException attribute

gives the freedom to differentiate exceptions even when the information

type associated with the exchanges may be the same. -->

<send variable="cdl:getVariable('tns:badPurchaseOrderAck','','')"

causeException="tns:badPOAckException"/>

<receive variable="cdl:getVariable('tns:badPurchaseOrderAck','','')"

causeException="tns:badPOAckException"/>

</exchange>

<record name="record-the-channel-info" when="after">

<source variable="cdl:getVariable('tns:purchaseOrder','',

'/PO/CustomerRef')"/>

<target variable="cdl:getVariable('tns:consumer-channel','','')"/>

</record>

</interaction>

</choreography>

</package>





WSDL1.1



<?xml version="1.0" encoding="UTF-8"?>

<definitions name="Purchasing"

targetNamespace="http://www.example.com/ConsumerRetailerChoreographysample"

xmlns:tns="http://www.example.com/ConsumerRetailerChoreographysample"

xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns="http://schemas.xmlsoap.org/wsdl/">

<types> .... </types>

<message name="PurchaseOrder">

<part name="body" element="tns:PurchaseOrderDetails"/>

</message>

<message name="PurchaseOrderAck">

<part name="body" element="tns:PurchaseOrderAckDetails"/>

</message>

<message name="FaultDetails">

<part name="body" element="xsd:string"/>

</message>

<portType name="RetailerConsumerPT">

<operation name="handlePurchaseOrder">

<input message="tns:PurchaseOrder"/>

<output message="tns:PurchaseOrderAck"/>

<!-- NOTE: A WSDL1.1 operation can have multiple

faults with the same message type. Current

CDL would not be able to distinguish between

then, as it only looks at the fault type. -->

<fault name="badPOAck" message="tns:FaultDetails"/>

<fault name="outOfStock" message="tns:FaultDetails"/>

</operation>

</portType>

</definitions>



WSDL 2.0

<?xml version="1.0" encoding="UTF-8"?>

<description targetNamespace="http://www.example.com/ConsumerRetailerChoreographysample"

xmlns:tns="http://www.example.com/ConsumerRetailerChoreographysample"

xmlns="http://www.w3.org/2005/05/wsdl"> 

<types>

<!-- Change from WSDL1.1 version is simply converting the messages into

complex types. -->


<complexType name="PurchaseOrder" >

....

</complexType>

<complexType name="PurchaseOrderAck" >

....

</complexType>

<complexType name="FaultDetails" >

....

</complexType>

</types>


<interface name="RetailerConsumerPT" >

<!-- NOTE: The only change from WSDL1.1 (in terms of the interface),

is that the fault declaration has been moved out of the operation.

The updated CDL still simply refers to the fault 'name' and 'type'.

Whereas in the current CDL, when dealing with WSDL1.1, the CDL

deals with a 'type' and in WSDL2 it deals with a 'name'. Therefore

when someone is upgrading a WSDL1.1 service to WSDL2, if they

don't take into account how it has been used in CDL and simply

do a syntax change (i.e. externalising the faults from the operation

as we have done below), then with the current version of CDL,

the Choreography would need to be updated to use the WSDL2

version of the same service. -->


<fault name="badPOAck" type="tns:FaultDetails" />

<fault name="outOfStock" type="tns:FaultDetails" />


<operation name="handlePurchaseOrder"

pattern="http://www.w3.org/2005/05/wsdl/in-out" style="http://www.w3.org/2005/05/wsdl/style/uri"
safe = "true">


<input element="tns:PurchaseOrder" >

<output messageLabel="Out" element="tns:PurchaseOrderAck" >

<outfault ref="tns:badPOAck" messageLabel="Out" />

<outfault ref="tns:outOfStock" messageLabel="Out" />

</operation>

</interface>

</description> 





SUMMARY:

When upgrading from a WSDL1.1 interface to WSDL2, an organization is likely to preserve the structure of the interface and do minimal changes. In the above case, all we did was to convert the WSDL1.1 messages into complex types, and externalise the fault declarations from the operations and replace them with a reference to the new fault declaration. However the fault name and type were preserved.

No change is required to the CDL definition to support this change.

As mentioned before, this approach allows WSDL1.1 faults to be distinguished, where there are multiple faults on an operation with the same type.

By using the fault name and type separately within our CDL proposal, it means that the type part can be used in other fault exchanges. Whereas in the current CDL, if two faults have common types (in WSDL2), then a separate CDL information type declaration is required for each one.

The other benefit of explicitly defining the faultName attribute is that it means WSDL1.1 and WSDL2 definitions can be generated from the CDL. In the current CDL spec, this would only be possible for WSDL2 - although even for WSDL2, the user would still need to edit the generated interface definition to define the 'element' attribute of the fault declaration.