Topic Configurations by Example

Define a Subscriber Group

The following example shows how to statically configure a subscriber group in the cache configuration file. The example shows a group named durable-subscription for the topic named topicWithDurableSubscription. In this way, you can define none, one, or many subscriber groups for a topic. These groups will be created as soon as the topic is created. All values published to topicWithDurableSubscription will be accumulated for this subscriber group until they have been received by a subscriber that is part of that 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.

22 Topic Configurations by Example

Define a Subscriber Group

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

Configuring a Persistent Topic