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 Subscriber
s. 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.Option
s 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 AutoCloseable
boolean isActive()
Subscriber
is active.true
if this Subscriber
is activevoid onClose(Runnable action)
Subscriber
is closed.action
- the action to execute