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).
If you specify ordered as the reliability QoS, IceStorm forwards events to subscribers in the order in which they are received. Without this setting, events are forwarded immediately, as soon as they are received; because events can arrive from different publishers publishing to the same topic, this means that they can be forwarded to subscribers in an order that differs from the order in which IceStorm received them.
Whether the subscriber receives events in the same order in which they are sent by IceStorm also depends on the subscriber's threading model.
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.
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 qos = new java.util.HashMap();
qos.put("reliability", "ordered");
topic.subscribeAndGetPublisher(qos, proxy.ice_twoway());