io.aeron

Class Aeron

java.lang.Object

io.aeron.Aeron

All Implemented Interfaces:

java.lang.AutoCloseable

public final class Aeron
extends java.lang.Object
implements java.lang.AutoCloseable

Aeron entry point for communicating to the Media Driver for creating Publications and Subscriptions. Use an Aeron.Context to configure the Aeron object. A client application requires only one Aeron object per Media Driver.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Aeron.Context This class provides configuration for the Aeron class via the connect(Aeron.Context) method and its overloads.

Field Summary

Fields

Modifier and Type	Field and Description
static org.agrona.ErrorHandler	DEFAULT_ERROR_HANDLER The Default handler for Aeron runtime exceptions.
static long	IDLE_SLEEP_NS Duration in nanoseconds for which the client conductor will sleep between duty cycles.
static long	INTER_SERVICE_TIMEOUT_NS Default interval that if exceeded between duty cycles the conductor will consider itself a zombie and suicide.
static long	KEEPALIVE_INTERVAL_NS Default interval between sending keepalive control messages to the driver.
static long	PUBLICATION_CONNECTION_TIMEOUT_MS Timeout after which if no status messages have been received then a publication is considered not connected.

Method Summary

Modifier and Type	Method and Description
ExclusivePublication	addExclusivePublication(java.lang.String channel, int streamId) Add an ExclusivePublication for publishing messages to subscribers from a single thread.
Publication	addPublication(java.lang.String channel, int streamId) Add a Publication for publishing messages to subscribers.
Subscription	addSubscription(java.lang.String channel, int streamId) Add a new Subscription for subscribing to messages from publishers.
Subscription	addSubscription(java.lang.String channel, int streamId, AvailableImageHandler availableImageHandler, UnavailableImageHandler unavailableImageHandler) Add a new Subscription for subscribing to messages from publishers.
void	close() Clean up and release all Aeron internal resources and shutdown threads.
static Aeron	connect() Create an Aeron instance and connect to the media driver with a default Aeron.Context.
static Aeron	connect(Aeron.Context ctx) Create an Aeron instance and connect to the media driver.
org.agrona.concurrent.status.CountersReader	countersReader() Create and return a CountersReader for the Aeron media driver counters.
long	nextCorrelationId() Generate the next correlation id that is unique for the connected Media Driver.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_ERROR_HANDLER

public static final org.agrona.ErrorHandler DEFAULT_ERROR_HANDLER

The Default handler for Aeron runtime exceptions. When a DriverTimeoutException is encountered, this handler will exit the program. The error handler can be overridden by supplying an Aeron.Context with a custom handler.

See Also:

Aeron.Context.errorHandler(ErrorHandler)

IDLE_SLEEP_NS

public static final long IDLE_SLEEP_NS

Duration in nanoseconds for which the client conductor will sleep between duty cycles.

KEEPALIVE_INTERVAL_NS

public static final long KEEPALIVE_INTERVAL_NS

Default interval between sending keepalive control messages to the driver.

INTER_SERVICE_TIMEOUT_NS

public static final long INTER_SERVICE_TIMEOUT_NS

Default interval that if exceeded between duty cycles the conductor will consider itself a zombie and suicide.

PUBLICATION_CONNECTION_TIMEOUT_MS

public static final long PUBLICATION_CONNECTION_TIMEOUT_MS

Timeout after which if no status messages have been received then a publication is considered not connected.

Method Detail

connect

public static Aeron connect()

Create an Aeron instance and connect to the media driver with a default Aeron.Context. Threads required for interacting with the media driver are created and managed within the Aeron instance.

Returns:

the new Aeron instance connected to the Media Driver.

connect

public static Aeron connect(Aeron.Context ctx)

Create an Aeron instance and connect to the media driver. Threads required for interacting with the media driver are created and managed within the Aeron instance. If an exception occurs while trying to establish a connection then the Aeron.Context.close() method will be called on the passed context.

Parameters:

ctx - for configuration of the client.

Returns:

the new Aeron instance connected to the Media Driver.

close

public void close()

Clean up and release all Aeron internal resources and shutdown threads.

Specified by:

close in interface java.lang.AutoCloseable

addPublication

public Publication addPublication(java.lang.String channel,
                                  int streamId)

Add a Publication for publishing messages to subscribers.

Parameters:

channel - for receiving the messages known to the media layer.

streamId - within the channel scope.

Returns:

the new Publication.

addExclusivePublication

public ExclusivePublication addExclusivePublication(java.lang.String channel,
                                                    int streamId)

Add an ExclusivePublication for publishing messages to subscribers from a single thread.

Parameters:

channel - for receiving the messages known to the media layer.

streamId - within the channel scope.

Returns:

the new Publication.

addSubscription

public Subscription addSubscription(java.lang.String channel,
                                    int streamId)

Add a new Subscription for subscribing to messages from publishers. The method will set up the Subscription to use the Aeron.Context.availableImageHandler(AvailableImageHandler) and Aeron.Context.unavailableImageHandler(UnavailableImageHandler) from the Aeron.Context.

Parameters:

channel - for receiving the messages known to the media layer.

streamId - within the channel scope.

Returns:

the Subscription for the channel and streamId pair.

addSubscription

public Subscription addSubscription(java.lang.String channel,
                                    int streamId,
                                    AvailableImageHandler availableImageHandler,
                                    UnavailableImageHandler unavailableImageHandler)

Add a new Subscription for subscribing to messages from publishers. This method will override the default handlers from the Aeron.Context, i.e. Aeron.Context.availableImageHandler(AvailableImageHandler) and Aeron.Context.unavailableImageHandler(UnavailableImageHandler). Null values are valid and will result in no action being taken.

Parameters:

channel - for receiving the messages known to the media layer.

streamId - within the channel scope.

availableImageHandler - called when Images become available for consumption. Null is valid if no action is to be taken.

unavailableImageHandler - called when Images go unavailable for consumption. Null is valid if no action is to be taken.

Returns:

the Subscription for the channel and streamId pair.

nextCorrelationId

public long nextCorrelationId()

Generate the next correlation id that is unique for the connected Media Driver. This is useful generating correlation identifiers for pairing requests with responses in a clients own application protocol. This method is thread safe and will work across processes that all use the same media driver.

Returns:

next correlation id that is unique for the Media Driver.

countersReader

public org.agrona.concurrent.status.CountersReader countersReader()

Create and return a CountersReader for the Aeron media driver counters.

Returns:

new CountersReader for the Aeron media driver in use.