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:

  • Field Details

    • DEFAULT_CHANNEL_COUNT

      static final int DEFAULT_CHANNEL_COUNT
      The topic should have the default number of channels.
      See Also:

    • 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:

    • 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 Details

    • 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