Image (Aeron Message Transport)

java.lang.Object
- io.aeron.Image

```
public final class Image
extends Object
```
Represents a replicated Publication from a which matches a Subscription. Each Image identifies a source Publication by sessionId().
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 Image for new messages.
Note:Images are not threadsafe and should not be shared between subscribers.

Constructor Summary

Constructors
Constructor and Description
`Image(Subscription subscription, int sessionId, Position subscriberPosition, LogBuffers logBuffers, ErrorHandler errorHandler, String sourceIdentity, long correlationId)` Construct a new image over a log to represent a stream of messages from a `Publication`.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`int`	`activeTransportCount()` Count of observed active transports within the image liveness timeout.
`int`	`blockPoll(BlockHandler handler, int blockLengthLimit)` Poll for new messages in a stream.
`int`	`boundedControlledPoll(ControlledFragmentHandler handler, long limitPosition, int fragmentLimit)` Poll for new messages in a stream.
`int`	`boundedPoll(FragmentHandler handler, long limitPosition, int fragmentLimit)` Poll for new messages in a stream.
`long`	`controlledPeek(long initialPosition, ControlledFragmentHandler handler, long limitPosition)` Peek for new messages in a stream by scanning forward from an initial position.
`int`	`controlledPoll(ControlledFragmentHandler handler, int fragmentLimit)` Poll for new messages in a stream.
`long`	`correlationId()` The correlationId for identification of the image with the media driver.
`FileChannel`	`fileChannel()` The `FileChannel` to the raw log of the Image.
`int`	`initialTermId()` The initial term at which the stream started for this session.
`boolean`	`isClosed()` Has this object been closed and should no longer be used?
`boolean`	`isEndOfStream()` Is the current consumed position at the end of the stream?
`long`	`joinPosition()` Get the position the subscriber joined this stream at.
`int`	`mtuLength()` The length in bytes of the MTU (Maximum Transmission Unit) the Sender used for the datagram.
`int`	`poll(FragmentHandler fragmentHandler, int fragmentLimit)` Poll for new messages in a stream.
`long`	`position()` The position this `Image` has been consumed to by the subscriber.
`void`	`position(long newPosition)` Set the subscriber position for this `Image` to indicate where it has been consumed to.
`int`	`positionBitsToShift()` Number of bits to right shift a position to get a term count for how far the stream has progressed.
`int`	`rawPoll(RawBlockHandler handler, int blockLengthLimit)` Poll for new messages in a stream.
`int`	`sessionId()` The sessionId for the steam of messages.
`String`	`sourceIdentity()` The source identity of the sending publisher as an abstract concept appropriate for the media.
`int`	`subscriberPositionId()` The counter id for the subscriber position counter.
`Subscription`	`subscription()` Get the `Subscription` to which this `Image` belongs.
`int`	`termBufferLength()` Get the length in bytes for each term partition in the log buffer.
`String`	`toString()`

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

- Constructor Detail
  - Image
```
public Image(Subscription subscription,
             int sessionId,
             Position subscriberPosition,
             LogBuffers logBuffers,
             ErrorHandler errorHandler,
             String sourceIdentity,
             long correlationId)
```
    Construct a new image over a log to represent a stream of messages from a Publication.
    
    Parameters:
    
    subscription - to which this Image belongs.
    
    sessionId - of the stream of messages.
    
    subscriberPosition - for indicating the position of the subscriber in the stream.
    
    logBuffers - containing the stream of messages.
    
    errorHandler - to be called if an error occurs when polling for messages.
    
    sourceIdentity - of the source sending the stream of messages.
    
    correlationId - of the request to the media driver.
- Method Detail
  - positionBitsToShift
```
public int positionBitsToShift()
```
    Number of bits to right shift a position to get a term count for how far the stream has progressed.
    
    Returns:
    
    of bits to right shift a position to get a term count for how far the stream has progressed.
  - termBufferLength
```
public int termBufferLength()
```
    Get the length in bytes for each term partition in the log buffer.
    
    Returns:
    
    the length in bytes for each term partition in the log buffer.
  - sessionId
