21 Configuring Topics

You make configuration changes in the coherence-cache-config.xml file.

This section includes the following topics:

• Defining Topic Mappings
  A Topic mapping maps a Topic name to a paged Topic scheme definition.
• Defining a Paged Topic Scheme
  Topic schemes are used to define the Topic services that are available to an application.
• Remote Topics
  Coherence topics can be used from Extend and gRPC clients. Coherence topics running on a client use remote topic services to communicate with a proxy on the server. A remote topic is configured in the cache configuration file the same way as caches are configured.

Defining Topic Mappings

A Topic mapping maps a Topic name to a paged Topic scheme definition.The mappings provide a level of separation between applications and the underlying Topic definitions. The separation allows Topic implementations to be changed as required without having to change application code. Topic mappings have optional initialization parameters that are applied to the underlying paged Topic scheme definition.

Topic mappings are defined using a <topic-mapping> element within the <topic-scheme-mapping> node. Any number of Topic mappings can be created. The Topic mapping must include the Topic name and the scheme name to which the Topic name is mapped. See topic-mapping config element.

This section includes the following topics:

• Using Exact Topic Mappings
  
• Using Named Pattern Topic Mappings
  
• Using Subscriber Groups
  

Using Exact Topic Mappings

Exact Topic mapping maps a specific Topic name to a paged Topic scheme definition. An application must provide the exact name as specified in the mapping to use a Topic. The slash (/) and colon (:) are reserved characters and cannot be used in Topic names. Example 21-1 creates a single Topic mapping that maps the Topic name exampleTopic to a paged-topic-scheme definition with the scheme name topic-scheme.

Example 21-1 Sample Exact Topic Mapping

<?xml version="1.0"?>
<cache-config xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
   xmlns=http://xmlns.oracle.com/coherence/coherence-cache-config
xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config coherence-cache-config.xsd">
   <topic-scheme-mapping>
      <topic-mapping>
         <topic-name>exampleTopic</topic-name>
         <scheme-name>topic-scheme</scheme-name>
      </topic-mapping>
   </topic-scheme-mapping>
   <caching-schemes>
      <paged-topic-scheme>
         <scheme-name>topic-scheme</scheme-name>
         <service-name>PagedTopicService</service-name>
      </paged-topic-scheme>
   </caching-schemes>
</cache-config>

Using Named Pattern Topic Mappings

Name pattern Topic mappings allow applications to use patterns when specifying a Topic name. Patterns use the asterisk (*) wildcard. Name patterns alleviate an application from having to know the exact name of a Topic. The slash (/) and colon (:) are reserved characters and cannot be used in Topic names. Example 21-2 creates two Topic mappings. The first mapping uses the wildcard (*) to map any Topic name to a paged Topic scheme definition with the scheme name basic-topic-scheme. The second mapping maps the name pattern account-* to the paged Topic scheme definition with the scheme name account-topic-scheme.

Example 21-2 Sample Topic Name Pattern Mapping

<?xml version="1.0"?>
<cache-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
              xmlns=http://xmlns.oracle.com/coherence/coherence-cache-config
             xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config coherence-cache-config.xsd">
    <topic-scheme-mapping>
      <topic-mapping>
          <topic-name>*</topic-name>
          <scheme-name>basic-topic-scheme</scheme-name>
      </topic-mapping>
      <topic-mapping>
          <topic-name>account-*</topic-name>
          <scheme-name>account-topic-scheme</scheme-name>
          <service-name>accountPagedTopicService</service-name>      
      </topic-mapping>
    </topic-scheme-mapping>

    <caching-schemes>
      <paged-topic-scheme>
          <scheme-name>basic-topic-scheme</scheme-name>
      </paged-topic-scheme>
      <paged-topic-scheme>
          <scheme-name>account-topic-scheme</scheme-name>
      </paged-topic-scheme>
    </caching-schemes>
</cache-config>

For the first mapping, an application can use any name when creating a Topic and the name is mapped to the paged Topic scheme definition with the scheme name basic-topic-scheme. The second mapping requires an application to use a pattern when specifying a Topic name. In this case, an application must use the prefix account- before the name. For example, an application that specifies account-overdue as the Topic name uses the paged Topic scheme definition with the scheme name account-topic-scheme.

As shown in Example 21-2, it is possible to have a Topic name (for example account-overdue) that can be matched to multiple Topic mappings. In such cases, if an exact Topic mapping is defined, then it is always selected over any wildcard matches. Among multiple wildcard matches, the last matching wildcard mapping (based on the order in which they are defined in the file) is selected. Therefore, it is common to define less specific wildcard patterns earlier in the file that can be overridden by more specific wildcard patterns later in the file.

Note that there are different namespaces for Topic names and cache names.

Using Subscriber Groups

A Topic can have 0, 1, or more durable subscriber groups defined in the topic-mapping for the Topic. The subscriber group(s) are created along with the Topic and are ensured to exist before any data is published to the Topic. A subscriber group can have 0, 1, or more subscriber group members processing values from it. Creating multiple subscribers to a subscriber group enables parallel distributed processing of all the values collected by the durable subscriber group. When there are no subscribers, the subscriber group preserves the values for future subscriber(s) to consume each value.

Note:

A subscriber group does not have to be defined on a Topic’s topic-mapping for a subscriber to be able to join its group. For more information about configured and dynamic subscriber groups, see Subscriber Groups for a NamedTopic.

