Aeron (Aeron Message Transport)

java.lang.Object
- io.aeron.Aeron

All Implemented Interfaces:

AutoCloseable
```
public class Aeron
extends Object
implements 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.
Note: If Aeron.Context.errorHandler(ErrorHandler) is not set and a DriverTimeoutException occurs then the process will face the wrath of System.exit(int). See Aeron.Configuration.DEFAULT_ERROR_HANDLER.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`Aeron.Configuration` Configuration options for the `Aeron` client.
`static class`	`Aeron.Context` Provides a means to override configuration for an `Aeron` client via the `connect(Aeron.Context)` method and its overloads.

Field Summary

Fields
Modifier and Type Field and Description

static int NULL_VALUE
Used to represent a null value for when some value is not yet set.

Fields
Modifier and Type	Field and Description
`static int`	`NULL_VALUE` Used to represent a null value for when some value is not yet set.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`long`	`addAvailableCounterHandler(AvailableCounterHandler handler)` Add a handler to the list be called when `Counter`s become available.
`long`	`addCloseHandler(Runnable handler)` Add a handler to the list be called when the Aeron client is closed.
`Counter`	`addCounter(int typeId, DirectBuffer keyBuffer, int keyOffset, int keyLength, DirectBuffer labelBuffer, int labelOffset, int labelLength)` Allocate a counter on the media driver and return a `Counter` for it.
`Counter`	`addCounter(int typeId, String label)` Allocate a counter on the media driver and return a `Counter` for it.
`ExclusivePublication`	`addExclusivePublication(String channel, int streamId)` Add an `ExclusivePublication` for publishing messages to subscribers from a single thread.
`ConcurrentPublication`	`addPublication(String channel, int streamId)` Add a `Publication` for publishing messages to subscribers.
`Subscription`	`addSubscription(String channel, int streamId)` Add a new `Subscription` for subscribing to messages from publishers.
`Subscription`	`addSubscription(String channel, int streamId, AvailableImageHandler availableImageHandler, UnavailableImageHandler unavailableImageHandler)` Add a new `Subscription` for subscribing to messages from publishers.
`long`	`addUnavailableCounterHandler(UnavailableCounterHandler handler)` Add a handler to the list be called when `Counter`s become unavailable.
`long`	`clientId()` Get the client identity that has been allocated for communicating with the media driver.
`void`	`close()` Clean up and release all Aeron client resources and shutdown conductor thread if not using `Aeron.Context.useConductorAgentInvoker(boolean)`.
`AgentInvoker`	`conductorAgentInvoker()` Get the `AgentInvoker` for the client conductor.
`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.
`Aeron.Context`	`context()` Get the `Aeron.Context` that is used by this client.
`CountersReader`	`countersReader()` Get the `CountersReader` for the Aeron media driver counters.
`boolean`	`hasActiveCommands()` Does the client have any active asynchronous commands?
`boolean`	`isClosed()` Has the client been closed? If not then the CnC file may not be unmapped.
`boolean`	`isCommandActive(long correlationId)` Is the command still active for a given correlation id.
`long`	`nextCorrelationId()` Generate the next correlation id that is unique for the connected Media Driver.
`void`	`printCounters(PrintStream out)` Print out the values from `countersReader()` which can be useful for debugging.
`boolean`	`removeAvailableCounterHandler(AvailableCounterHandler handler)` Deprecated. please use `removeAvailableCounterHandler(long)`.
`boolean`	`removeAvailableCounterHandler(long registrationId)` Remove a previously added handler to the list be called when `Counter`s become available.
`boolean`	`removeCloseHandler(long registrationId)` Remove a previously added handler to the list be called when the Aeron client is closed.
`boolean`	`removeCloseHandler(Runnable handler)` Deprecated. please use `removeCloseHandler(long)`.
`boolean`	`removeUnavailableCounterHandler(long registrationId)` Remove a previously added handler to the list be called when `Counter`s become unavailable.
`boolean`	`removeUnavailableCounterHandler(UnavailableCounterHandler handler)` Deprecated. please use `removeUnavailableCounterHandler(long)`.

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

