Subscription (Aeron Message Transport)

java.lang.Object
- io.aeron.Subscription

All Implemented Interfaces:

AutoCloseable
```
public final class Subscription
extends Object
implements AutoCloseable
```
Aeron Subscriber API for receiving a reconstructed Image for a stream of messages from publishers on a given channel and streamId pair, i.e. a Publication. 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.

See Also:

FragmentAssembler, ControlledFragmentHandler, Aeron.addSubscription(String, int), Aeron.addSubscription(String, int, AvailableImageHandler, UnavailableImageHandler)

Method Summary

All Methods Instance Methods Concrete Methods
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 `Image`s 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.
`int`	`channelStatusId()` Get the counter used to represent the channel status for this Subscription.
`void`	`close()` Close the Subscription so that associated `Image`s can be released.
`int`	`controlledPoll(ControlledFragmentHandler fragmentHandler, int fragmentLimit)` Poll in a controlled manner the `Image`s under the subscription for available message fragments.
`void`	`forEachImage(Consumer<Image> consumer)` Iterate over the `Image`s for this subscription.
`boolean`	`hasNoImages()` Has this subscription currently no `Image`s?
`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 `Image`s associated to this subscription.
`List<Image>`	`images()` Get a `List` of active `Image`s that match this subscription.
`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`.
`List<String>`	`localSocketAddresses()` Fetches the local socket addresses for this subscription.
`int`	`poll(FragmentHandler fragmentHandler, int fragmentLimit)` Poll the `Image`s under the subscription for available message fragments.
`long`	`rawPoll(RawBlockHandler rawBlockHandler, int blockLengthLimit)` Poll the `Image`s 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.
`String`	`resolvedEndpoint()` Find the resolved endpoint for the channel.
`int`	`streamId()` Stream identity for scoping within the channel media address.
`String`	`toString()`
`String`	`tryResolveChannelEndpointPort()` Resolve channel endpoint and replace it with the port from the ephemeral range when 0 was provided.
`UnavailableImageHandler`	`unavailableImageHandler()` Callback used to indicate when an `Image` goes unavailable under this `Subscription`.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Method Detail
  - channel
```
public 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.
  - registrationId
```
public long registrationId()
```
    Return the registration id used to register this Subscription with the media driver.
    
    Returns:
    
    registration id
  - availableImageHandler
```
public AvailableImageHandler availableImageHandler()
```
    Callback used to indicate when an Image becomes available under this Subscription.
    
    Returns:
    
    callback used to indicate when an Image becomes available under this Subscription.
  - unavailableImageHandler
```
public UnavailableImageHandler unavailableImageHandler()
```
    Callback used to indicate when an Image goes unavailable under this Subscription.
    
    Returns:
    
    Callback used to indicate when an Image goes unavailable under this Subscription.
  - 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 when polling 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 when polling 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.
  - isConnected
```
public boolean isConnected()
```
    Is this subscription connected by having at least one open publication Image.
    
    Returns:
    
    true if this subscription connected by having at least one open publication Image.
  - hasNoImages
```
public boolean hasNoImages()
```
    Has this subscription currently no Images?
    
    Returns:
    
    has subscription currently no Images?
  - imageCount
```
public int imageCount()
```
    Count of Images associated to this subscription.
    
    Returns:
    
    count of Images associated 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.
  - imageAtIndex
```
public Image imageAtIndex(int index)
```
    Get the Image at the given index from the images array.
    
    Parameters:
    
    index - in the array
    
    Returns:
    
    image at given index
    
    Throws:
    
    ArrayIndexOutOfBoundsException - if the index is not valid.
  - images
```
public List<Image> images()
```
    Get a List of active Images that match this subscription.
    
    Returns:
    
    an unmodifiable List of active Images that match this subscription.
  - forEachImage
```
public void forEachImage(Consumer<Image> consumer)
```
    Iterate over the Images for this subscription.
    
    Parameters:
    
    consumer - 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 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.
  - channelStatus
