An IceStorm subscriber specifies Quality of Service (QoS) parameters at the time of subscription. The supported QoS parameters are described in the sections below
On this page:
Reliability QoS for IceStorm
The QoS parameter reliability affects message delivery. The only legal values at this point are ordered and the empty string. If not specified, the default value is the empty string (meaning not ordered).
The ordered reliability QoS requires a twoway subscriber proxy. If you specify this reliability QoS, IceStorm will forward events in the order they are received but doesn't forward them immediately. Instead, IceStorm waits for the reply from the forwarding of an event before forwarding the next event. This guarantees that the subscriber will process the events in the same order as they were received even if its thread pool doesn't serialize incoming requests.
Retry Count QoS for IceStorm
IceStorm automatically removes a subscriber if ObjectNotExistException or NotRegisteredException is raised while attempting to deliver an event. IceStorm considers these exceptions as indicators of a hard failure, after which it is unnecessary to continue event delivery.
For other kinds of failures, IceStorm uses the QoS parameter retryCount to determine when to remove a subscriber. A value of -1 means IceStorm retries forever and never automatically removes a subscriber unless a hard failure occurs. A value of zero means IceStorm never retries and immediately removes the subscriber. For positive values, IceStorm decrements the subscriber's retry count for each failure and removes the subscriber once it reaches zero. Linked topics always have a configured retry count of -1. The default value of the retryCount parameter is zero.
A retry count of -1 adds some resiliency to your IceStorm application by ignoring intermittent network failures such as ConnectionRefusedException. However, there is also some risk inherent in using a retry count of -1 because an improperly configured subscriber may never be removed. For example, consider what happens when a subscriber registers using a transient endpoint: if that subscriber happens to terminate and resubscribe with a different endpoint, IceStorm will continue trying to deliver events to the subscriber at its old endpoint. IceStorm can only remove the subscriber if it receives a hard error, and that is only possible when the subscriber is reachable.
To use a retry count of -1 successfully, the subscriber should either register with a fixed endpoint, or use IceGrid to take advantage of indirect proxies and automatic activation. Furthermore, if the subscriber is expected to function correctly after a restart of its process, the subscriber must use the same identity. The application can rely on the subscribeAndGetPublisher operation to raise AlreadySubscribed when the subscriber is already subscribed.
Connection caching QoS for IceStorm
The QoS parameter connectionCached affects the connection caching setting of the subscriber proxy used for message delivery. Defining this QoS parameter is equivalent to invoking the ice_connectionCached proxy method.
Locator cache timeout QoS for IceStorm
The QoS parameter locatorCacheTimeout affects the locator cache timeout setting of the subscriber proxy used for message delivery. Defining this QoS parameter is equivalent to invoking the ice_locatorCacheTimeout proxy method.
IceStorm QoS Example
The Slice type IceStorm::QoS is defined as a dictionary whose key and value types are both string, therefore the QoS parameter name and value are both represented as strings. The code we presented in our earlier subscriber example used an empty dictionary for the QoS argument, meaning default values are used. The C++ and Java examples shown below illustrate how to set the reliability parameter to ordered.
Here is the C++ example:
IceStorm::QoS qos; qos["reliability"] = "ordered"; topic->subscribeAndGetPublisher(qos, proxy->ice_twoway());
Here is the Java example:
java.util.Map<String, String> qos = new java.util.HashMap<>();
qos.put("reliability", "ordered");
topic.subscribeAndGetPublisher(qos, proxy.ice_twoway());