www.openlinksw.com
docs.openlinksw.com

Book Home

Contents
Preface

Web Services

SOAP
WSDL
WS-Security (WSS) Support in Virtuoso SOAP Server
Web Services Routing Protocol (WS-Routing)
Web Services Reliable Messaging Protocol (WS-ReliableMessaging)
SOAP CLIENT API Extensions WS-RM Sender API WSRM Receiver API WS-RM Protocol Endpoint Configuration Message Examples WS-RM Schema
Web Services Trust Protocol (WS-Trust)
XML for Analysis Provider
XML-RPC support
SyncML
UDDI
Exposing Persistent Stored Modules as Web Services
Testing Web Published Web Services
BPEL Reference
XSQL

15.5. Web Services Reliable Messaging Protocol (WS-ReliableMessaging)

The WS-ReliableMessaging protocol is a SOAP-based RPC protocol for guaranteed delivery of messages; possibly in specific order from one sender to one receiver. Such messages are usual SOAP messages - XML documents conforming to the SOAP specification. The Sender is an alias of the transmission initiator, i.e. the originator of the message transfer. The Receiver is a recipient, that which accepts the messages. How accepted messages should be processed is not covered in this document.; What to do with the data and whether to send replies is at the discretion of the application.

See Also:

WS Reliable Messaging

WS Reliable Messaging Exec Summary

Further in this section for brevity WS-RM will be used in place of "Web Services Reliable Messaging Protocol".

Delivery Assurances Types:

See Also:

WS-RM System Table Definitions in the Appendix section

15.5.1. SOAP CLIENT API Extensions

The SOAP Client API is used for handling, building and accessing complex types required to perform a SOAP request. It allows you to build a structures to access their elements and to build values suitable for passing to the SOAP_CLIENT() function. It also allows to de-serialize a SOAP response to a soap_parameter and access its members and attributes safely.

Vectors are used to pass or retrieve a complex type using SOAP These vectors contain special content or UDTs. In SOAP, structures are allowed to have multiple members of the same name, or conditional members (choices). Thus it is not possible to cover all variants of XSD types with UDTs (which would be the most elegant way to represent structures). So to cover all variants of structure handling or to express structures containing attributes, we have to use vectors. Since we used a special structure with vectors for expressing such complex types we introduce the following API to deal with them.

The base of API is a UDT 'soap_parameter':

create type soap_parameter as
		(
		  s any default null,
		  param_type int default 1,
		  param_xsd varchar default null,
		  ver int default 11
		)
		temporary self as ref
;

Its members are:

Its Constructors are:

constructor method soap_complex_parameter ()
Instantiate an empty structure placeholder;
constructor method soap_simple_parameter (val any),
Instantiate an empty simple type placeholder
constructor method soap_array_parameter (n int),
Instantiate an array placeholder
constructor method soap_single_parameter (elm soap_parameter),
Instantiate an element of containing a type of 'elm'

Its Methods are:

method get_length () returns any,
Returns the  length of the parameter
method add_member (name varchar, val any) returns any,
Add a new member element to the structure placeholder
method set_member (name varchar, val any) returns any
Sets the value of an existing member by name or will add a new member  if  the member does not exist
method set_member (pos int, val any) returns any,
the same as above but using ordinal position of the member;
method get_member (name varchar) returns any,
Returns a member's value by name
method get_member (pos int) returns any,
Returns member value by ordinal position
method get_value () returns any,
Returns value for simple types. Only for simple type is applicable
method set_value (val any) returns any,
Sets the value of a simple type
method set_attribute (name varchar, val any) returns any,
Set an attribute value of a structure or simple type
method get_attribute (name varchar) returns any,
Return an attribute value of a structure or simple type
method get_call_param (name varchar) returns any,

Serializes the parameter in a form suitable for passing to the SOAP_CLIENT() function. When several parameters needs to be passed to it, then result of those calls must be concatenated (see vector_concat()) Importanat: set_xsd have to be called with valid ExQName, before doing get_call_param call.

method set_xsd (xsd varchar) returns any,