```
public long channelStatus()
```
    Get the status of the media channel for this Subscription.
    The status will be ChannelEndpointStatus.ERRORED if a socket exception occurs on setup and ChannelEndpointStatus.ACTIVE if all is well.
    
    Returns:
    
    status for the channel as one of the constants from ChannelEndpointStatus with it being ChannelEndpointStatus.NO_ID_ALLOCATED if the subscription is closed.
    
    See Also:
    
    ChannelEndpointStatus
  - channelStatusId
```
public int channelStatusId()
```
    Get the counter used to represent the channel status for this Subscription.
    
    Returns:
    
    the counter used to represent the channel status for this Subscription.
  - localSocketAddresses
```
public List<String> localSocketAddresses()
```
    Fetches the local socket addresses for this subscription. If the channel is not ChannelEndpointStatus.ACTIVE, then this will return an empty list.
    The format is as follows:
    
    IPv4: ip address:port
    IPv6: [ip6 address]:port
    
    This is to match the formatting used in the Aeron URI.
    
    Returns:
    
    List of local socket addresses for this subscription.
    
    See Also:
    
    channelStatus()
  - addDestination
```
public void addDestination(String endpointChannel)
```
    Add a destination manually to a multi-destination Subscription.
    
    Parameters:
    
    endpointChannel - for the destination to add.
  - removeDestination
```
public void removeDestination(String endpointChannel)
```
    Remove a previously added destination from a multi-destination Subscription.
    
    Parameters:
    
    endpointChannel - for the destination to remove.
  - asyncAddDestination
```
public long asyncAddDestination(String endpointChannel)
```
    Asynchronously add a destination manually to a multi-destination Subscription.
    Errors will be delivered asynchronously to the Aeron.Context.errorHandler(). Completion can be tracked by passing the returned correlation id to Aeron.isCommandActive(long).
    
    Parameters:
    
    endpointChannel - for the destination to add.
    
    Returns:
    
    the correlationId for the command.
  - asyncRemoveDestination
```
public long asyncRemoveDestination(String endpointChannel)
```
    Asynchronously remove a previously added destination from a multi-destination Subscription.
    Errors will be delivered asynchronously to the Aeron.Context.errorHandler(). Completion can be tracked by passing the returned correlation id to Aeron.isCommandActive(long).
    
    Parameters:
    
    endpointChannel - for the destination to remove.
    
    Returns:
    
    the correlationId for the command.
  - tryResolveChannelEndpointPort
```
public String tryResolveChannelEndpointPort()
```
    Resolve channel endpoint and replace it with the port from the ephemeral range when 0 was provided. If there are no addresses, or if there is more than one, returned from localSocketAddresses() then the original channel() is returned.
    If the channel is not ChannelEndpointStatus.ACTIVE, then null will be returned.
    
    Returns:
    
    channel URI string with an endpoint being resolved to the allocated port.
    
    See Also:
    
    channelStatus(), localSocketAddresses()
  - resolvedEndpoint
```
public String resolvedEndpoint()
```
    Find the resolved endpoint for the channel. This may be null of MDS is used and no destination is yet added. The result will similar to taking the first element returned from localSocketAddresses(). If more than one destination is added then the first found is returned.
    If the channel is not ChannelEndpointStatus.ACTIVE, then null will be returned.
    
    Returns:
    
    The resolved endpoint or null if not found.
    
    See Also:
    
    channelStatus(), localSocketAddresses()
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class Subscription

Method Summary

Methods inherited from class java.lang.Object

Method Detail

channel

streamId

registrationId

availableImageHandler

unavailableImageHandler

poll

controlledPoll

blockPoll

rawPoll

isConnected

hasNoImages

imageCount

imageBySessionId

imageAtIndex

images

forEachImage

close

isClosed

channelStatus

channelStatusId

localSocketAddresses

addDestination

removeDestination

asyncAddDestination

asyncRemoveDestination

tryResolveChannelEndpointPort

resolvedEndpoint

toString