Package com.tangosol.net.topic

Interface Publisher<V>

Type Parameters:
V - the value type
All Superinterfaces:
AutoCloseable
public interface Publisher<V> extends AutoCloseable
Publisher provides a means to publish values to the NamedTopic.

The factory method NamedTopic.createPublisher(Publisher.Option[]) or Session.createPublisher(String) allows one to specify one or more Publisher.Options to configure the Publisher.

Since the publish(Object) method is asynchronous, there is a flush() that allows one to block until all outstanding sent values for the Publisher have completed.

Channels

Topics use the concept of channels to improve scalability. This is similar to how Coherence uses partition for caches but to avoid confusion the name channel was chosen. The default is the next prime above the square root of the partition count for the underlying cache service, which for the default partition count of 257 is 17 channels.

Publishers publish messages to a channel based on their ordering configuration. Subscribers then subscribe from channels by assigning channel ownership to subscribers. An anonymous subscriber has ownership of all channels. A subscriber that is part of a subscriber group has ownership of a sub-set of the available channels.

Channel count is configurable, but ideally should not be set too high nor too low. For example setting the channel count to 1, would mean that all publishers contend to publish to a single channel, and that only one subscriber in a subscriber group will be able to receive messages. Setting the channel count too high (above say the number of publishers) may mean that some channels never receive any messages and are wasted. Finding the appropriate value is admittedly non-trivial, however when faced with maxing out throughput from a publishers perspective this is a configuration that can be tweaked.

Positions

Elements in a NamedTopic are published to a channel have a unique Position within that channel. A Position is an opaque representation of the underlying position as theoretically the implementation of the Position could change for different types of topic. Positions are used in various places in the API, for example, positions can be committed, and they can be used to move the subscriber to backwards or forwards within channels. A Position is serializable so they can be stored and recovered to later reset a subscriber to a desired position. Positions are Comparable so positions for elements can be used to determine whether how two elements related to each other within a channel.
Since:
Coherence 14.1.1
Author:
jf/jk/mf 2015.06.03

  • Field Details

    • PROP_CHANNEL_COUNT

      static final String PROP_CHANNEL_COUNT
      The system property to use to configure a default publisher channel count.
      See Also:

  • Method Details

    • send

      @Deprecated default CompletableFuture<Void> send(V value)
      Deprecated.
      Use publish(Object) which returns metadata about the published value
      Asynchronously publish the specified value to the topic.

      Cancellation of the returned future is best effort and is not guaranteed to stop the corresponding publication of the value, for example example the request may already be on the wire and being processed on a storage member.

      Parameters:
      value - the value to add to the topic
      Returns:
      a CompletableFuture which can be used to identify when the value has been delivered to the topic
      Throws:
      IllegalStateException - if this Publisher is closed or the parent topic has been released or destroyed

    • publish

      CompletableFuture<Publisher.Status> publish(V value)
      Asynchronously publish the specified value to the topic.

      Cancellation of the returned future is best effort and is not guaranteed to stop the corresponding publication of the value, for example example the request may already be on the wire and being processed on a storage member.

      Published messages will be recieved by subscribers in order determined by the Publisher.OrderBy option used to create this Publisher. Message ordering can also be controlled by publishing values that implement the Publisher.Orderable interface, in which case the order identifier provided by the Publisher.Orderable value will override any ordering configured for the Publisher.

      Parameters:
      value - the value to add to the topic
      Returns:
      a CompletableFuture containing the Publisher.Status, which can be used to identify when the value has been delivered to the topic and the position it was added to the topic
      Throws:
      IllegalStateException - if this Publisher is closed or the parent topic has been released or destroyed

    • getFlowControl

      FlowControl getFlowControl()
      Return the FlowControl object governing this publisher.
      Returns:
      the FlowControl object.

    • flush

      CompletableFuture<Void> flush()
      Obtain a CompletableFuture that will be complete when all of the currently outstanding publish operations complete.

      The returned CompletableFuture will always complete normally, even if the outstanding operations complete exceptionally.

      Returns:
      a CompletableFuture that will be completed when all of the currently outstanding publish operations are complete

    • close

      void close()
      Close this Publisher.

      This is a blocking method and will wait until all outstanding CompletableFutures returned from previous calls to publish(Object) have completed before returning.

      Specified by:
      close in interface AutoCloseable

    • onClose

      void onClose(Runnable action)
      Add an action to be executed when this Publisher is closed.
      Parameters:
      action - the action to execute

    • getChannelCount

      int getChannelCount()
      Returns the number of channels in the underlying NamedTopic that can be published to.
      Returns:
      the number of channels in the underlying NamedTopic that can be published to

    • getNamedTopic

      NamedTopic<V> getNamedTopic()
      Returns the underlying NamedTopic that this Publisher publishes to.
      Returns:
      the underlying NamedTopic that this Publisher publishes to

    • isActive

      boolean isActive()
      Specifies whether or not the Publisher is active.
      Returns:
      true if the NamedCache is active; false otherwise