Skip to content

Working with Recordings

There are a number of utility functions that help reduce errors when interacting with Aeron Archive. Some commonly used ones are described below.

Getting Recording information

Once you have the specific recording ID for the archive recording you're wanting to interact with, you can perform additional actions on the recording.

List Recordings

This lists all the recordings, up to the given count, on the connected instance Archive. Data is returned via a RecordingDescriptorConsumer.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
final RecordingDescriptorConsumer consumer =
    (controlSessionId, correlationId, recordingId,
    startTimestamp, stopTimestamp, startPosition,
    stopPosition, initialTermId, segmentFileLength,
    termBufferLength, mtuLength, sessionId,
    streamId, strippedChannel, originalChannel,
    sourceIdentity) -> 
    {
        ...
    };

final int countOfItemsReturned = archive.listRecordings(fromRecordingId, recordCount, consumer);
...

The recordingId, stream and channel data returned to the RecordingDescriptorConsumer should provide most of what typical applications need for working with and identifying a given recording.

Notes:

  • fromRecordingId and recordCount can be used to paginate the recording data. For example, the first data set could be from 0L, count 100, second would be from 101L, count 100 etc.
  • sourceIdentity returns either aeron:udp or aeron:ipc.

List Recordings for URI

This lists all the recordings, up to the given count, on the connected instance Archive which contain the provided text in their channel and which match the provided stream. As before, data is returned via a RecordingDescriptorConsumer.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
final RecordingDescriptorConsumer consumer =
    (controlSessionId, correlationId, recordingId,
    startTimestamp, stopTimestamp, startPosition,
    stopPosition, initialTermId, segmentFileLength,
    termBufferLength, mtuLength, sessionId,
    streamId, strippedChannel, originalChannel,
    sourceIdentity) -> 
    {
        ...
    };

final int countOfItemsReturned = archive.listRecordingsForUri(fromRecordingId, recordCount, channel, stream, consumer);
...

Getting Position information

Recording Position

final long recordingPosition = archive.getRecordingPosition(recordingId);

This method returns the current position (at time of query) of the recording. If the result return is -1 (aka NULL_POSITION), then the recording is present on the remote side, but not active.

Start and Stop Position

final long startPosition = archive.getStartPosition(recordingId);
final long stopPosition = archive.getStopPosition(recordingId);

This method returns the start position and stop position (at time of query) of the recording. If the stop position is -1 (aka NULL_POSITION), then the recording is still active and has no defined stop position.

Using these positions with Replay

These three positions help safely perform replay operations:

  • if the archive is active (stop position = NULL_POSITION), but the position is smaller than your start position, then this archive will not yet (or potentially ever) be able to replay from the requested position
  • if the archive is not active (recording position = NULL_POSITION), then there is no point requesting a replay with a start position at or greater than stop position. If you do, Aeron Archive will return an error to the ErrorHandler.

Warning

If you're getting position information before starting a replay, and you have already opened a Subscription but then realize it cannot successfully continue due to data returned by the position helpers, remember to close the Subscription so that you do not leak Subscriptions and counters.

Checking for Errors

Poll for Error Response

The synchronous pollForErrorResponse is useful if you want to check connectivity or for an error without throwing an exception following a specific request, such as replay or replicate.

final var errorMessage = archive.pollForErrorResponse();

This will return null if there was no error, or not connected if the Aeron Archive client is no longer connected to the Archive, or another string message if there was an error.

Check for Error Response

This works much like pollForErrorResponse, but will call the ErrorHandler or raise an exception if the ErrorHandler is not set.