Skip to main content
Previous sectionNext section

Using WS-ReliableMessaging

InterSystems IRIS supports parts of the WS-ReliableMessaging specifications, as described in the first topic. This specification provides a mechanism to reliably deliver a sequence of messages, in order. The easiest way to use this support is to create a security policy and use the Reliable Message Delivery option in the Web Service/Client Configuration Wizard. Another option is to manually use reliable messaging, as described in this topic.

Sending a Sequence of Messages from the Web Client

To send a sequence of messages reliably from an InterSystems IRIS web client to a web service that supports WS-ReliableMessaging, do the following:

  1. Specify the security header elements of the web client as needed. See previous topics of this book.

    If you are using WS-SecureConversation, as described in the previous topic, start the secure conversation.

  2. Call the Create() class method of %SOAP.RM.CreateSequence. This returns an instance of that class.

    This method has the following signature:

    classmethod Create(addressingNamespace As %String, 
                       oneWay As %Boolean = 0, 
                       retryInterval As %Float = 1.0, 
                       maxRetryCount As %Integer = 8, 
                       expires As %xsd.duration, 
                       SSLSecurity As %Boolean = 0) as %SOAP.RM.CreateSequence
    Copy code to clipboard

    Where:

    • addressingNamespace is the namespace being used for WS-Addressing support. The default is "http://www.w3.org/2005/08/addressing"

    • oneWay is true if only request sequence is to be created.

    • retryInterval is interval in seconds to wait before retry.

    • maxRetryCount is the maximum number of retries when no activity has taken place.

    • expires is an XML format duration that specifies requested duration of the sequence to be sent.

    • SSLSecurity specifies whether the web client uses SSL to connect to the web service.

  3. Call the %StartRMSession() method of the web client and pass the instance of %SOAP.RM.CreateSequence as the argument.

    Note that you can use the instance of %SOAP.RM.CreateSequence only one time. That is, you cannot use it to create another session later.

  4. Invoke web methods as needed.

    Use the same web client instance each time.

  5. Call the %CloseRMSession() method of the web client when you are done sending messages.

Important:

Also make sure to sign the WS-ReliableMessaging headers as described in the next section.

Signing the WS-ReliableMessaging Headers

You can sign the WS-ReliableMessaging headers in either of the following ways.

Signing the Headers with the SecurityContextToken

If you are also using WS-SecureConversation, as described in the previous topic, the SecurityContextToken property of web client contains a symmetric key that you can use to sign the WS-ReliableMessaging header elements. To do so, call the AddSTR() method of the instance of %SOAP.RM.CreateSequence, passing the SecurityContextToken property as the argument:

 do createsequence.AddSTR(client.SecurityContextToken)
Copy code to clipboard

Do this before calling %StartRMSession().

Signing the Headers When Signing the Message

You can also sign the WS-ReliableMessaging headers in the same way that you sign the rest of the message. To do so, add the value $$$SOAPWSIncludeRMHeaders to the signatureOptions argument when you call the Create() or CreateX509() method of %XML.Signature. The $$$SOAPWSIncludeRMHeaders macro is included in the %soap.inc file.

Modifying a Web Service to Support WS-ReliableMessaging

To modify an InterSystems IRIS web service to support WS-ReliableMessaging, modify the web methods so that they do the following:

  • Verify the inbound request messages contain the WS-ReliableMessaging headers.

  • Verify that the WS-ReliableMessaging headers are signed.

    Note that InterSystems IRIS automatically checks whether any signatures are valid. See the topic “Validating and Decrypting Inbound Messages.”

  • Optionally specify the parameters of the web service class to fine-tune the behavior of the web service, as described in the next section.

It is easier, however, to create a security policy and use the Reliable Message Delivery option in the Web Service/Client Configuration Wizard.

Controlling How the Web Service Handles Reliable Messaging

You can specify the following parameters of the web service class to fine-tune the behavior of the web service:

RMINORDER

Corresponds to the InOrder policy assertion of WS-ReliableMessaging. Specify this as either 0 (false) or 1 (true). See the Web Services Reliable Messaging Policy 1.1 specification for details.

By default, when this parameter is not specified, an InterSystems IRIS the web service does not issue SOAP faults about the order of messages.

RMDELIVERYASSURANCE

Corresponds to the DeliveryAssurance policy assertion of WS-ReliableMessaging. Specify this as "ExactlyOnce", "AtLeastOnce", or "AtMostOnce". See the Web Services Reliable Messaging Policy 1.1 specification for details.

By default, when this parameter is not specified, an InterSystems IRIS the web service does not issue SOAP faults about any failures to deliver according to this policy assertion.

RMINACTIVITYTIMEOUT

Specifies the inactivity timeout, in seconds, for the sequence received by the web service. The default is 10 minutes.

You can specify the same parameters in a web service class that uses a security policy that uses the Reliable Message Delivery option.

Also, you can implement the %OnCreateRMSession() callback method of the web service. This method is invoked at the start of WS-ReliableMessaging session before the %SOAP.RM.CreateSequenceResponse is returned. The response argument has been completely created and not yet returned at this point. This callback gives you an opportunity to add any required Security header elements to the SecurityOut property of the web service. If WS-Policy is used, then WS-Policy support does this automatically. For the method signature, see the class reference for %SOAP.WebService.