io.aeron

Class Subscription

java.lang.Object

io.aeron.Subscription

All Implemented Interfaces:

java.lang.AutoCloseable

public class Subscription
extends java.lang.Object
implements java.lang.AutoCloseable

Aeron Subscriber API for receiving a reconstructed Image for a stream of messages from publishers on a given channel and streamId pair. Subscribers 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 Subscriber for new messages. Subscriptions are not threadsafe and should not be shared between subscribers.

See Also:

FragmentAssembler

Method Summary

Modifier and Type	Method and Description
long	blockPoll(BlockHandler blockHandler, int blockLengthLimit) Poll the Images under the subscription for available message fragments in blocks.
java.lang.String	channel() Media address for delivery to the channel.
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(java.util.function.Consumer<Image> imageConsumer) Iterate over the Images for this subscription.
Image	imageBySessionId(int sessionId) Return the Image associated with the given sessionId.
int	imageCount() Count of images connected to this subscription.
java.util.List<Image>	images() Get a List of active Images that match this subscription.
boolean	isClosed() Has this object been closed and should no longer be used?
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 Publication with the media driver.
int	streamId() Stream identity for scoping within the channel media address.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

channel

public java.lang.String channel()

Media address for delivery to the channel.

Returns:

Media address for delivery to the channel.

streamId

public int streamId()

Stream identity for scoping within the channel media address.

Returns:

Stream identity for scoping within the channel media address.

poll

public int poll(FragmentHandler fragmentHandler,
                int fragmentLimit)

Poll the 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.

Parameters:

fragmentHandler - callback for handling each message fragment as it is read.

fragmentLimit - number of message fragments to limit for the poll operation across multiple Images.

Returns:

the number of fragments received

controlledPoll

public int controlledPoll(ControlledFragmentHandler fragmentHandler,
                          int fragmentLimit)

Poll in a controlled manner the 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.

Parameters:

fragmentHandler - callback for handling each message fragment as it is read.

fragmentLimit - number of message fragments to limit for the poll operation across multiple Images.

Returns:

the number of fragments received

See Also:

ControlledFragmentHandler

blockPoll

public long blockPoll(BlockHandler blockHandler,
                      int blockLengthLimit)

Poll the Images under the subscription for available message fragments in blocks. This method is useful for operations like bulk archiving and messaging indexing.

Parameters:

blockHandler - to receive a block of fragments from each Image.

blockLengthLimit - for each Image polled.

Returns:

the number of bytes consumed.

rawPoll

public long rawPoll(RawBlockHandler rawBlockHandler,
                    int blockLengthLimit)

Poll the Images under the subscription for available message fragments in blocks. This method is useful for operations like bulk archiving a stream to file.

Parameters:

rawBlockHandler - to receive a block of fragments from each Image.

blockLengthLimit - for each Image polled.

Returns:

the number of bytes consumed.

imageCount

public int imageCount()

Count of images connected to this subscription.

Returns:

count of images connected to this subscription.

imageBySessionId

public Image imageBySessionId(int sessionId)

Return the Image associated with the given sessionId.

Parameters:

sessionId - associated with the Image.

Returns:

Image associated with the given sessionId or null if no Image exist.

images

public java.util.List<Image> images()

Get a List of active Images that match this subscription.

Returns:

a List of active Images that match this subscription.

forEachImage

public void forEachImage(java.util.function.Consumer<Image> imageConsumer)

Iterate over the Images for this subscription.

Parameters:

imageConsumer - to handle each Image.

close

public void close()

Close the Subscription so that associated Images can be released. This method is idempotent.

Specified by:

close in interface java.lang.AutoCloseable

isClosed

public boolean isClosed()

Has this object been closed and should no longer be used?

Returns:

true if it has been closed otherwise false.

registrationId

public long registrationId()

Return the registration id used to register this Publication with the media driver.

Returns:

registration id