Example 21-3 Sample Durable Subscriber Group

<?xml version="1.0"?>
<cache-config xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
   xmlns=http://xmlns.oracle.com/coherence/coherence-cache-config
xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config coherence-cache-config.xsd">
   <topic-scheme-mapping>
      <topic-mapping>
         <topic-name>exampleTopic</topic-name>
         <scheme-name>topic-scheme</scheme-name>
         <subscriber-groups>
             <subscriber-group>
                 <name>durableSubscription</name>
             </subscriber-group>
         <subscriber-groups>
      </topic-mapping>
   </topic-scheme-mapping>
   <caching-schemes>
      <paged-topic-scheme>
         <scheme-name>topic-scheme</scheme-name>
         <service-name>PagedTopicService</service-name>
      </paged-topic-scheme>
   </caching-schemes>
</cache-config>

Defining a Paged Topic Scheme

Topic schemes are used to define the Topic services that are available to an application.Topic schemes provide a declarative mechanism that allows Topics to be defined independent of the applications that use them. This removes the responsibility of defining Topics from the application and allows Topics to change without having to change an application's code. Topic schemes also promote Topic definition reuse by allowing many applications to use the same Topic definition.

Topic schemes are defined within the <caching-schemes> element. A <paged-topic-scheme> scheme element and its properties are used to define a topic of that type.

A paged topic is a topic that distributes data across the cluster. The elements published to a paged topic are stored in pages and each paged topic is assigned to a Coherence partition in the same way that Coherence caches work. A page is a fixed size and will contain a number of elements depending on the size of the messages being published. When a page is filled, publishers will then publish to the next page in the topic. As pages are emptied by subscribers they are garbage collected and removed from the topic.

Sample Paged Topic Definition

The <paged-topic-scheme> element is used to define paged Topics. A paged Topic utilizes a paged (partitioned) Topic service instance. Any number of paged Topics can be defined in a cache configuration file. See paged-topic-scheme.

Example 21-4 defines a basic paged Topic that uses paged-topic as the scheme name and is mapped to the Topic name example-topic. The <autostart> element is set to true to start the service on a cache server node.

Example 21-4 Sample Paged Topic Definition

<?xml version="1.0"?>
<cache-config xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
   xmlns=http://xmlns.oracle.com/coherence/coherence-cache-config
   xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config coherence-cache-config.xsd">
   <topic-scheme-mapping>
     <topic-mapping>
       <topic-name>example-topic</topic-name>
       <scheme-name>paged-topic</scheme-name>
       <value-type>java.lang.String</value-type>
     </topic-mapping>
   </topic-scheme-mapping>
   <caching-schemes>
     <paged-topic-scheme>
        <scheme-name>paged-topic</scheme-name>
        <service-name>paged-topic-service</service-name>
        <autostart>true</autostart>
     </paged-topic-scheme>
   </caching-schemes>
</cache-config>

Note:

The <value-type> subelement of <topic-mapping> is optional and needs to be specified only to enable enhanced generic type checking in processing the values of a Topic. For information about specifying a ValueTypeAssertion when getting a Topic, see Getting a Topic Instance.

This section includes the following topics:

• Size Limited Topic
  
• Topic with Expiring Values
  
• Storage Options for Topic Values
  
• Topic Values Serializer
  
• Persistent Topic
  

Size Limited Topic

Adding a <high-units> subelement to <paged-topic-scheme> element limits the storage size of the values retained for the Topic. The Topic is considered full if this storage limit is reached. Not exceeding this high water mark is managed by default using flow control. When subscriber(s) are lagging in processing outstanding values retained on the Topic, the publishers are throttled until there is space available. See Managing the Publisher Flow Control to Place Upper Bound on Topics Storage.

Topic with Expiring Values

Adding a <expiry-delay> subelement to <paged-topic-scheme> element limits the length of time that the published value lives on Topic, waiting to be received by a Subscriber.

Storage Options for Topic Values

The <storage> subelement allows specification of on-heap, ramjournal and flashjournal to store the values and metadata for a Topic. See Using the Elastic Data Feature to Store Data for details on ramjournal and flashjournal options.

Topic Values Serializer

The <serializer> subelement of <paged-topic-scheme> element enables specifying predefined serializers pof or java(default). See serializer.

Persistent Topic

If active persistence is configured for a Topic and the entire cluster is restarted, the outstanding unconsumed values on the Topic for subscriber(s) and subscriber group(s) are recovered during persistence recovery operations. The following subelements of <paged-topic-scheme> element configure whether a Topic is persistent or not. The optional transient subelement must be false, which is its default. The optional persistence.environment subelement references a pre-defined or custom persistence environment. For an example of a configuration, see Configuring a Persistent Topic.

Remote Topics

Coherence topics can be used from Extend and gRPC clients. Coherence topics running on a client use remote topic services to communicate with a proxy on the server. A remote topic is configured in the cache configuration file the same way as caches are configured.

A remote topic is a specialized topic service that routes operations to a topic on the Coherence cluster. The remote topic and the topic on the cluster must have the same topic name. Extend clients use the NamedTopic interface as normal to get an instance of the topic. At run time, the topic operations are not run locally but instead are sent using TCP/IP to an Extend or gRPC proxy service on the cluster. The fact that the topic operations are delegated to a topic on the cluster is transparent to the client code. There is no API difference between topics on a cluster member and topics on a client.