<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head profile="http://internetalchemy.org/2003/02/profile">
<link rel="foaf" type="application/rdf+xml" title="FOAF" href="http://www.openlinksw.com/dataspace/uda/about.rdf" />
<link rel="schema.dc" href="http://purl.org/dc/elements/1.1/" />
<meta name="dc.title" content="15. Web Services" />
<meta name="dc.subject" content="15. Web Services" />
<meta name="dc.creator" content="OpenLink Software Documentation Team ; " />
<meta name="dc.copyright" content="OpenLink Software, 1999 - 2009" />
<link rel="top" href="index.html" title="OpenLink Virtuoso Universal Server: Documentation" />
<link rel="search" href="/doc/adv_search.vspx" title="Search OpenLink Virtuoso Universal Server: Documentation" />
<link rel="parent" href="webservices.html" title="Chapter Contents" />
<link rel="prev" href="ws-routing.html" title="Web Services Routing Protocol (WS-Routing)" />
<link rel="next" href="vwstrust.html" title="Web Services Trust Protocol (WS-Trust)" />
<link rel="shortcut icon" href="../images/misc/favicon.ico" type="image/x-icon" />
<link rel="stylesheet" type="text/css" href="doc.css" />
<link rel="stylesheet" type="text/css" href="/doc/translation.css" />
<title>15. Web Services</title>
<meta http-equiv="Content-Type" content="text/xhtml; charset=UTF-8" />
<meta name="author" content="OpenLink Software Documentation Team ; " />
<meta name="copyright" content="OpenLink Software, 1999 - 2009" />
<meta name="keywords" content="" />
<meta name="GENERATOR" content="OpenLink XSLT Team" />
</head>
<body>
<div id="header">
<a name="warm" />
<img src="../images/misc/logo.jpg" alt="" />
<h1>15. Web Services</h1>
</div>
<div id="navbartop">
<div>
<a class="link" href="webservices.html">Chapter Contents</a> | <a class="link" href="ws-routing.html" title="Web Services Routing Protocol (WS-Routing)">Prev</a> | <a class="link" href="vwstrust.html" title="Web Services Trust Protocol (WS-Trust)">Next</a>
</div>
</div>
<div id="currenttoc">
<form method="post" action="/doc/adv_search.vspx">
<div class="search">Keyword Search: <br />
<input type="text" name="q" /> <input type="submit" name="go" value="Go" />
</div>
</form>
<div>
<a href="http://www.openlinksw.com/">www.openlinksw.com</a>
</div>
<div>
<a href="http://docs.openlinksw.com/">docs.openlinksw.com</a>
</div>
<br />
<div>
<a href="index.html">Book Home</a>
</div>
<br />
<div>
<a href="contents.html">Contents</a>
</div>
<div>
<a href="preface.html">Preface</a>
</div>
<br />
<div class="selected">
<a href="webservices.html">Web Services</a>
</div>
<br />
<div>
<a href="soap.html">SOAP</a>
</div>
<div>
<a href="wsdl.html">WSDL</a>
</div>
<div>
<a href="vfoafssl.html">WebID Protocol Support</a>
</div>
<div>
<a href="voauth.html">OAuth Support</a>
</div>
<div>
<a href="vwsssupport.html">WS-Security (WSS) Support in Virtuoso SOAP Server</a>
</div>
<div>
<a href="ws-routing.html">Web Services Routing Protocol (WS-Routing)</a>
</div>
<div class="selected">
<a href="warm.html">Web Services Reliable Messaging Protocol (WS-ReliableMessaging)</a>
<div>
<a href="#wsrmsoapcliapi" title="SOAP CLIENT API Extensions">SOAP CLIENT API Extensions</a>
<a href="#wsrmsndrapi" title="WS-RM Sender API">WS-RM Sender API</a>
<a href="#wsrmrcvrapi" title="WSRM Receiver API">WSRM Receiver API</a>
<a href="#wsrmsetupendpoint" title="WS-RM Protocol Endpoint Configuration">WS-RM Protocol Endpoint Configuration</a>
<a href="#wsrmmsgexamples" title="Message Examples">Message Examples</a>
<a href="#wsrmschema" title="WS-RM Schema">WS-RM Schema</a>
</div>
</div>
<div>
<a href="vwstrust.html">Web Services Trust Protocol (WS-Trust)</a>
</div>
<div>
<a href="xmlxmla.html">XML for Analysis Provider</a>
</div>
<div>
<a href="xmlrpc.html">XML-RPC support</a>
</div>
<div>
<a href="syncml.html">SyncML</a>
</div>
<div>
<a href="uddi.html">UDDI</a>
</div>
<div>
<a href="expwsmodules.html">Exposing Persistent Stored Modules as Web Services</a>
</div>
<div>
<a href="vsmx.html">Testing Web Published Web Services</a>
</div>
<div>
<a href="bpel.html">BPEL Reference</a>
</div>
<div>
<a href="xsql.html">XSQL</a>
</div>
<br />
</div>
<div id="text">
<a name="warm" />
<h2>15.7. Web Services Reliable Messaging Protocol (WS-ReliableMessaging)</h2>
<p>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.</p>
<div class="tip">
<div class="tiptitle">See Also:</div>
<p>
<a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnglobspec/html/ws-reliablemessaging.asp">WS Reliable Messaging</a>
</p>
<p>
<a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnglobspec/html/WS-RM-exec-summary.asp">WS Reliable Messaging Exec Summary</a>
</p>
</div>
<p>Further in this section for brevity WS-RM will be used
in place of "Web Services Reliable Messaging Protocol".</p>
<p>
<strong>Delivery Assurances Types:</strong>
</p>
<ul>
<li>
<strong>AtMostOnce</strong> - Delivery at most once without
duplication or an error will be raised on at least one endpoint. It is possible
that some messages in a sequence may not be delivered.</li>
<li>
<strong>AtLeastOnce</strong> - Every message sent will be
delivered or an error will be raised on at least one endpoint. Some messages
may be delivered more than once.</li>
<li>
<strong>ExactlyOnce</strong> - Every message sent will be delivered
without duplication or an error will be raised on at least one endpoint. This
delivery assurance is the logical "and" of the two prior delivery assurances.</li>
<li>
<strong>InOrder</strong> - Messages will be delivered in the order
that they were sent. This delivery assurance may be combined with any of the
above delivery assurances. It requires that the sequence observed by the
ultimate receiver be non-decreasing. It says nothing about duplications or
omissions.</li>
</ul>
<div class="tip">
<div class="tiptitle">See Also:</div>
<p>
<a href="systemtables.html#systabswsrm">WS-RM System Table Definitions</a>
in the Appendix section</p>
</div>
<a name="wsrmsoapcliapi" />
<h3>15.7.1. SOAP CLIENT API Extensions</h3>
<p>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
<a href="fn_soap_client.html">SOAP_CLIENT()</a> function.
It also allows to de-serialize a SOAP response to a
<span class="computeroutput">soap_parameter</span>
and access its members and attributes safely.</p>
<p>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.</p>
<p>The base of API is a UDT 'soap_parameter':</p>
<div>
<pre class="programlisting">
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
;
</pre>
</div>
<p>Its members are:</p>
<ul>
<li>
<strong>'s'</strong> - a vector representing a structure,
array or simple type.</li>
<li>
<strong>'param_type'</strong> - designates what is kept in
's' : 1 is struct ; 0 - simple type; 2 - array</li>
<li>
<strong>'param_xsd'</strong> - URL; QName of the type stored in 's'</li>
<li>
<strong>'ver'</strong> - soap version to be used for
serialization/deserialization if RPC style is used.</li>
</ul>
<p>Its Constructors are:</p>
<div>
<pre class="programlisting">
constructor method soap_complex_parameter ()
Instantiate an empty structure placeholder;
</pre>
</div>
<div>
<pre class="programlisting">
constructor method soap_simple_parameter (val any),
Instantiate an empty simple type placeholder
</pre>
</div>
<div>
<pre class="programlisting">
constructor method soap_array_parameter (n int),
Instantiate an array placeholder
</pre>
</div>
<div>
<pre class="programlisting">
constructor method soap_single_parameter (elm soap_parameter),
Instantiate an element of containing a type of 'elm'
</pre>
</div>
<p>Its Methods are:</p>
<div>
<pre class="programlisting">
method get_length () returns any,
Returns the length of the parameter
</pre>
</div>
<div>
<pre class="programlisting">
method add_member (name varchar, val any) returns any,
Add a new member element to the structure placeholder
</pre>
</div>
<div>
<pre class="programlisting">
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
</pre>
</div>
<div>
<pre class="programlisting">
method set_member (pos int, val any) returns any,
the same as above but using ordinal position of the member;
</pre>
</div>
<div>
<pre class="programlisting">
method get_member (name varchar) returns any,
Returns a member's value by name
</pre>
</div>
<div>
<pre class="programlisting">
method get_member (pos int) returns any,
Returns member value by ordinal position
</pre>
</div>
<div>
<pre class="programlisting">
method get_value () returns any,
Returns value for simple types. Only for simple type is applicable
</pre>
</div>
<div>
<pre class="programlisting">
method set_value (val any) returns any,
Sets the value of a simple type
</pre>
</div>
<div>
<pre class="programlisting">
method set_attribute (name varchar, val any) returns any,
Set an attribute value of a structure or simple type
</pre>
</div>
<div>
<pre class="programlisting">
method get_attribute (name varchar) returns any,
Return an attribute value of a structure or simple type
</pre>
</div>
<div>
<pre class="programlisting">
method get_call_param (name varchar) returns any,
</pre>
</div>
<p>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())
Important: set_xsd have to be called with valid ExQName, before doing
get_call_param call.
</p>
<div>
<pre class="programlisting">
method set_xsd (xsd varchar) returns any,
</pre>
</div>
<p>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.
</p>
<a name="ex_wsrmtypes" />
<div class="example">
<div class="exampletitle">Complex WS Type Example</div>
<p>Consider the following complex type:</p>
<div>
<pre class="programlisting">
<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"
</pre>
</div>
<p>So if we add two more members, and remove varString, to the statements above.</p>
<div>
<pre class="programlisting">
s.add_member ('varInt', 123);
s.add_member ('varFloat', 3.14);
s.serialize ('mystruct');
</pre>
</div>
<p>Will produce valid output:</p>
<div>
<pre class="programlisting">
<mystruct><varInt>123</varInt><varFloat>3.14</varFloat></mystruct>
</pre>
</div>
<p>and finally we can make a parameter for the SOAP_CLIENT() function:</p>
<div>
<pre class="programlisting">
par := s.get_call_param ('par1');
</pre>
</div>
<p>here are the contents of 'par':</p>
<div>
<pre class="programlisting">
(
("par1", "http://soapinterop.org/xsd:SOAPComplexType" ), -- designates parameter 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
)
)
</pre>
</div>
</div>
<p>Further methods are:</p>
<div>
<pre class="programlisting">
method deserialize (xs any, elem varchar) returns any,
</pre>
</div>
<p>Deserializes a element 'elem' from 'xs' (XML tree object)
the the soap_parameter.</p>
<div>
<pre class="programlisting">
method serialize (tag varchar) returns any,
</pre>
</div>
<p>Returns an XML document representing the data kept into
the soap_parameter.</p>
<div>
<pre class="programlisting">
method set_struct (s any) returns any
</pre>
</div>
<p>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.</p>
<a name="ex_wsrmuseparam" />
<div class="example">
<div class="exampletitle">Example Using WS-RM</div>
<p>echoStruct invocation</p>
<div>
<pre class="programlisting">
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');
</pre>
</div>
<p>echoDocument invocation</p>
<div>
<pre class="programlisting">
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');
</pre>
</div>
</div>
<div class="tip">
<div class="tiptitle">See Also:</div>
<p>
<a href="fn_soap_client.html">SOAP_CLIENT()</a>
</p>
</div>
<br />
<a name="wsrmsndrapi" />
<h3>15.7.2. WS-RM Sender API</h3>
<p>The WS-RM API allows for:</p>
<ul>
<li>register/start a conversation</li>
<li>set parameters on both sides (receiver or sender)</li>
<li>check the acknowledgment</li>
<li>retry if needed</li>
<li>to finish or cancel the conversation (can be with cancel) </li>
<li>check for faults</li>
</ul>
<p>The User Defined Types defined in support of WS-RM are as follows:</p>
<ul>
<li>
<p>
<strong>soap_client () parameters wrapper</strong>
</p>
<div>
<pre class="programlisting">
create type soap_client_req as
(
url varchar,
operation varchar,
target_namespace varchar default null,
parameters any default null,
headers any default null,
soap_action varchar default '',
attachments any default null,
ticket any default null,
passwd varchar default null,
user_name varchar default null,
user_password varchar default null,
auth_type varchar default 'none',
security_type varchar default 'sign',
debug integer default 0,
template varchar default null,
style integer default 0,
version integer default 11,
direction integer default 0
)
;
</pre>
</div>
<p>This UDT is used for passing various parameters to the
WS-RM client to send a SOAP messages along with WS-RM specific headers.
The members are with same names as for SOAP_CLIENT () function.
In other words applications must fill a soap_client_req specific
data and pass this to the wsrm_cli methods (see below).</p>
</li>
<li>
<p>
<strong>client addressing UDT:</strong>
</p>
<p>To facilitate two-way transport the receiver must know the
address of the sender's responder (endpoint for asynchronous Acknowledgment or
response). To pass such addresses to the WS-RM client (wsrm_cli)
the following UDT is used.</p>
<div>
<pre class="programlisting">
create type wsa_cli as
(
mid varchar default null,
"to" varchar default null,
"from" varchar default null,
action varchar default null,
fault_to varchar default null,
reply_to varchar default null
)
</pre>
</div>
<p>Whose members are as follows:</p>
<ul>
<li>
<strong>mid</strong> - message identifier; unique across space and time</li>
<li>
<strong>to</strong> - where message traveling to</li>
<li>
<strong>from</strong> - from where it's sent</li>
<li>
<strong>action</strong> - WS-Addressing Action headed element</li>
<li>
<strong>fault_to</strong> - where to return the fault</li>
<li>
<strong>reply_to</strong> - where to reply; if no such URL given the "to" will be used to reply. </li>
</ul>
<div class="note">
<div class="notetitle">Important Note:</div>
<p>A special "to" equal to
'<span class="computeroutput">http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous</span>'
is used to designate an 'anonymous' sender. Further Acknowledgment
can be made as a synchronous reply only. There is no way to return a response
in asynchronous manner.</p>
</div>
<p>Constructors:</p>
<div>
<pre class="programlisting">
constructor method wsa_cli ()
</pre>
</div>
<p>Instantiate a new addressing placeholder ; with new message id. </p>
</li>
<li>
<p>
<strong>WS-RM Client UDT</strong>
</p>
<p>The following is a core UDT for the sender's activity.
It is used to establish a message sequence context, to
set various parameters and to send/check/cancel WS-RM
encapsulated SOAP messages to the sender.</p>
<div>
<pre class="programlisting">
create type wsrm_cli as
(
url varchar,
seq varchar,
msgno int default -1,
assurance varchar,
expiry datetime,
address wsa_cli,
i_timeout int,
resend_intl int,
ack_intl int,
dirty int default 0,
is_last int default 0,
is_finish int default 0
)
temporary self as ref
</pre>
</div>
<p>Members:</p>
<ul>
<li>
<strong>url</strong> - the recipient's URL</li>
<li>
<strong>seq</strong> - identifier; unique Id for batch of
messages to be sent together</li>
<li>
<strong>msgno</strong> - unique number/unsigned integer greater than 1,
unique identifying a message within a sequence</li>
<li>
<strong>assurance</strong> - policy to be applied on receiver
side : AtLeastOne; InOrder; AtMostOne </li>
<li>
<strong>expiry</strong> - message expiration </li>
<li>
<strong>address</strong> - a UDT of type <span class="computeroutput">wsa_cli</span>;
identifying sender and receiver URLs</li>
<li>
<strong>i_timeout</strong> - inactivity timeout</li>
<li>
<strong>ack_intl</strong> - Acknowledgment interval</li>
<li>
<strong>dirty</strong> - (internal use)</li>
<li>
<strong>is_last</strong> - the current message is a last in sequence</li>
<li>
<strong>is_finish</strong> - transfer is finished; no more
messages are pending</li>
</ul>
<p>Constructors:</p>
<div>
<pre class="programlisting">
constructor method wsrm_cli (addr wsa_cli, url varchar),
</pre>
</div>
<p>Instantiate a new WS-RM sender object; new message sequence
This will generate a new sequence identifier, and will store it into a
outgoing sequences table. The default policy will be established.</p>
<div>
<pre class="programlisting">
constructor method wsrm_cli (addr wsa_cli, url varchar, seq varchar),
</pre>
</div>
<p>Instantiate a WS-RM sender object from a persisted state;
The policy and parameters will be read from database and instantiated
in WS-RM sender's object.</p>
<p>Methods:</p>
<div>
<pre class="programlisting">
method create_sequence () returns any,
</pre>
</div>
<p>Start a new sequence with current WS-RM sender's object;</p>
<div>
<pre class="programlisting">
method send_message (req soap_client_req, last int) returns any,
</pre>
</div>
<p>Send a message to the recipient; depending on 'last' flag this can be
designate open or closed message sequence.
The 'req' must be fulfilled with appropriate parameters (see above).</p>
<div>
<pre class="programlisting">
method send_message (req soap_client_req) returns any,
</pre>
</div>
<p>same as send_message (req soap_client_req, 0)</p>
<div>
<pre class="programlisting">
method finish (req soap_client_req) returns any,
</pre>
</div>
<p>same as send_message (req soap_client_req, 1)</p>
<div>
<pre class="programlisting">
method check_state () returns any,
</pre>
</div>
<p>retrieves a state for a sequence. If sequence is closed and all is
delivered no remote call will be performed. If an message is in pending state
a remote call will be issued to check the state of message sequence.
The return value is an array containing message numbers (id's within sequence)
and their state: 0 or 1 - send or pending</p>
<div>
<pre class="programlisting">
method cancel () returns any,
</pre>
</div>
<p>cancel the sequence; kill it on WS-RM sender site ; say that to recipient to
do that also.</p>
<div>
<pre class="programlisting">
method set_parameter (name varchar, val any) returns any,
</pre>
</div>
<p>Set a parameter to the current message sequence : like policy; timeout etc.
The parameters will be sent together with next WS-RM conversation.
Note: Some of parameters may invalidate previous state of message transfer; so
in this case the sender will receive a fault and application must handle the
situation properly. </p>
<p>Valid 'name's are :</p>
<ul>
<li>
<strong>Assurance</strong> - 'AtMostOnce','AtLeastOnce','ExactlyOnce','InOrder'</li>
<li>
<strong>Expiry</strong> - date of expiration</li>
<li>
<strong>Timeout</strong> - inactivity timeout in milliseconds</li>
<li>
<strong>RetryInterval</strong> - retry on every n milliseconds if message is not sent</li>
<li>
<strong>AckInterval</strong> - Acknowledgment interval in milliseconds</li>
</ul>
</li>
</ul>
<div class="formalpara">
<strong>Sender's responder (endpoint)</strong>
<p>To receive an asynchronous Acknowledgment the sender must
have an endpoint to handle them.
The <span class="computeroutput">WSRMSequenceAcknowledgment()</span>
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.</p>
</div>
<br />
<a name="wsrmrcvrapi" />
<h3>15.7.3. WSRM Receiver API</h3>
<p>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.</p>
<p>The following is the list of WS-RM receiver wrappers:</p>
<ol>
<li>
<div class="formalpara">
<strong>WSRMSequence</strong>
<p>accept and store a Sequence requests. This is used
to accept Sequence requests from sender and will perform the
following actions:</p>
</div>
<ul>
<li>store the message in incoming message log table</li>
<li>process and apply the Policy attachment (if supplied); otherwise
apply default rule: AtMostOnce</li>
<li>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.</li>
<li>If an error occurred a Fault will be generated </li>
</ul>
</li>
<li>
<div class="formalpara">
<strong>WSRMSequenceTerminate</strong>
<p>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.</p>
</div>
</li>
<li>
<div class="formalpara">
<strong>WSRMAckRequested</strong>
<p>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.</p>
</div>
</li>
</ol>
<p>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.</p>
<br />
<a name="wsrmsetupendpoint" />
<h3>15.7.4. WS-RM Protocol Endpoint Configuration</h3>
<p>The setup is a virtual directory definition and grant of
rights to the procedures for sender and receiver endpoints.</p>
<p>This will be demonstrated as an example of setting up both endpoints:</p>
<ul>
<li>
<p>
<strong>Sender</strong>
</p>
<div>
<pre class="programlisting">
create user WSRMS;
grant execute on WSRMSequenceAcknowledgment to WSRMS;
vhost_define (lpath=>'/replyto', ppath=>'/SOAP/', soap_user=>'WSRMS');
</pre>
</div>
</li>
<li>
<p>
<strong>Reply</strong>
</p>
<div>
<pre class="programlisting">
create user WSRMR;
grant execute on WSRMSequence to WSRMR;
grant execute on WSRMSequenceTerminate to WSRMR;
grant execute on WSRMAckRequested to WSRMR;
vhost_define (lpath=>'/wsrm', ppath=>'/SOAP/', soap_user=>'WSRMR');
</pre>
</div>
</li>
</ul>
<a name="ex_wsrmping" />
<div class="example">
<div class="exampletitle">WS-RM Ping Test Example</div>
<p>This is an example client used to perform the interoperability
test "Ping" as proposed in "Interop Workshop Scenarios"</p>
<div>
<pre class="programlisting">
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/" />');
</pre>
</div>
<div>
<pre class="programlisting">
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>');
</pre>
</div>
<div>
<pre class="programlisting">
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;
}
;
</pre>
</div>
</div>
<br />
<a name="wsrmmsgexamples" />
<h3>15.7.5. Message Examples</h3>
<a name="ex_wsrminitreq" />
<div class="example">
<div class="exampletitle">Example: Initial request</div>
<div>
<pre class="programlisting">
<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>
</pre>
</div>
<p>receiver accepts and return just</p>
<div>
<pre class="programlisting">
HTTP/1.1 202 Accepted
Content-Length: 0
</pre>
</div>
<p>Last message</p>
<div>
<pre class="programlisting">
<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>
</pre>
</div>
<p>receiver accepts and returns </p>
<div>
<pre class="programlisting">
HTTP/1.1 202 Accepted
Content-Length: 0
</pre>
</div>
<p>Sequence Acknowledgment response; sent via another channel</p>
<div>
<pre class="programlisting">
<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>
</pre>
</div>
<p>initial sender accepts and returns </p>
<div>
<pre class="programlisting">
HTTP/1.1 202 Accepted
Content-Length: 0
</pre>
</div>
</div>
<br />
<a name="wsrmschema" />
<h3>15.7.6. WS-RM Schema</h3>
<div>
<pre class="programlisting">
<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"/>
<!-- *** ASSERTIONS *** -->
<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>
</pre>
</div>
<br />
<table border="0" width="90%" id="navbarbottom">
<tr>
<td align="left" width="33%">
<a href="ws-routing.html" title="Web Services Routing Protocol (WS-Routing)">Previous</a>
<br />Web Services Routing Protocol (WS-Routing)</td>
<td align="center" width="34%">
<a href="webservices.html">Chapter Contents</a>
</td>
<td align="right" width="33%">
<a href="vwstrust.html" title="Web Services Trust Protocol (WS-Trust)">Next</a>
<br />Web Services Trust Protocol (WS-Trust)</td>
</tr>
</table>
</div>
<div id="footer">
<div>Copyright© 1999 - 2009 OpenLink Software All rights reserved.</div>
<div id="validation">
<a href="http://validator.w3.org/check/referer">
<img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" />
</a>
<a href="http://jigsaw.w3.org/css-validator/">
<img src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!" height="31" width="88" />
</a>
</div>
</div>
</body>
</html>
distrib
>
Fedora
>
14
>
x86_64
>
media
>
updates
>
by-pkgid
>
71d40963b505df4524269198e237b3e3
>
files
>
990