- Field Detail
  - NULL_VALUE
```
public static final int NULL_VALUE
```
    Used to represent a null value for when some value is not yet set.
    
    See Also:
    
    Constant Field Values
- 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.
  - printCounters
```
public void printCounters(PrintStream out)
```
    Print out the values from countersReader() which can be useful for debugging.
    
    Parameters:
    
    out - to where the counters get printed.
  - isClosed
```
public boolean isClosed()
```
    Has the client been closed? If not then the CnC file may not be unmapped.
    
    Returns:
    
    true if the client has been explicitly closed otherwise false.
  - context
```
public Aeron.Context context()
```
    Get the Aeron.Context that is used by this client.
    
    Returns:
    
    the Aeron.Context that is use by this client.
  - clientId
```
public long clientId()
```
    Get the client identity that has been allocated for communicating with the media driver.
    
    Returns:
    
    the client identity that has been allocated for communicating with the media driver.
  - conductorAgentInvoker
```
public AgentInvoker conductorAgentInvoker()
```
    Get the AgentInvoker for the client conductor.
    
    Returns:
    
    the AgentInvoker for the client conductor.
  - isCommandActive
```
public boolean isCommandActive(long correlationId)
```
    Is the command still active for a given correlation id.
    
    Parameters:
    
    correlationId - to check if it is still active.
    
    Returns:
    
    true in the command is still in active processing or false if completed successfully or errored.
    
    See Also:
    
    Publication.asyncAddDestination(String), Subscription.asyncAddDestination(String), hasActiveCommands()
  - hasActiveCommands
```
public boolean hasActiveCommands()
```
    Does the client have any active asynchronous commands?
    When close operations are performed on Publications, Subscriptions, and Counters the commands are sent asynchronously to the driver. The client tracks active commands in case errors need to be reported. If you wish to wait for acknowledgement of close operations then wait for this method to return false.
    
    Returns:
    
    true if any commands are currently active otherwise false.
  - close
```
public void close()
```
    Clean up and release all Aeron client resources and shutdown conductor thread if not using Aeron.Context.useConductorAgentInvoker(boolean).
    This will close all currently open Publications, Subscriptions, and Counters created from this client. To check for the command being acknowledged by the driver
    
    Specified by:
    
    close in interface AutoCloseable
  - addPublication
```
public ConcurrentPublication addPublication(String channel,
                                            int streamId)
```
    Add a Publication for publishing messages to subscribers. The publication returned is threadsafe.
    
    Parameters:
    
    channel - for sending the messages known to the media layer.
    
    streamId - within the channel scope.
    
    Returns:
    
    a new ConcurrentPublication.
  - addExclusivePublication
```
public ExclusivePublication addExclusivePublication(String channel,
                                                    int streamId)
```
    Add an ExclusivePublication for publishing messages to subscribers from a single thread.
    
    Parameters:
    
    channel - for sending the messages known to the media layer.
    
    streamId - within the channel scope.
    
    Returns:
    
    a new ExclusivePublication.
  - addSubscription
```
public Subscription addSubscription(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(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 CountersReader countersReader()
```
    Get the CountersReader for the Aeron media driver counters.
    
    Returns:
    
    new CountersReader for the Aeron media driver in use.
  - addCounter
```
public Counter addCounter(int typeId,
                          DirectBuffer keyBuffer,
                          int keyOffset,
                          int keyLength,
                          DirectBuffer labelBuffer,
                          int labelOffset,
                          int labelLength)
```
    Allocate a counter on the media driver and return a Counter for it.
    The counter should be freed by calling Counter.close().
    
    Parameters:
    
    typeId - for the counter.
    
    keyBuffer - containing the optional key for the counter.
    
    keyOffset - within the keyBuffer at which the key begins.
    
    keyLength - of the key in the keyBuffer.
    
    labelBuffer - containing the mandatory label for the counter. The label should not be length prefixed.
    
    labelOffset - within the labelBuffer at which the label begins.
    
    labelLength - of the label in the labelBuffer.
    
    Returns:
    
    the newly allocated counter.
    
    See Also:
    
    CountersManager.allocate(int, DirectBuffer, int, int, DirectBuffer, int, int)
  - addCounter
