public class Subscription extends Object implements AutoCloseable
Image for a stream of messages from publishers on
a given channel and streamId pair. Images are aggregated under a Subscription.
Subscriptions are created via an Aeron object, and received messages are delivered
to the FragmentHandler.
By default fragmented messages are not reassembled before delivery. If an application must
receive whole messages, whether or not they were fragmented, then the Subscriber
should be created with a FragmentAssembler or a custom implementation.
It is an application's responsibility to poll(io.aeron.logbuffer.FragmentHandler, int) the Subscription for new messages.
Note:Subscriptions are not threadsafe and should not be shared between subscribers.
| Modifier and Type | Field and Description |
|---|---|
protected AvailableImageHandler |
availableImageHandler |
protected String |
channel |
protected int |
channelStatusId |
protected io.aeron.ClientConductor |
conductor |
protected static Image[] |
EMPTY_ARRAY |
protected Image[] |
images |
protected boolean |
isClosed |
protected long |
p1 |
protected long |
p2 |
protected long |
p3 |
protected long |
p4 |
protected long |
p5 |
protected long |
p6 |
protected long |
p7 |
protected long |
registrationId |
protected int |
roundRobinIndex |
protected int |
streamId |
protected UnavailableImageHandler |
unavailableImageHandler |
| Modifier and Type | Method and Description |
|---|---|
void |
addDestination(String endpointChannel)
Add a destination manually to a multi-destination Subscription.
|
long |
asyncAddDestination(String endpointChannel)
Asynchronously add a destination manually to a multi-destination Subscription.
|
long |
asyncRemoveDestination(String endpointChannel)
Asynchronously remove a previously added destination from a multi-destination Subscription.
|
AvailableImageHandler |
availableImageHandler()
Callback used to indicate when an
Image becomes available under this Subscription. |
long |
blockPoll(BlockHandler blockHandler,
int blockLengthLimit)
Poll the
Images under the subscription for available message fragments in blocks. |
String |
channel()
Media address for delivery to the channel.
|
long |
channelStatus()
Get the status of the media channel for this Subscription.
|
void |
close()
Close the Subscription so that associated
Images can be released. |
int |
controlledPoll(ControlledFragmentHandler fragmentHandler,
int fragmentLimit)
Poll in a controlled manner the
Images under the subscription for available message fragments. |
void |
forEachImage(Consumer<Image> consumer)
Iterate over the
Images for this subscription. |
boolean |
hasNoImages()
Has this subscription currently no
Images? |
Image |
imageAtIndex(int index)
Get the
Image at the given index from the images array. |
Image |
imageBySessionId(int sessionId)
Return the
Image associated with the given sessionId. |
int |
imageCount()
Count of
Images associated to this subscription. |
List<Image> |
images()
|
boolean |
isClosed()
Has this object been closed and should no longer be used?
|
boolean |
isConnected()
Is this subscription connected by having at least one open publication
Image. |
int |
poll(FragmentHandler fragmentHandler,
int fragmentLimit)
Poll the
Images under the subscription for available message fragments. |
long |
rawPoll(RawBlockHandler rawBlockHandler,
int blockLengthLimit)
Poll the
Images under the subscription for available message fragments in blocks. |
long |
registrationId()
Return the registration id used to register this Subscription with the media driver.
|
void |
removeDestination(String endpointChannel)
Remove a previously added destination from a multi-destination Subscription.
|
int |
streamId()
Stream identity for scoping within the channel media address.
|
String |
toString() |
UnavailableImageHandler |
unavailableImageHandler()
Callback used to indicate when an
Image goes unavailable under this Subscription. |
protected long p1
protected long p2
protected long p3
protected long p4
protected long p5
protected long p6
protected long p7
protected static final Image[] EMPTY_ARRAY
protected final long registrationId
protected final int streamId
protected int roundRobinIndex
protected volatile boolean isClosed
protected volatile Image[] images
protected final io.aeron.ClientConductor conductor
protected final String channel
protected final AvailableImageHandler availableImageHandler
protected final UnavailableImageHandler unavailableImageHandler
protected int channelStatusId
public String channel()
public int streamId()
public long registrationId()
public AvailableImageHandler availableImageHandler()
Image becomes available under this Subscription.Image becomes available under this Subscription.public UnavailableImageHandler unavailableImageHandler()
Image goes unavailable under this Subscription.Image goes unavailable under this Subscription.public int poll(FragmentHandler fragmentHandler, int fragmentLimit)
Images under the subscription for available message fragments.
Each fragment read will be a whole message if it is under MTU length. If larger than MTU then it will come as a series of fragments ordered within a session.
To assemble messages that span multiple fragments then use FragmentAssembler.
fragmentHandler - callback for handling each message fragment as it is read.fragmentLimit - number of message fragments to limit when polling across multiple Images.public int controlledPoll(ControlledFragmentHandler fragmentHandler, int fragmentLimit)
Images under the subscription for available message fragments.
Control is applied to fragments in the stream. If more fragments can be read on another stream
they will even if BREAK or ABORT is returned from the fragment handler.
Each fragment read will be a whole message if it is under MTU length. If larger than MTU then it will come as a series of fragments ordered within a session.
To assemble messages that span multiple fragments then use ControlledFragmentAssembler.
fragmentHandler - callback for handling each message fragment as it is read.fragmentLimit - number of message fragments to limit when polling across multiple Images.ControlledFragmentHandlerpublic long blockPoll(BlockHandler blockHandler, int blockLengthLimit)
Images under the subscription for available message fragments in blocks.
This method is useful for operations like bulk archiving and messaging indexing.
public long rawPoll(RawBlockHandler rawBlockHandler, int blockLengthLimit)
Images under the subscription for available message fragments in blocks.
This method is useful for operations like bulk archiving a stream to file.
public boolean isConnected()
Image.Image.public boolean hasNoImages()
Images?Images?public int imageCount()
Images associated to this subscription.Images associated to this subscription.public Image imageBySessionId(int sessionId)
Image associated with the given sessionId.sessionId - associated with the Image.public Image imageAtIndex(int index)
Image at the given index from the images array.index - in the arrayArrayIndexOutOfBoundsException - if the index is not valid.public void forEachImage(Consumer<Image> consumer)
Images for this subscription.consumer - to handle each Image.public void close()
Images can be released.
This method is idempotent.
close in interface AutoCloseablepublic boolean isClosed()
public long channelStatus()
The status will be ChannelEndpointStatus.ERRORED if a socket exception occurs on setup
and ChannelEndpointStatus.ACTIVE if all is well.
ChannelEndpointStatus with it being
ChannelEndpointStatus.NO_ID_ALLOCATED if the subscription is closed.ChannelEndpointStatuspublic void addDestination(String endpointChannel)
endpointChannel - for the destination to add.public void removeDestination(String endpointChannel)
endpointChannel - for the destination to remove.public long asyncAddDestination(String endpointChannel)
Errors will be delivered asynchronously to the Aeron.Context.errorHandler(). Completion can be
tracked by passing the returned correlation id to Aeron.isCommandActive(long).
endpointChannel - for the destination to add.public long asyncRemoveDestination(String endpointChannel)
Errors will be delivered asynchronously to the Aeron.Context.errorHandler(). Completion can be
tracked by passing the returned correlation id to Aeron.isCommandActive(long).
endpointChannel - for the destination to remove.Copyright © 2014-2019 Real Logic Ltd. All Rights Reserved.