Caché supports parts of the WS-ReliableMessaging specifications, as described in the first chapter. 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 chapter, which discusses the following topics:
Sending a Sequence of Messages from the Web Client
To send a sequence of messages reliably from a Caché web client to a web service that supports WS-ReliableMessaging, do the following:
Specify the security header elements of the web client as needed. See previous chapters of this book.
If you are using WS-SecureConversation, as described in the previous chapter, start the secure conversation.
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.CreateSequenceCopy code to clipboard
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.
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.
Invoke web methods as needed.
Use the same web client instance each time.
Call the %CloseRMSession() method of the web client when you are done sending messages.
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 chapter, 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 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 a Caché 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 Caché automatically checks whether any signatures are valid. See the chapter “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:
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, a Caché the web service does not issue SOAP faults about the order of messages.
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, a Caché the web service does not issue SOAP faults about any failures to deliver according to this policy assertion.
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.