17.7.2.WS-RM Sender API
The WS-RM API allows for:
|register/start a conversation|
|set parameters on both sides (receiver or sender)|
|check the acknowledgment|
|retry if needed|
|to finish or cancel the conversation (can be with cancel)|
|check for faults|
The User Defined Types defined in support of WS-RM are as follows:
soap_client () parameters wrapper
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 ) ;
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).
client addressing UDT: 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.
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 )
Whose members are as follows:
mid - message identifier; unique across space and time to - where message traveling to from - from where it's sent action - WS-Addressing Action headed element fault_to - where to return the fault reply_to - where to reply; if no such URL given the "to" will be used to reply. Important Note:
A special "to" equal to '
http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous' 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.
constructor method wsa_cli ()
Instantiate a new addressing placeholder ; with new message id.
WS-RM Client UDT 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.
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
url - the recipient's URL seq - identifier; unique Id for batch of messages to be sent together msgno - unique number/unsigned integer greater than 1, unique identifying a message within a sequence assurance - policy to be applied on receiver side : AtLeastOne; InOrder; AtMostOne expiry - message expiration address - a UDT of type
wsa_cli; identifying sender and receiver URLs
i_timeout - inactivity timeout ack_intl - Acknowledgment interval dirty - (internal use) is_last - the current message is a last in sequence is_finish - transfer is finished; no more messages are pending
constructor method wsrm_cli (addr wsa_cli, url varchar),
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.
constructor method wsrm_cli (addr wsa_cli, url varchar, seq varchar),
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.
method create_sequence () returns any,
Start a new sequence with current WS-RM sender's object;
method send_message (req soap_client_req, last int) returns any,
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).
method send_message (req soap_client_req) returns any,
same as send_message (req soap_client_req, 0)
method finish (req soap_client_req) returns any,
same as send_message (req soap_client_req, 1)
method check_state () returns any,
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
method cancel () returns any,
cancel the sequence; kill it on WS-RM sender site ; say that to recipient to do that also.
method set_parameter (name varchar, val any) returns any,
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.
Valid 'name's are :
Assurance - 'AtMostOnce','AtLeastOnce','ExactlyOnce','InOrder' Expiry - date of expiration Timeout - inactivity timeout in milliseconds RetryInterval - retry on every n milliseconds if message is not sent AckInterval - Acknowledgment interval in milliseconds
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