Establish a SOAP data-type Expanded QName, referencing the data kept in the soap_parameter. This is a reference to a SOAP complex data-type already defined with soap_dt_define () function (see function reference). This method only sets the relation between data kept in soap_parameter and doesn't check its validity unless serialize is performed. The data-type Expanded QName also will be included into output of the get_call_param method.

Complex WS Type Example

Consider the following complex type:

<xsd:complexType
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    name="SOAPComplexType"
    targetNamespace="http://soapinterop.org/xsd">
 <xsd:sequence>
	<xsd:element minOccurs="1" maxOccurs="1" name="varInt" type="xsd:int" />
	<xsd:element minOccurs="0" maxOccurs="1" name="varString" type="xsd:string" />
	<xsd:element minOccurs="1" maxOccurs="1" name="varFloat" type="xsd:float" />
 </xsd:sequence>
</xsd:complexType>

declare s soap_parameter ;
s := new soap_parameter ();
s.set_xsd ('http://soapinterop.org/xsd:SOAPComplexType');
s.add_member ('varString', 'string');
s.serialize ('mystruct'); -- will generate an error as, varInt and varFloat are
			              -- missing but they are declared as minOccurs="1"

So if we add two more members, and remove varString, to the statements above.

s.add_member ('varInt', 123);
s.add_member ('varFloat', 3.14);
s.serialize ('mystruct');

Will produce valid output:

<mystruct><varInt>123</varInt><varFloat>3.14</varFloat></mystruct>

and finally we can make a parameter for the SOAP_CLIENT() function:

par := s.get_call_param ('par1');

here are the contents of 'par':

(
  ("par1", "http://soapinterop.org/xsd:SOAPComplexType" ), -- designates paramter par1, with type SOAPComplexType
  (<COMPOSITE>, "",	-- this is a marker that it's a struct
	"varInt", 123, 	-- the members name/value pairs follows
	"varFloat", 3.14
  )
)

Further methods are:

method deserialize (xs any, elem varchar) returns any,

Deserializes a element 'elem' from 'xs' (XML tree object) the the soap_parameter.

method serialize (tag varchar) returns any,

Returns an XML document representing the data kept into the soap_parameter.

method set_struct (s any) returns any

Explicitly sets the structure/array/simple type kept in the soap_parameter UDT. This can be used to disassemble a nested complex type into its components.

Example Using WS-RM

echoStruct invocation

declare ret any;
declare pa soap_parameter;

pa := new soap_parameter ();
pa.add_member ('varString', 'My String');
pa.add_member ('varInt', 12345);
pa.add_member ('varFloat', 3.1415926);
pa.set_xsd ('http://soapinterop.org/xsd:SOAPStruct');

ret := SOAP_CLIENT (url=>'http://.../interop',
  operation=>'echoStruct', parameters=>pa.get_call_param ('inputStruct'));

pa := new soap_parameter ();
pa.set_xsd ('http://soapinterop.org/xsd:SOAPStruct');
pa.deserialize (ret, 'CallReturn');
return pa.get_member ('varString');

echoDocument invocation

declare ret any;
declare doc, pa soap_parameter;

doc := new soap_parameter ('The document content');
doc.set_attribute ('ID', uuid());
doc.set_xsd ('http://soapinterop.org/xsd:x_Document');


ret := SOAP_CLIENT (url=>'http://.../r3/Compound1', operation=>'echoDocument',
  parameters=>doc.get_call_param ('x'), style=>1);


pa := new soap_parameter ();
pa.set_xsd ('http://soapinterop.org/xsd:Document');
pa.deserialize (ret, 'result_Document');
dbg_obj_print (pa.s);

return pa.get_attribute ('ID');
See Also:

SOAP_CLIENT()


15.5.2. WS-RM Sender API

The WS-RM API allows for:

The User Defined Types defined in support of WS-RM are as follows:

Sender's responder (endpoint)

To receive an asynchronous Acknowledgment the sender must have an endpoint to handle them. The WSRMSequenceAcknowledgment() procedure must be exposed at that endpoint. This accepts and processes asynchronous Acknowledgment. This is used to accept a SequenceAcknowledgment response from a remote party so it will process the response and will set the state of messages that are acknowledged.


