22 Topic Configurations by Example

You can learn how to configure Coherence Topics by reviewing a series of sample Topic scheme definitions that can be used or modified as required. For detailed instructions on how to configure Topics, see Configuring Topics.

This chapter includes the following topics:

• Define a Durable Subscriber Group
  The example below shows how to statically configure a durable subscriber-group durable-subscription for the topicWithDurableSubscription Topic. You can define none, one, or many subscriber groups for a Topic. All values published to topicWithDurableSubscription will be accumulated for this subscriber group.
• Configuring Value Expiry and Upper Bound on Storage Used for Values Retained for a Topic
  The following example illustrates how to parameterize a paged-topic-scheme element so that it can be configured via topic-mapping user-defined parameter macros.
• Configuring a Persistent Topic
  If persistence is enabled on a Topic and the entire cluster is restarted, the outstanding unconsumed values on the Topic for subscribers, and subscriber group(s) are recovered during persistence recovery operations.

Define a Durable Subscriber Group

The example below shows how to statically configure a durable subscriber-group durable-subscription for the topicWithDurableSubscription Topic. You can define none, one, or many subscriber groups for a Topic. All values published to topicWithDurableSubscription will be accumulated for this subscriber group.

<topic-mapping>
  <topic-name>topicWithDurableSubscription</topic-name>
  <scheme-name>topic-scheme</scheme-name>
  <value-type>java.lang.String</value-type>
  <subscriber-groups>
    <subscriber-group>
      <name>durable-subscription</name>
    </subscriber-group>
  </subscriber-groups>
</topic-mapping>

Note:

Since each value published to a Topic is retained until all subscriber(s)/subscriber group(s) have consumed the value, it is important to actively manage subscriber groups. If a statically configured subscriber group is no longer necessary, remove it from the topic-mapping configuration file. The life cycle of statically configured and dynamically created subscriber groups should be manage as described in list subscriber groups and destroy subscriber group.

Configuring Value Expiry and Upper Bound on Storage Used for Values Retained for a Topic

The following example illustrates how to parameterize a paged-topic-scheme element so that it can be configured via topic-mapping user-defined parameter macros.

See Using User-Defined Parameter Macros for details on how to use this feature with cache-mapping. The same usage model applies to topic-mapping.

In the example below, the paged-topic-scheme.configurable-topic-scheme.expiry-delay has a user-defined parameter macro default value of 0; thus, the default expiry for the Topic values will be to never expire. The default high-units user-defined parameter macro value is 0B; thus, there is no storage limit for paged-type-scheme.configurable-topic-scheme unless the referring topic-mapping explicitly defines expiry-delay and high-units parameters. For this example, the topic-mapping.initial-params override both expiry-delay and high-units.

Example 22-1 Configure paged-topic-scheme using User-defined Parameter Macros

<cache-config>
   <topic-mapping-schemes>
     <topic-mapping>
        <name>topic</name>
        <scheme>configurable-topic-scheme</scheme>
        <initial-params>
          <init-param>
            <param-name>high-units</param-name>
            <param-value>2G<param-value>
          </init-param>
          <init-param>
            <param-name>expiry-delay</param-name>
            <param-value>12h<param-value>
          </init-param>
        </initial-params>
     <topic-mapping>
   <topic-mapping-scheme>
   <caching-schemes>
     <paged-topic-scheme>
       <scheme-name>configurable-topic-scheme</scheme-name>
       <service-name>DistributedTopicService</service-name>
       <storage>on-heap</storage>
       <expiry-delay>{expiry-delay 0}</expiry-delay>
       <high-units>{high-units 0B}</high-units>
    </paged-topic-scheme>
   <caching-schemes>
</cache-config>

Configuring a Persistent Topic

If persistence is enabled on a Topic and the entire cluster is restarted, the outstanding unconsumed values on the Topic for subscribers, and subscriber group(s) are recovered during persistence recovery operations.

The following is a sample configuration that enables configuring persistent Topics.

Example 22-2 Configuring transient and persistent topic-mappings with same topic scheme

<cache-config>
   <topic-mapping-schemes>
     <topic-mapping>
        <name>persistent-topic-*</name>
        <scheme>persistent-topic-scheme</scheme>
     <topic-mapping>
     <topic-mapping>
        <name>transient-topic-*</name>
        <scheme>persistent-topic-scheme</scheme>
	  <initial-params>
          <initial-param>
            <param-name>transient</param-name>
            <param-value>true</param-value>
          </initial-param>
         </initial-params>
     <topic-mapping>
   <topic-mapping-scheme>
   <caching-schemes>
     <paged-topic-scheme>
       <scheme-name>persistent-topic-scheme</scheme-name>
       <service-name>DistributedTopicService</service-name>
       <storage>on-heap</storage>
       <transient>{transient false}</transient>
       <persistence>
         <environment>default-active</environment>
       </persistence>
       <partitioned-quorum-policy-scheme>
	   <recover-quorum>{recover-quorum 0}</recover-quorum>
       <partitioned-quorum-policy-scheme>
       <autostart>true</autostart>
       <expiry-delay>{expiry-delay 0}</expiry-delay>
       <high-units>{high-units 0B}</high-units>
     </paged-topic-scheme>
   <caching-schemes>
</cache-config>

In Example 22-2, all Topic names starting with prefix persistent-topic- are persistent Topics. All Topic names starting with prefix transient-topic- are transient Topics. If paged-topic-scheme subelement transient is false and a persistence.environment is defined, the Topic is persistent. When the transient subelement is set to true, the unconsumed values of the Topic is not recovered during persistence recovery operations when a cluster is completely restarted. This example uses one of the pre-defined persistence environments, default-active, for the value of paged-topic-scheme.persistence.environment. See Overview of the Pre-Defined Persistence Environment for details. Configuration of the recover-quorum subelement is discussed in Using Quorum for Persistence Recovery. If no value is provided for recover-quorum in a topic-mapping.initial-param, the default of 0 results in the predefined Using the Dynamic Recovery Quorum Policy being used.