Package com.tangosol.net.topic

Interface NamedTopic<V>

Type Parameters:

V - the type of the topic values

All Superinterfaces:

AutoCloseable, NamedCollection, Releasable

public interface NamedTopic<V>
extends NamedCollection

NamedTopic represents a topic entity for publish/subscribe messaging.

A topic may have any number of publishers or subscribers. Subscribers subscribe directly to the topic or subscribe to a logical subscriber group of the topic. Each published value to a topic is delivered to all direct topic Subscribers and each subscriber group of the topic. Each value of a subscriber group is only consumed by one subscriber group member. Thus, each subscriber group in effect behaves like a queue over the topic data.

Once published, a value will be retained by the topic until it has either expired or has been received by all subscriber group(s) and direct topic Subscriber(s) which were registered prior to it being published. The ordering of values within the topic is dependent on the Publisher.OrderBy option.

Subscriber Group Lifecycle
A subscriber group is created either at configuration time or dynamically. A subscriber-group child element of a topic-mapping element in a cache configuration file statically configures a subscriber group when the topic is created, ensuring all values published to the topic are also delivered to the statically configured subscriber group. A subscriber group is created dynamically when a createSubscriber call specifies a subscriber group name using the option Subscriber.Name.of(String) and the subscriber group does not exist on the NamedTopic.

One must actively manage a NamedTopic's logical subscriber groups since their life span is independent of their active Subscriber membership. destroySubscriberGroup(String) releases storage and stops accumulating topic values for a subscriber group.

To release storage resources for unconsumed values for a direct topic Subscriber, it is sufficient to ensure it is closed. Both topic Publisher and Subscriber can be defined with the try-with-resource pattern to ensure their resources are closed when no longer in scope.

Since:

Coherence 14.1.1

Author:

jf/jk/mf 2015.06.03

See Also:

Publisher, Subscriber

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	NamedTopic.ElementCalculator	A unit calculator is an object that can calculate the cost of storing an element in a topic.

Nested classes/interfaces inherited from interface com.tangosol.net.NamedCollection

NamedCollection.Option

Field Summary

Fields

Modifier and Type	Field	Description
static int	DEFAULT_CHANNEL_COUNT	The topic should have the default number of channels.
static long	DEFAULT_PAGE_CAPACITY_BYTES	The default capacity of pages when using the default binary calculator (1MB).
static Seconds	DEFAULT_RECONNECT_RETRY_SECONDS	The default reconnect retry.
static Seconds	DEFAULT_RECONNECT_TIMEOUT_SECONDS	The default reconnect timeout.
static Seconds	DEFAULT_RECONNECT_WAIT_SECONDS	The default reconnect wait.
static Seconds	DEFAULT_SUBSCRIBER_TIMEOUT_SECONDS	The default subscriber timeout.

Method Summary

Modifier and Type	Method	Description
default Publisher<V>	createPublisher()	Create a Publisher that can publish values into this NamedTopic.
Publisher<V>	createPublisher(Publisher.Option<? super V>... options)	Create a Publisher that can publish values into this NamedTopic.
default Subscriber<V>	createSubscriber()	Create a direct Subscriber to the topic that receives all values from this NamedTopic.
<U> Subscriber<U>	createSubscriber(Subscriber.Option<? super V,U>... options)	Create a Subscriber that can receive values from this NamedTopic.
void	destroySubscriberGroup(String sGroup)	Destroy the named subscriber group for the associated topic.
default void	ensureSubscriberGroup(String sName)	Ensure that the specified subscriber group exists for this topic.
void	ensureSubscriberGroup(String sGroup, Filter<?> filter, ValueExtractor<?,?> extractor)	Ensure that the specified subscriber group exists for this topic.
int	getChannelCount()	Returns the number of channels that this topic has.
default int	getRemainingMessages(String sSubscriberGroup)	Returns the number of remaining messages to be read from the topic for the specific subscriber group.
int	getRemainingMessages(String sSubscriberGroup, int... anChannel)	Returns the number of remaining messages to be read from the topic for the specific subscriber group, and optionally for one or more specific channels.
Set<String>	getSubscriberGroups()	Return the set of named subscriber group(s) and statically configured subscriber-group(s).
default TopicService	getTopicService()	Return the TopicService managing this NamedTopic.
default boolean	isDestroyed()	Specifies whether this NamedTopic has been destroyed.
default boolean	isReleased()	Specifies whether this NamedTopic has been released.

Methods inherited from interface com.tangosol.net.NamedCollection

destroy, getName, getService

Methods inherited from interface com.tangosol.net.Releasable

close, isActive, release

Field Detail

DEFAULT_CHANNEL_COUNT

static final int DEFAULT_CHANNEL_COUNT

The topic should have the default number of channels.

See Also:

Constant Field Values

DEFAULT_PAGE_CAPACITY_BYTES

static final long DEFAULT_PAGE_CAPACITY_BYTES