15.5.3. WSRM Receiver API

On the receiver side we have PL wrappers that take as arguments all *known* WS-RM headers. This procedure, when granted to a SOAP endpoint will process the incoming requests. It will also answer send the appropriate answers to the sender.

The following is the list of WS-RM receiver wrappers:

  1. WSRMSequence

    accept and store a Sequence requests. This is used to accept Sequence requests from sender and will perform the following actions:

    • store the message in incoming message log table
    • process and apply the Policy attachment (if supplied); otherwise apply default rule: AtMostOnce
    • depending of a addressing headers will reply in synchronous or asynchronous manner. This depends on the value of "From" and "ReplyTo" headers. If these contains non-anonymous URL (see above); an asynchronous Acknowledgment will be sent in a separate TCP connection. Thus in this mode the sender must have defined a listener with WSRMSequenceAcknowledgment exposed to accept such responses. Otherwise synchronous Acknowledgment will be sent in the same TCP connection.
    • If an error occurred a Fault will be generated
  2. WSRMSequenceTerminate

    accept and process SequenceTerminate requests. This is used to accept cancel request; to kill an existing message sequence. Further actions on such sequence will be rejected.

  3. WSRMAckRequested

    accept and process AckRequested requests. This is used to process AckRequested WS-RM messages and will produce a SequenceAcknowledgment containing info about messages been accepted. Used from sender's side to check the message sequence state.

These PL procedures are built-in to the server, and have to be granted to the user that is assigned as the SOAP execution account for a given virtual directory designated as a WS-RM receiver endpoint.


15.5.4. WS-RM Protocol Endpoint Configuration

The setup is a virtual directory definition and grant of rights to the procedures for sender and receiver endpoints.

This will be demonstrated as an example of setting up both endpoints:

WS-RM Ping Test Example

This is an example client used to perform the interoperability test "Ping" as proposed in "Interop Workshop Scenarios"

