Subscription (Aeron Message Transport)

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. 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)

Field Summary

Fields
Modifier and Type	Field and Description
`protected AvailableImageHandler`	`availableImageHandler`
`protected java.lang.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`	`p10`
`protected long`	`p11`
`protected long`	`p12`
`protected long`	`p13`
`protected long`	`p14`
`protected long`	`p15`
`protected long`	`p16`
`protected long`	`p17`
`protected long`	`p18`
`protected long`	`p19`
`protected long`	`p2`
`protected long`	`p20`
`protected long`	`p21`
`protected long`	`p22`
`protected long`	`p23`
`protected long`	`p24`
`protected long`	`p25`
`protected long`	`p26`
`protected long`	`p27`
`protected long`	`p28`
`protected long`	`p29`
`protected long`	`p3`
`protected long`	`p30`
`protected long`	`p4`
`protected long`	`p5`
`protected long`	`p6`
`protected long`	`p7`
`protected long`	`p8`
`protected long`	`p9`
`protected long`	`registrationId`
`protected int`	`roundRobinIndex`
`protected int`	`streamId`
`protected UnavailableImageHandler`	`unavailableImageHandler`

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`void`	`addDestination(java.lang.String endpointChannel)` Add a destination manually to 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.
`java.lang.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 `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(java.util.function.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.
`java.util.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`.
`int`	`poll(FragmentHandler fragmentHandler, int fragmentLimit)` Poll the `Image`s under the subscription for available message fragments.
`int`	`pollEndOfStreams(EndOfStreamHandler endOfStreamHandler)` Deprecated.
`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(java.lang.String endpointChannel)` Remove a previously added destination from a multi-destination Subscription.
`int`	`streamId()` Stream identity for scoping within the channel media address.
`java.lang.String`	`toString()`
`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

- Field Detail
  - p16
```
protected long p16
```
  - p17
```
protected long p17
```
  - p18
```
protected long p18
```
  - p19
```
protected long p19
```
  - p20
```
protected long p20
```
  - p21
```
protected long p21
```
  - p22
```
protected long p22
```
  - p23
```
protected long p23
```
  - p24
```
protected long p24
```
  - p25
```
protected long p25
```
  - p26
```
protected long p26
```
  - p27
```
protected long p27
```
  - p28
```
protected long p28
```
  - p29
```
protected long p29
```
  - p30
```
protected long p30
```
  - EMPTY_ARRAY
```
protected static final Image[] EMPTY_ARRAY
```
  - registrationId
```
protected final long registrationId
```
  - roundRobinIndex
```
protected int roundRobinIndex
```
  - streamId
```
protected final int streamId
```
  - isClosed
```
protected volatile boolean isClosed
```
  - images
```
protected volatile Image[] images
```
  - conductor
```
protected final io.aeron.ClientConductor conductor
```
  - channel
```
protected final java.lang.String channel
```
  - availableImageHandler
```
protected final AvailableImageHandler availableImageHandler
```
  - unavailableImageHandler
```
protected final UnavailableImageHandler unavailableImageHandler
```
  - channelStatusId
```
protected int channelStatusId
```
  - p1
```
protected long p1
```
  - p2
```
protected long p2
```
  - p3
```
protected long p3
```
  - p4
```
protected long p4
```
  - p5
```
protected long p5
```
  - p6
```
protected long p6
```
  - p7
```
protected long p7
```
  - p8
```
protected long p8
```
  - p9
```
protected long p9
```
  - p10
```
protected long p10
```
  - p11
```
protected long p11
```
  - p12
```
protected long p12
```
  - p13
```
protected long p13
```
  - p14
```
protected long p14
```
  - p15
```
protected long p15
```
- 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.
  - 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.
  - pollEndOfStreams
```
@Deprecated
public int pollEndOfStreams(EndOfStreamHandler endOfStreamHandler)
```
    Deprecated.
    
    Poll the Images under the subscription for having reached End of Stream (EOS). This method will miss Images that have gone unavailable between calls unless using the Aeron.conductorAgentInvoker().
    
    Parameters:
    
    endOfStreamHandler - callback for handling end of stream indication.
    
    Returns:
    
    number of Image that have reached End of Stream.
  - 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.
  - 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:
    
    java.lang.ArrayIndexOutOfBoundsException - if the index is not valid.
  - images
```
public java.util.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(java.util.function.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 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.
  - 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
  - addDestination
```
public void addDestination(java.lang.String endpointChannel)
```
    Add a destination manually to a multi-destination Subscription.
    
    Parameters:
    
    endpointChannel - for the destination to add
  - removeDestination
```
public void removeDestination(java.lang.String endpointChannel)
```
    Remove a previously added destination from a multi-destination Subscription.
    
    Parameters:
    
    endpointChannel - for the destination to remove
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object

Class Subscription

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

p16

p17

p18

p19

p20

p21

p22

p23

p24

p25

p26

p27

p28

p29

p30

EMPTY_ARRAY

registrationId

roundRobinIndex

streamId

isClosed

images

conductor

channel

availableImageHandler

unavailableImageHandler

channelStatusId

p1

p2

p3

p4

p5

p6

p7

p8

p9

p10

p11

p12

p13

p14

p15

Method Detail

channel

streamId

registrationId

availableImageHandler

unavailableImageHandler

pollEndOfStreams

poll

controlledPoll

blockPoll

rawPoll

isConnected

hasNoImages

imageCount

imageBySessionId

imageAtIndex

images

forEachImage

close

isClosed

channelStatus

addDestination

removeDestination

toString