```
public int sessionId()
```
    The sessionId for the steam of messages. Sessions are unique within a Subscription and unique across all Publications from a sourceIdentity().
    
    Returns:
    
    the sessionId for the steam of messages.
  - sourceIdentity
```
public String sourceIdentity()
```
    The source identity of the sending publisher as an abstract concept appropriate for the media.
    
    Returns:
    
    source identity of the sending publisher as an abstract concept appropriate for the media.
  - mtuLength
```
public int mtuLength()
```
    The length in bytes of the MTU (Maximum Transmission Unit) the Sender used for the datagram.
    
    Returns:
    
    length in bytes of the MTU (Maximum Transmission Unit) the Sender used for the datagram.
  - initialTermId
```
public int initialTermId()
```
    The initial term at which the stream started for this session.
    
    Returns:
    
    the initial term id.
  - correlationId
```
public long correlationId()
```
    The correlationId for identification of the image with the media driver.
    
    Returns:
    
    the correlationId for identification of the image with the media driver.
  - subscription
```
public Subscription subscription()
```
    Get the Subscription to which this Image belongs.
    
    Returns:
    
    the Subscription to which this Image belongs.
  - isClosed
```
public boolean isClosed()
```
    Has this object been closed and should no longer be used?
    
    Returns:
    
    true if it has been closed otherwise false.
  - joinPosition
```
public long joinPosition()
```
    Get the position the subscriber joined this stream at.
    
    Returns:
    
    the position the subscriber joined this stream at.
  - position
```
public long position()
```
    The position this Image has been consumed to by the subscriber.
    
    Returns:
    
    the position this Image has been consumed to by the subscriber.
  - position
```
public void position(long newPosition)
```
    Set the subscriber position for this Image to indicate where it has been consumed to.
    
    Parameters:
    
    newPosition - for the consumption point.
  - subscriberPositionId
```
public int subscriberPositionId()
```
    The counter id for the subscriber position counter.
    
    Returns:
    
    the id for the subscriber position counter.
  - isEndOfStream
```
public boolean isEndOfStream()
```
    Is the current consumed position at the end of the stream?
    
    Returns:
    
    true if at the end of the stream or false if not.
  - activeTransportCount
```
public int activeTransportCount()
```
    Count of observed active transports within the image liveness timeout. If the image is closed, then this is 0. This may also be 0 if no actual datagrams have arrived. IPC Images also will be 0.
    
    Returns:
    
    count of active transports - 0 if Image is closed, no datagrams yet, or IPC.
  - fileChannel
```
public FileChannel fileChannel()
```
    The FileChannel to the raw log of the Image.
    
    Returns:
    
    the FileChannel to the raw log of the Image.
  - poll
```
public int poll(FragmentHandler fragmentHandler,
                int fragmentLimit)
```
    Poll for new messages in a stream. If new messages are found beyond the last consumed position then they will be delivered to the FragmentHandler up to a limited number of fragments as specified.
    Use a FragmentAssembler to assemble messages which span multiple fragments.
    
    Parameters:
    
    fragmentHandler - to which message fragments are delivered.
    
    fragmentLimit - for the number of fragments to be consumed during one polling operation.
    
    Returns:
    
    the number of fragments that have been consumed.
    
    See Also:
    
    FragmentAssembler, ImageFragmentAssembler
  - controlledPoll
```
public int controlledPoll(ControlledFragmentHandler handler,
                          int fragmentLimit)
```
    Poll for new messages in a stream. If new messages are found beyond the last consumed position then they will be delivered to the ControlledFragmentHandler up to a limited number of fragments as specified.
    Use a ControlledFragmentAssembler to assemble messages which span multiple fragments.
    
    Parameters:
    
    handler - to which message fragments are delivered.
    
    fragmentLimit - for the number of fragments to be consumed during one polling operation.
    
    Returns:
    
    the number of fragments that have been consumed.
    
    See Also:
    
    ControlledFragmentAssembler, ImageControlledFragmentAssembler
  - boundedPoll
