V - the type of the value returned to the subscriberpublic interface Subscriber<V> extends AutoCloseable
Subscriber subscribes either directly to a NamedTopic or to a subscriber group of the NamedTopic.
Each value published to a NamedTopic is delivered to all of its subscriber groups
and direct Subscribers. Within each subscriber group, each value is only received by one of the group members,
enabling distributed, parallel processing of the values delivered to the subscriber group.
Thus each subscriber group in effect behaves like a queue over the topic data.
The factory method NamedTopic.createSubscriber(Subscriber.Option[]) allows one to specify
one or more Subscriber.Options to configure the Subscriber. The Subscriber.Name.of(String) option
specifies the subscriber group for the Subscriber to join. If this option is not specified, the
Subscriber is a direct subscriber to the topic. All Subscriber options and defaults are summarized in a table in Subscriber.Option.
| Modifier and Type | Interface and Description |
|---|---|
static class |
Subscriber.CompleteOnEmpty<V>
The CompleteOnEmpty option indicates that the
CompletableFuture returned
from the receive() operation should complete with a null Subscriber.Element
upon identifying that the topic is or has become empty. |
static class |
Subscriber.Convert<V,U>
The Convert option specifies a
Function that will convert topic values that
a subscriber is interested in receiving prior to sending them to the subscriber. |
static interface |
Subscriber.Element<V>
Element represents a container for returned values.
|
static class |
Subscriber.Filtered<V>
The Filtered option specifies a filter that will determine which topic values a
subscriber is interested in receiving.
|
static class |
Subscriber.Name<V>
The Name option is used to specify a subscriber group name.
|
static interface |
Subscriber.Option<V,U>
A marker interface to indicate that a class is a valid
Subscriber.Option
for a Subscriber. |
| Modifier and Type | Method and Description |
|---|---|
void |
close()
Close the Subscriber.
|
FlowControl |
getFlowControl()
Return the
FlowControl object governing this subscriber. |
boolean |
isActive()
Determine whether this
Subscriber is active. |
void |
onClose(Runnable action)
Add an action to be executed when this
Subscriber is closed. |
CompletableFuture<Subscriber.Element<V>> |
receive()
Receive a value from the topic.
|
CompletableFuture<Subscriber.Element<V>> receive()
Subscriber.CompleteOnEmpty option.
Note: If the returned future is cancelled it is possible that a value
may still be considered by the topic to have been received by this group, while the group would consider this
a lost value. Subscriber implementations will make a best effort to prevent such loss, but it cannot be guaranteed
and thus cancellation is not advisable.
FlowControl getFlowControl()
FlowControl object governing this subscriber.void close()
Closing a subscriber ensures that no new receive() requests will be accepted and all pending
receive requests will be completed or safely cancelled.
For a direct topic Subscriber, close() enables the release of storage resources for
unconsumed values.
For a group member, close() indicates that this member has left its corresponding group.
One must actively manage a NamedTopic's logical subscriber groups since their life span
is independent of active Subscriber group membership.
NamedTopic.destroySubscriberGroup(String) releases storage and stops accumulating topic values for a subscriber group.
close in interface AutoCloseableboolean isActive()
Subscriber is active.true if this Subscriber is activevoid onClose(Runnable action)
Subscriber is closed.action - the action to execute