20 Configuring Topics
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 Distributed Topic Scheme
Topic schemes are used to define the topic services that are available to an application.
Parent topic: Using Topics
Defining Topic Mappings
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:
Parent topic: Configuring Topics
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 20-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 20-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>DistributedTopicService</service-name> </paged-topic-scheme> </caching-schemes> </cache-config>
Parent topic: Defining Topic Mappings
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 20-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 20-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>accountDistributedTopicService</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 20-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.
Parent topic: Defining Topic Mappings
Subscriber Group
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’stopic-mapping
for a subscriber to be able to join its
group. Configured and dynamic subscriber groups are discussed in more detail in Subscriber Groups for a NamedTopic.
Example 20-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>DistributedTopicService</service-name> </paged-topic-scheme> </caching-schemes> </cache-config>
Parent topic: Defining Topic Mappings
Defining a Distributed Topic Scheme
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.
Sample Distributed Topic Definition
The <paged-topic-scheme>
element is used to define
distributed topics. A distributed topic utilizes a distributed (partitioned) topic service
instance. Any number of distributed topics can be defined in a cache configuration file.
See paged-topic-scheme.
Example 20-4 defines a basic distributed topic that uses
distributed-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 20-4 Sample Distributed 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>distributed-topic</scheme-name> <value-type>java.lang.String</value-type> </topic-mapping> </topic-scheme-mapping> <caching-schemes> <paged-topic-scheme> <scheme-name>distributed-topic</scheme-name> <service-name>distributed-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 only needs to be specified to
enable enhanced generic type checking in processing the values of a topic. See Getting a Topic Instance on how to specify a ValueTypeAssertion
when getting a topic.
This section includes the following topics:
- Size Limited Topic
- Topic with Expiring Values
- Storage Options for Topic Values
- Topic Values Serializer
- Persistent Topic
Parent topic: Configuring Topics
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.
Parent topic: Defining a Distributed Topic Scheme
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
.
Parent topic: Defining a Distributed Topic Scheme
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.
Parent topic: Defining a Distributed Topic Scheme
Topic Values Serializer
The <serializer>
subelement of
<paged-topic-scheme>
element enables specifying predefined serializers
pof
or java
(default). See serializer.
Parent topic: Defining a Distributed Topic Scheme
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. An example configuration is
provided Example 21-2.
Parent topic: Defining a Distributed Topic Scheme