IceStorm is a relatively lightweight service in that it requires very little configuration and is implemented as an IceBox service (see
Chapter 43). The configuration properties supported by IceStorm are described in
Appendix D; some of them control diagnostic output and are not discussed in this chapter.
As you will see in the description of the IceStorm properties in Appendix D, IceStorm uses its IceBox service name as the prefix for all of its properties. For example, the property
service.TopicManager.Endpoints becomes
DemoIceStorm.TopicManager.Endpoints when IceStorm is configured as the IceBox service
DemoIceStorm.
In this example, IceStorm uses Freeze to manage the service’s persistent state, therefore the first property specifies the pathname of the Freeze database environment directory (see
Chapter 39) for the service. Here the directory
db is used, which must already exist in the current working directory. This property can be omitted when the service is running in transient mode; see the description of the
service.Transient property in
Appendix D for more information.
The final two properties specify the endpoints used by the IceStorm object adapters; notice that their property names begin with
DemoIceStorm, matching the service name. The
TopicManager property specifies the endpoints on which the
TopicManager and
Topic objects reside; these endpoints must use a connection-oriented protocol such as TCP or SSL. The
Publish property specifies the endpoints used by topic publisher objects; using datagram endpoints in this property is possible but carries additional risk (see
Section 44.5.2 for more information on publisher objects).
IceStorm’s default thread pool configuration is sufficient when the service is running on a single CPU machine. On a host with multiple CPUs, you may be able to improve IceStorm’s performance by increasing the size of its client-side thread pool using the
Ice.ThreadPool.Client.* properties, but the optimal number of threads can only be determined with careful benchmarking. Refer to
Section 32.10 for more information on the Ice threading model.
There are two ways of deploying IceStorm in its highly available (replicated) mode. In both cases, adding another replica requires that all active replicas be stopped while their configurations are updated; it is not possible to add a replica while replication is running.
To remove a replica, stop all replicas and alter the configuration as necessary. You must be careful not to remove a replica if it has the latest database state. This situation will never occur during normal operation since the database state of all replicas is identical. However, in the event of a crash it is possible for a coordinator to have later database state than all replicas. The safest approach is to verify that all replicas are active prior to stopping them. You can do this using the
icestormadmin utility by checking that all replicas are in the
Normal state (see
Section 44.8).
IceGrid (see Chapter 38) is a convenient way of deploying IceStorm replicas. The term
replica is also used in the context of IceGrid, specifically when referring to groups of object adapters that participate in replication, as described in
Section 38.9. It is important to be aware of the distinction between IceStorm replication and object adapter replication; IceStorm replication
uses object adapter replication when deployed with IceGrid, but IceStorm does not
require object adapter replication as you will see in the next section.
<replica‑group id="DemoIceStorm‑PublishReplicaGroup">
</replica‑group>
<replica‑group id="DemoIceStorm‑TopicManagerReplicaGroup">
<object identity="DemoIceStorm/TopicManager"
type="::IceStorm::TopicManager"/>
</replica‑group>
<adapter name="${service}.Publish"
endpoints="tcp"
replica‑group="${instance‑name}‑PublishReplicaGroup"/>
<adapter name="${service}.TopicManager"
endpoints="tcp"
replica‑group="${instance‑name}‑TopicManagerReplicaGroup"/>
As discussed in Section 44.7.5, an application may not want publisher proxies to contain multiple endpoints. In this case you should remove
PublishReplicaGroup from the above deployment.
The next step is defining the endpoints for the adapter Node, which is used internally for communication with other IceStorm replicas and is not part of an adapter replica group:
<adapter name="${service}.Node" endpoints="tcp"/>
<property name="${service}.NodeId" value="${index}"/>
The first step is defining the set of node proxies using properties of the form Nodes.id. These proxies allow replicas to contact each other; their object identities are composed using
instance-name/nodeid.
For example, assuming we are using the IceBox service name IceStorm and have three replicas with the identifiers 0, 1, 2 and an instance name of
DemoIceStorm, we can configure the proxies as shown below:
IceStorm.InstanceName=DemoIceStorm
IceStorm.Nodes.0=DemoIceStorm/node0:tcp ‑p 13000
IceStorm.Nodes.1=DemoIceStorm/node1:tcp ‑p 13010
IceStorm.Nodes.2=DemoIceStorm/node2:tcp ‑p 13020
These properties must be defined in each replica. Additionally, each replica must define its node id, as well as the node’s endpoints. For example, we can configure node 0 as follows:
IceStorm.NodeId=0
IceStorm.TopicManager.Endpoints=tcp ‑p 10000
IceStorm.Publish.Endpoints=tcp ‑p 10001:udp ‑p 10001
IceStorm.NodeId=1
IceStorm.TopicManager.Endpoints=tcp ‑p 10010
IceStorm.Publish.Endpoints=tcp ‑p 10011:udp ‑p 10011
IceStorm.NodeId=2
IceStorm.TopicManager.Endpoints=tcp ‑p 10020
IceStorm.Publish.Endpoints=tcp ‑p 10021:udp ‑p 10021
As discussed in Section 44.7.5, an application may not want publisher proxies to contain multiple endpoints. In this case you should remove the definition of the
ReplicatedPublishEndpoints property from the above deployment.
The name of the property is not relevant, but the endpoint must match that of the service.TopicManager.Endpoints property, and the object identity must use the IceStorm instance name as the category and
TopicManager as the name.
IceStorm hosts one well-known object, which implements the IceStorm::TopicManager interface. The default identity of this object is
IceStorm/TopicManager, as seen in the stringified proxy example from
Section 44.12.4. If an application requires the use of multiple IceStorm services, it is a good idea to assign unique identities to the well-known objects by configuring the services with different values for the
service.InstanceName property, as shown in the following example:
This property changes the category of the object’s identity, which becomes Measurement/TopicManager. The client’s configuration must also be changed to reflect the new identity:
By default, IceStorm uses a Freeze database (see Chapter 39) to store its persistent state. You can configure IceStorm to use an SQL database by setting a number of properties.