The default capacity of pages when using the default binary calculator (1MB).

See Also:

Constant Field Values

DEFAULT_SUBSCRIBER_TIMEOUT_SECONDS

static final Seconds DEFAULT_SUBSCRIBER_TIMEOUT_SECONDS

The default subscriber timeout.

DEFAULT_RECONNECT_TIMEOUT_SECONDS

static final Seconds DEFAULT_RECONNECT_TIMEOUT_SECONDS

The default reconnect timeout.

DEFAULT_RECONNECT_RETRY_SECONDS

static final Seconds DEFAULT_RECONNECT_RETRY_SECONDS

The default reconnect retry.

DEFAULT_RECONNECT_WAIT_SECONDS

static final Seconds DEFAULT_RECONNECT_WAIT_SECONDS

The default reconnect wait.

Method Detail

createPublisher

Publisher<V> createPublisher(Publisher.Option<? super V>... options)

Create a Publisher that can publish values into this NamedTopic.

Parameters:

options - the Publisher.Options controlling the Publisher

Returns:

a Publisher that can publish values into this NamedTopic

createPublisher

default Publisher<V> createPublisher()

Create a Publisher that can publish values into this NamedTopic.

Returns:

a Publisher that can publish values into this NamedTopic

createSubscriber

<U> Subscriber<U> createSubscriber(Subscriber.Option<? super V,U>... options)

Create a Subscriber that can receive values from this NamedTopic.

Parameters:

options - the Subscriber.Options controlling the Subscriber

Returns:

a Subscriber that can receive values from this NamedTopic

createSubscriber

default Subscriber<V> createSubscriber()

Create a direct Subscriber to the topic that receives all values from this NamedTopic.

Returns:

a Subscriber that can receive values from this NamedTopic

ensureSubscriberGroup

default void ensureSubscriberGroup(String sName)

Ensure that the specified subscriber group exists for this topic.

Parameters:

sName - the name of the subscriber group

Throws:

IllegalStateException - if the subscriber group already exists with a different filter or converter function

ensureSubscriberGroup

void ensureSubscriberGroup(String sGroup,
                           Filter<?> filter,
                           ValueExtractor<?,?> extractor)

Ensure that the specified subscriber group exists for this topic.

Parameters:

sGroup - the name of the subscriber group

filter - the Filter used to filter messages to be received by subscribers in the group

extractor - the ValueExtractor used to convert messages to be received by subscribers in the group

Throws:

IllegalStateException - if the subscriber group already exists with a different filter or converter extractor

destroySubscriberGroup

void destroySubscriberGroup(String sGroup)

Destroy the named subscriber group for the associated topic.

Releases storage and stops accumulating topic values for destroyed subscriber group. This operation will impact all members of the subscriber group.

getSubscriberGroups

Set<String> getSubscriberGroups()

Return the set of named subscriber group(s) and statically configured subscriber-group(s).

Returns:

the set of named subscriber groups.

isDestroyed

default boolean isDestroyed()

Specifies whether this NamedTopic has been destroyed.

Implementations must override this method to provide the necessary information.

Specified by:

isDestroyed in interface NamedCollection

Returns:

true if the NamedTopic has been destroyed; false otherwise

isReleased

default boolean isReleased()

Specifies whether this NamedTopic has been released.

Implementations must override this method to provide the necessary information.

Specified by:

isReleased in interface Releasable

Returns:

true if the NamedTopic has been released; false otherwise

getChannelCount

int getChannelCount()

Returns the number of channels that this topic has.

Returns:

the number of channels that this topic has

getRemainingMessages

default int getRemainingMessages(String sSubscriberGroup)

Returns the number of remaining messages to be read from the topic for the specific subscriber group.

This method is a sum of the remaining messages for each channel from the last committed message (exclusive) to the current tail. This result returned by this method is somewhat transient in situations where there are active Subscribers with in-flight commit requests, so the count may change just after the method returns. Message expiry may also affect the returned value, if messages expire after the count is returned.

Parameters:

sSubscriberGroup - the name of the subscriber group

Returns:

the number of remaining messages for the subscriber group

getRemainingMessages

int getRemainingMessages(String sSubscriberGroup,
                         int... anChannel)

Returns the number of remaining messages to be read from the topic for the specific subscriber group, and optionally for one or more specific channels.

This method is a sum of the remaining messages for each channel from the last committed message (exclusive) to the current tail. This result returned by this method is somewhat transient in situations where there are active Subscribers with in-flight commit requests, so the count may change just after the method returns. Message expiry may also affect the returned value, if messages expire after the count is returned.

Parameters:

sSubscriberGroup - the name of the subscriber group

anChannel - one or more optional channels

Returns:

the number of remaining messages for the subscriber group

getTopicService

default TopicService getTopicService()

Return the TopicService managing this NamedTopic.

Returns:

the TopicService managing this NamedTopic