```
public int boundedPoll(FragmentHandler handler,
                       long limitPosition,
                       int fragmentLimit)
```
    Poll for new messages in a stream. If new messages are found beyond the last consumed position then they will be delivered to the FragmentHandler up to a limited number of fragments as specified or the maximum position specified.
    Use a FragmentAssembler to assemble messages which span multiple fragments.
    
    Parameters:
    
    handler - to which message fragments are delivered.
    
    limitPosition - to consume messages up to.
    
    fragmentLimit - for the number of fragments to be consumed during one polling operation.
    
    Returns:
    
    the number of fragments that have been consumed.
    
    See Also:
    
    FragmentAssembler, ImageFragmentAssembler
  - boundedControlledPoll
```
public int boundedControlledPoll(ControlledFragmentHandler handler,
                                 long limitPosition,
                                 int fragmentLimit)
```
    Poll for new messages in a stream. If new messages are found beyond the last consumed position then they will be delivered to the ControlledFragmentHandler up to a limited number of fragments as specified or the maximum position specified.
    Use a ControlledFragmentAssembler to assemble messages which span multiple fragments.
    
    Parameters:
    
    handler - to which message fragments are delivered.
    
    limitPosition - to consume messages up to.
    
    fragmentLimit - for the number of fragments to be consumed during one polling operation.
    
    Returns:
    
    the number of fragments that have been consumed.
    
    See Also:
    
    ControlledFragmentAssembler, ImageControlledFragmentAssembler
  - controlledPeek
```
public long controlledPeek(long initialPosition,
                           ControlledFragmentHandler handler,
                           long limitPosition)
```
    Peek for new messages in a stream by scanning forward from an initial position. If new messages are found then they will be delivered to the ControlledFragmentHandler up to a limited position.
    Use a ControlledFragmentAssembler to assemble messages which span multiple fragments. Scans must also start at the beginning of a message so that the assembler is reset.
    
    Parameters:
    
    initialPosition - from which to peek forward.
    
    handler - to which message fragments are delivered.
    
    limitPosition - up to which can be scanned.
    
    Returns:
    
    the resulting position after the scan terminates which is a complete message.
    
    See Also:
    
    ControlledFragmentAssembler, ImageControlledFragmentAssembler
  - blockPoll
```
public int blockPoll(BlockHandler handler,
                     int blockLengthLimit)
```
    Poll for new messages in a stream. If new messages are found beyond the last consumed position then they will be delivered to the BlockHandler up to a limited number of bytes.
    A scan will terminate if a padding frame is encountered. If first frame in a scan is padding then a block for the padding is notified. If the padding comes after the first frame in a scan then the scan terminates at the offset the padding frame begins. Padding frames are delivered singularly in a block.
    Padding frames may be for a greater range than the limit offset but only the header needs to be valid so relevant length of the frame is DataHeaderFlyweight.HEADER_LENGTH.
    
    Parameters:
    
    handler - to which block is delivered.
    
    blockLengthLimit - up to which a block may be in length.
    
    Returns:
    
    the number of bytes that have been consumed.
  - rawPoll
```
public int rawPoll(RawBlockHandler handler,
                   int blockLengthLimit)
```
    Poll for new messages in a stream. If new messages are found beyond the last consumed position then they will be delivered to the RawBlockHandler up to a limited number of bytes.
    This method is useful for operations like bulk archiving a stream to file.
    A scan will terminate if a padding frame is encountered. If first frame in a scan is padding then a block for the padding is notified. If the padding comes after the first frame in a scan then the scan terminates at the offset the padding frame begins. Padding frames are delivered singularly in a block.
    Padding frames may be for a greater range than the limit offset but only the header needs to be valid so relevant length of the frame is DataHeaderFlyweight.HEADER_LENGTH.
    
    Parameters:
    
    handler - to which block is delivered.
    
    blockLengthLimit - up to which a block may be in length.
    
    Returns:
    
    the number of bytes that have been consumed.
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class Image

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Image

Method Detail

positionBitsToShift

termBufferLength

sessionId

sourceIdentity

mtuLength

initialTermId

correlationId

subscription

isClosed

joinPosition

position

position

subscriberPositionId

isEndOfStream

activeTransportCount

fileChannel

poll

controlledPoll

boundedPoll

boundedControlledPoll

controlledPeek

blockPoll

rawPoll

toString