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.
    [Note] 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 acknowledged.