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 |
|
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
andrecordCount
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 eitheraeron:udp
oraeron: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 |
|
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 theErrorHandler
.
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.