21 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 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>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 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>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 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.
Parent topic: Defining Topic Mappings
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’stopic-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>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 21-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 21-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 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
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. For an example of a
configuration, see Configuring a Persistent Topic.
Parent topic: Defining a Distributed Topic Scheme