```
public Counter addCounter(int typeId,
                          String label)
```
    Allocate a counter on the media driver and return a Counter for it.
    The counter should be freed by calling Counter.close().
    
    Parameters:
    
    typeId - for the counter.
    
    label - for the counter. It should be US-ASCII.
    
    Returns:
    
    the newly allocated counter.
    
    See Also:
    
    CountersManager.allocate(String, int)
  - addAvailableCounterHandler
```
public long addAvailableCounterHandler(AvailableCounterHandler handler)
```
    Add a handler to the list be called when Counters become available.
    
    Parameters:
    
    handler - to be called when Counters become available.
    
    Returns:
    
    registration id for the handler which can be used to remove it.
  - removeAvailableCounterHandler
```
public boolean removeAvailableCounterHandler(long registrationId)
```
    Remove a previously added handler to the list be called when Counters become available.
    
    Parameters:
    
    registrationId - to be removed which was returned from add method.
    
    Returns:
    
    true if found and removed otherwise false.
  - removeAvailableCounterHandler
```
@Deprecated
public boolean removeAvailableCounterHandler(AvailableCounterHandler handler)
```
    Deprecated. please use removeAvailableCounterHandler(long).
    
    Remove a previously added handler to the list be called when Counters become available.
    
    Parameters:
    
    handler - to be removed.
    
    Returns:
    
    true if found and removed otherwise false.
  - addUnavailableCounterHandler
```
public long addUnavailableCounterHandler(UnavailableCounterHandler handler)
```
    Add a handler to the list be called when Counters become unavailable.
    
    Parameters:
    
    handler - to be called when Counters become unavailable.
    
    Returns:
    
    registration id for the handler which can be used to remove it.
  - removeUnavailableCounterHandler
```
public boolean removeUnavailableCounterHandler(long registrationId)
```
    Remove a previously added handler to the list be called when Counters become unavailable.
    
    Parameters:
    
    registrationId - to be removed which was returned from add method.
    
    Returns:
    
    true if found and removed otherwise false.
  - removeUnavailableCounterHandler
```
@Deprecated
public boolean removeUnavailableCounterHandler(UnavailableCounterHandler handler)
```
    Deprecated. please use removeUnavailableCounterHandler(long).
    
    Remove a previously added handler to the list be called when Counters become unavailable.
    
    Parameters:
    
    handler - to be removed.
    
    Returns:
    
    true if found and removed otherwise false.
  - addCloseHandler
```
public long addCloseHandler(Runnable handler)
```
    Add a handler to the list be called when the Aeron client is closed.
    
    Parameters:
    
    handler - to be called when the Aeron client is closed.
    
    Returns:
    
    registration id for the handler which can be used to remove it.
  - removeCloseHandler
```
public boolean removeCloseHandler(long registrationId)
```
    Remove a previously added handler to the list be called when the Aeron client is closed.
    
    Parameters:
    
    registrationId - of the handler from when it was added.
    
    Returns:
    
    true if found and removed otherwise false.
  - removeCloseHandler
```
@Deprecated
public boolean removeCloseHandler(Runnable handler)
```
    Deprecated. please use removeCloseHandler(long).
    
    Remove a previously added handler to the list be called when the Aeron client is closed.
    
    Parameters:
    
    handler - to be removed.
    
    Returns:
    
    true if found and removed otherwise false.

Class Aeron

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

NULL_VALUE

Method Detail

connect

connect

printCounters

isClosed

context

clientId

conductorAgentInvoker

isCommandActive

hasActiveCommands

close

addPublication

addExclusivePublication

addSubscription

addSubscription

nextCorrelationId

countersReader

addCounter

addCounter

addAvailableCounterHandler

removeAvailableCounterHandler

removeAvailableCounterHandler

addUnavailableCounterHandler

removeUnavailableCounterHandler

removeUnavailableCounterHandler

addCloseHandler

removeCloseHandler

removeCloseHandler