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

Nested Class Summary

Nested Classes
Modifier and Type	Interface	Description
`static class`	`Publisher.FailOnFull`	The FailOnFull option indicates that the `CompletableFuture` returned from the `publish(V)` operation should complete exceptionally upon identifying that the topic is or has become full.
`static class`	`Publisher.OnFailure`	This option controls how a `Publisher` handles a failure of an individual `publish(V)` call.
`static interface`	`Publisher.Option<V>`	A marker interface to indicate that a class is a valid `Publisher.Option` for a `Publisher`.
`static interface`	`Publisher.Orderable`	Orderable represents a value published by `Publisher` that has a natural ordering.
`static class`	`Publisher.OrderBy<V>`	The OrderBy option specifies the ordering of async operations with respect to one another.
`static class`	`Publisher.OrderById<V>`	`Publisher.OrderBy` option ensures ordering of `sent values` across all threads which share the same `orderId`.
`static class`	`Publisher.OrderByNone<V>`	`Publisher.OrderBy` option enforces no specific ordering between `sent values` allowing for the greatest level of parallelism.
`static class`	`Publisher.OrderByRoundRobin<V>`	`Publisher.OrderBy` option which computes the unit-of-order such that each message is sent to the next channel in a round-robin order.
`static class`	`Publisher.OrderByThread<V>`	`Publisher.OrderBy` option which ensures that a sequence of `sent values` issued by a single thread will complete in order.
`static class`	`Publisher.OrderByValue<V>`	`Publisher.OrderBy` option which computes the unit-of-order based on applying `constructor's` `orderIdFunction parameter` on `sent value`.
`static interface`	`Publisher.Status`	The status for a successfully published element.

Field Summary

Fields
Modifier and Type Field Description

static String PROP_CHANNEL_COUNT
The system property to use to configure a default publisher channel count.

Method Summary

All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods
Modifier and Type	Method	Description
`void`	`close()`	Close this `Publisher`.
`CompletableFuture<Void>`	`flush()`	Obtain a `CompletableFuture` that will be complete when all of the currently outstanding publish operations complete.
`int`	`getChannelCount()`	Returns the number of channels in the underlying `NamedTopic` that can be published to.
`FlowControl`	`getFlowControl()`	Return the `FlowControl` object governing this publisher.
`NamedTopic<V>`	`getNamedTopic()`	Returns the underlying `NamedTopic` that this `Publisher` publishes to.
`boolean`	`isActive()`	Specifies whether or not the `Publisher` is active.
`void`	`onClose(Runnable action)`	Add an action to be executed when this `Publisher` is closed.
`CompletableFuture<Publisher.Status>`	`publish(V value)`	Asynchronously publish the specified value to the topic.
`default CompletableFuture<Void>`	`send(V value)`	Deprecated. Use `publish(Object)` which returns metadata about the published value

- Field Detail
  - PROP_CHANNEL_COUNT
```
static final String PROP_CHANNEL_COUNT
```
    The system property to use to configure a default publisher channel count.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - 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

Interface Publisher<V>

Channels

Positions

Nested Class Summary

Field Summary

Method Summary

Field Detail

PROP_CHANNEL_COUNT

Method Detail

send

publish

getFlowControl

flush

close

onClose

getChannelCount

getNamedTopic

isActive