soap_dt_define ('',
		'<element
			xmlns="http://www.w3.org/2001/XMLSchema"
			name="Ping" type="test:Ping_t"
			targetNamespace = "http://tempuri.org/" xmlns:test="http://tempuri.org/" />');
soap_dt_define ('',
		'<complexType xmlns="http://www.w3.org/2001/XMLSchema"
		 	      name="Ping_t" targetNamespace = "http://tempuri.org/">
				<sequence>
					<element minOccurs="1" maxOccurs="1" name="Text" type="string"/>
				</sequence>
		</complexType>');
create procedure WSRMTestPing (in _to varchar, in _from varchar)
  {
    declare addr wsa_cli;
    declare test wsrm_cli;
    declare req soap_client_req;
    declare finish any;
    declare ping soap_parameter;

    ping := new soap_parameter (1);

    ping.set_xsd ('http://tempuri.org/:Ping');
    ping.s := vector ('Hello World');

    addr := new wsa_cli ();
    addr."to" := _to;
    addr."from" := _from;
    addr.action := 'urn:wsrm:Ping';

    req := new soap_client_req ();
    req.url := _to;
    req.operation := 'Ping';
    req.parameters := ping.get_call_param ('');

    test := new wsrm_cli (addr, _to);

    test.send_message (req);
    test.send_message (req);
    test.finish (req);
    return test.seq;
  }
;

15.5.5. Message Examples

Example: Initial request
<SOAP:Envelope>
  <SOAP:Header>
    <wsa:MessageID>uuid:aa8bd508-110b-11d8-8344-8cfad4a25a87</wsa:MessageID>
    <wsa:To>http://host:9999/wsrm</wsa:To>
    <wsa:From>
      <wsa:Address>http://host:9999/replyto</wsa:Address>
    </wsa:From>
    <wsa:Action><!-- depending of application --></wsa:Action>
    <wsrm:Sequence>
      <wsu:Identifier>uuid:aa8bfa74-110b-11d8-8344-8cfad4a25a87</wsu:Identifier>
      <wsrm:MessageNumber>1</wsrm:MessageNumber>
    </wsrm:Sequence>
  </SOAP:Header>
  <SOAP:Body>
    <!-- some application data -->
  </SOAP:Body>
</SOAP:Envelope>

receiver accepts and return just

HTTP/1.1 202 Accepted
Content-Length: 0

Last message

<SOAP:Envelope>
  <SOAP:Header>
    <wsa:MessageID>uuid:aa8bd508-110b-11d8-8344-8cfad4a25a87</wsa:MessageID>
    <wsa:To>http://host:9999/wsrm</wsa:To>
    <wsa:From>
      <wsa:Address>http://host:9999/replyto</wsa:Address>
    </wsa:From>
    <wsa:Action><!-- depending of application --></wsa:Action>
    <wsrm:Sequence>
      <wsu:Identifier>uuid:aa8bfa74-110b-11d8-8344-8cfad4a25a87</wsu:Identifier>
      <wsrm:MessageNumber>2</wsrm:MessageNumber>
      <wsrm:LastMessage/>
    </wsrm:Sequence>
  </SOAP:Header>
  <SOAP:Body>
    <!-- some application data -->
  </SOAP:Body>
</SOAP:Envelope>

receiver accepts and returns

HTTP/1.1 202 Accepted
Content-Length: 0

Sequence Acknowledgment response; sent via another channel

<SOAP:Envelope>
  <SOAP:Header>
    <wsa:MessageID>uuid:aadedf64-110b-11d8-8344-8cfad4a25a87</wsa:MessageID>
    <wsa:To>http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous</wsa:To>
    <wsa:From>
      <wsa:Address>http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous</wsa:Address>
    </wsa:From>
    <wsa:Action>http://schemas.xmlsoap.org/ws/2004/08/rm#SequenceAcknowledgment</wsa:Action>
    <wsrm:SequenceAcknowledgment>
      <wsu:Identifier>uuid:aa8bfa74-110b-11d8-8344-8cfad4a25a87</wsu:Identifier>
      <wsrm:AcknowledgmentRange Upper="2" Lower="1"/>
    </wsrm:SequenceAcknowledgment>
  </SOAP:Header>
  <SOAP:Body/>
</SOAP:Envelope>

initial sender accepts and returns

HTTP/1.1 202 Accepted
Content-Length: 0

15.5.6. WS-RM Schema

<xsd:schema
    targetNamespace="http://schemas.xmlsoap.org/ws/2003/03/rm"
	xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility"
	xmlns:wsrm="http://schemas.xmlsoap.org/ws/2003/03/rm"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	elementFormDefault="qualified" attributeFormDefault="unqualified">

	<!-- *** BASE *** -->
    <xsd:complexType name="SequenceType">
	<xsd:sequence>
	    <xsd:element ref="wsu:Identifier"/>
	    <xsd:element name="MessageNumber" type="xsd:unsignedLong"/>
	    <xsd:element name="LastMessage" type="xsd:ENTITY" minOccurs="0"/>
	</xsd:sequence>
    </xsd:complexType>


    <xsd:complexType name="SequenceTerminate_t">
	<xsd:sequence>
	    <xsd:element ref="wsu:Identifier"/>
	</xsd:sequence>
    </xsd:complexType>


    <xsd:complexType name="AcknowledgmentRange_t">
	<xsd:sequence/>
	<xsd:attribute name="Upper" type="xsd:unsignedLong" use="required"/>
	<xsd:attribute name="Lower" type="xsd:unsignedLong" use="required"/>
    </xsd:complexType>

    <xsd:complexType name="SequenceAcknowledgment_t">
	<xsd:sequence>
	    <xsd:element ref="wsu:Identifier"/>
	    <xsd:element name="AcknowledgmentRange" type="wsrm:AcknowledgmentRange_t" maxOccurs="unbounded">
	    </xsd:element>
	</xsd:sequence>
    </xsd:complexType>


    <xsd:complexType name="AckRequestedType">
	<xsd:sequence>
	    <xsd:element ref="wsu:Identifier"/>
	</xsd:sequence>
    </xsd:complexType>

    <xsd:element name="Sequence" type="wsrm:SequenceType"/>
    <xsd:element name="SequenceTerminate" type="wsrm:SequenceTerminate_t"/>
    <xsd:element name="SequenceAcknowledgment" type="wsrm:SequenceAcknowledgment_t" />
    <xsd:element name="AckRequested" type="wsrm:AckRequestedType"/>

    <!-- *** FAULTS *** -->

    <xsd:simpleType name="FaultCodes">
	<xsd:restriction base="xsd:QName">
	    <xsd:enumeration value="wsrm:UnknownSequence"/>
	    <xsd:enumeration value="wsrm:SequenceTerminated"/>
	    <xsd:enumeration value="wsrm:InvalidAcknowledgment"/>
	    <xsd:enumeration value="wsrm:MessageNumberRollover"/>
	</xsd:restriction>
    </xsd:simpleType>

    <xsd:complexType name="SequenceFaultType">
	<xsd:sequence>
	    <xsd:element ref="wsu:Identifier"/>
	    <xsd:element name="FaultCode" type="wsrm:FaultCodes"/>
	</xsd:sequence>
    </xsd:complexType>

    <xsd:element name="SequenceFault" type="wsrm:SequenceFaultType"/>

    <!-- *** ASSERTATIONS *** -->
    <xsd:complexType name="InactivityTimeout_t">
	<xsd:sequence/>
	<xsd:attribute name="Milliseconds" type="xsd:unsignedLong" use="required"/>
    </xsd:complexType>

    <xsd:complexType name="BaseRetransmissionInterval_t">
	<xsd:sequence/>
	<xsd:attribute name="Milliseconds" type="xsd:unsignedLong" use="required"/>
    </xsd:complexType>

    <xsd:complexType name="AcknowledgmentInterval_t">
	<xsd:sequence/>
	<xsd:attribute name="Milliseconds" type="xsd:unsignedLong" use="required"/>
    </xsd:complexType>

    <xsd:complexType name="PolicyAssertionType">
	<xsd:sequence>
	    <xsd:any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
	</xsd:sequence>
	<xsd:anyAttribute namespace="##other"/>
    </xsd:complexType>

    <xsd:simpleType name="DeliveryAssuranceEnum">
	<xsd:restriction base="xsd:QName">
	    <xsd:enumeration value="wsrm:AtMostOnce"/>
	    <xsd:enumeration value="wsrm:AtLeastOnce"/>
	    <xsd:enumeration value="wsrm:ExactlyOnce"/>
	    <xsd:enumeration value="wsrm:InOrder"/>
	</xsd:restriction>
    </xsd:simpleType>

    <xsd:complexType name="DeliveryAssurance_t">
	<xsd:sequence/>
	<xsd:attribute name="Value" type="xsd:QName" use="required"/>
    </xsd:complexType>

    <xsd:element name="InactivityTimeout" type="wsrm:InactivityTimeout_t" />
    <xsd:element name="BaseRetransmissionInterval" type="wsrm:BaseRetransmissionInterval_t" />
    <xsd:element name="ExponentialBackoff" type="wsrm:PolicyAssertionType"/>
    <xsd:element name="AcknowledgmentInterval" type="wsrm:AcknowledgmentInterval_t"/>
    <xsd:element name="DeliveryAssurance" type="wsrm:DeliveryAssurance_t"/>

    <!-- *** Sequence Reference *** -->
    <xsd:complexType name="SequenceRefType">
	<xsd:sequence />
	<xsd:attribute name="Identifier" type="xsd:anyURI" use="required"/>
	<xsd:attribute name="Match" type="wsrm:MatchChoiceType" use="optional"/>
    </xsd:complexType>

    <xsd:simpleType name="MatchChoiceType">
	<xsd:restriction base="xsd:QName">
	    <xsd:enumeration value="wsrm:Exact"/>
	    <xsd:enumeration value="wsrm:Prefix"/>
	</xsd:restriction>
    </xsd:simpleType>
    <xsd:element name="SequenceRef" type="wsrm:SequenceRefType"/>

</xsd:schema>