io.aeron.cluster.client

Class AeronCluster

java.lang.Object

io.aeron.cluster.client.AeronCluster

All Implemented Interfaces:

AutoCloseable

public final class AeronCluster
extends Object
implements AutoCloseable

Client for interacting with an Aeron Cluster.

A client will attempt to open a session and then offer ingress messages which are replicated to clustered services for reliability. If the clustered service responds then response messages and events are sent via the egress stream.

Note: Instances of this class are not threadsafe.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AeronCluster.AsyncConnect Allows for the async establishment of a cluster session.
static class	AeronCluster.Configuration Configuration options for cluster client.
static class	AeronCluster.Context Context for cluster session and connection.

Field Summary

Fields

Modifier and Type	Field and Description
static int	SESSION_HEADER_LENGTH Length of a session message header for cluster ingress or egress.

Method Summary

Modifier and Type	Method and Description
static AeronCluster.AsyncConnect	asyncConnect() Begin an attempt at creating a connection which can be completed by calling AeronCluster.AsyncConnect.poll() until it returns the client, before complete it will return null.
static AeronCluster.AsyncConnect	asyncConnect(AeronCluster.Context ctx) Begin an attempt at creating a connection which can be completed by calling AeronCluster.AsyncConnect.poll() until it returns the client, before complete it will return null.
void	close() Close session and release associated resources.
long	clusterSessionId() Cluster session id for the session that was opened as the result of a successful connect.
static AeronCluster	connect() Connect to the cluster using default configuration.
static AeronCluster	connect(AeronCluster.Context ctx) Connect to the cluster providing AeronCluster.Context for configuration.
AeronCluster.Context	context() Get the context used to launch this cluster client.
int	controlledPollEgress() Poll the egressSubscription() for session messages which are dispatched to AeronCluster.Context.controlledEgressListener().
Subscription	egressSubscription() Get the raw Subscription for receiving from the cluster.
Publication	ingressPublication() Get the raw Publication for sending to the cluster.
boolean	isClosed() Is the client closed? The client can be closed by calling close() or the cluster sending an event.
int	leaderMemberId() Get the current leader member id for the cluster.
long	leadershipTermId() Leadership term identity for the cluster.
long	offer(DirectBuffer buffer, int offset, int length) Non-blocking publish of a partial buffer containing a message plus session header to a cluster.
long	offer(DirectBufferVector[] vectors) Non-blocking publish by gathering buffer vectors into a message.
void	onNewLeader(long clusterSessionId, long leadershipTermId, int leaderMemberId, String ingressEndpoints) To be called when a new leader event is delivered.
int	pollEgress() Poll the egressSubscription() for session messages which are dispatched to AeronCluster.Context.egressListener().
boolean	sendAdminRequestToTakeASnapshot(long correlationId) Sends an admin request to initiate a snapshot action in the cluster.
boolean	sendKeepAlive() Send a keep alive message to the cluster to keep this session open.
long	tryClaim(int length, BufferClaim bufferClaim) Try to claim a range in the publication log into which a message can be written with zero copy semantics.

Methods inherited from class java.lang.Object

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

Field Detail

SESSION_HEADER_LENGTH

public static final int SESSION_HEADER_LENGTH

Length of a session message header for cluster ingress or egress.

See Also:

Constant Field Values

Method Detail

connect

public static AeronCluster connect()

Connect to the cluster using default configuration.

Returns:

allocated cluster client if the connection is successful.

connect

public static AeronCluster connect(AeronCluster.Context ctx)

Connect to the cluster providing AeronCluster.Context for configuration.

Parameters:

ctx - for configuration.

Returns:

allocated cluster client if the connection is successful.

asyncConnect

public static AeronCluster.AsyncConnect asyncConnect()

Begin an attempt at creating a connection which can be completed by calling AeronCluster.AsyncConnect.poll() until it returns the client, before complete it will return null.

Returns:

the AeronCluster.AsyncConnect that can be polled for completion.

asyncConnect

public static AeronCluster.AsyncConnect asyncConnect(AeronCluster.Context ctx)

Begin an attempt at creating a connection which can be completed by calling AeronCluster.AsyncConnect.poll() until it returns the client, before complete it will return null.

Parameters:

ctx - for the cluster.

Returns:

the AeronCluster.AsyncConnect that can be polled for completion.

close

public void close()

Close session and release associated resources.

Specified by:

close in interface AutoCloseable

isClosed

public boolean isClosed()

Is the client closed? The client can be closed by calling close() or the cluster sending an event.

Returns:

true if closed otherwise false.

context

public AeronCluster.Context context()

Get the context used to launch this cluster client.

Returns:

the context used to launch this cluster client.

clusterSessionId

public long clusterSessionId()

Cluster session id for the session that was opened as the result of a successful connect.

Returns:

session id for the session that was opened as the result of a successful connect.

leadershipTermId

public long leadershipTermId()

Leadership term identity for the cluster. Advances with changing leadership.

Returns:

leadership term identity for the cluster.

leaderMemberId

public int leaderMemberId()

Get the current leader member id for the cluster.

Returns:

the current leader member id for the cluster.

ingressPublication

public Publication ingressPublication()

Get the raw Publication for sending to the cluster.

This can be wrapped with a IngressSessionDecorator for pre-pending the cluster session header to messages. SessionMessageHeaderEncoder should be used for raw access.

Returns:

the raw Publication for connecting to the cluster.

egressSubscription

public Subscription egressSubscription()

Get the raw Subscription for receiving from the cluster.

This can be wrapped with a EgressAdapter for dispatching events from the cluster. SessionMessageHeaderDecoder should be used for raw access.

Returns:

the raw Subscription for receiving from the cluster.

tryClaim

public long tryClaim(int length,
                     BufferClaim bufferClaim)

Try to claim a range in the publication log into which a message can be written with zero copy semantics. Once the message has been written then BufferClaim.commit() should be called thus making it available.

On successful claim, the Cluster ingress header will be written to the start of the claimed buffer section. Clients MUST write into the claimed buffer region at offset + SESSION_HEADER_LENGTH.

     final DirectBuffer srcBuffer = acquireMessage();

     if (aeronCluster.tryClaim(length, bufferClaim) > 0L)
     {
         try
         {
              final MutableDirectBuffer buffer = bufferClaim.buffer();
              final int offset = bufferClaim.offset();
              // ensure that data is written at the correct offset
              buffer.putBytes(offset + AeronCluster.SESSION_HEADER_LENGTH, srcBuffer, 0, length);
         }
         finally
         {
             bufferClaim.commit();
         }
     }
 

Parameters:

length - of the range to claim in bytes. The additional bytes for the session header will be added.

bufferClaim - to be populated if the claim succeeds.

Returns:

The new stream position, otherwise a negative error value as specified in Publication.tryClaim(int, BufferClaim).

Throws:

IllegalArgumentException - if the length is greater than Publication.maxPayloadLength().

See Also:

Publication.tryClaim(int, BufferClaim), BufferClaim.commit(), BufferClaim.abort()

offer

public long offer(DirectBuffer buffer,
                  int offset,
                  int length)

Non-blocking publish of a partial buffer containing a message plus session header to a cluster.

This version of the method will set the timestamp value in the header to zero.

Parameters:

buffer - containing message.

offset - offset in the buffer at which the encoded message begins.

length - in bytes of the encoded message.

Returns:

the same as Publication.offer(DirectBuffer, int, int).

offer

public long offer(DirectBufferVector[] vectors)

Non-blocking publish by gathering buffer vectors into a message. The first vector will be replaced by the cluster session message header so must be left unused.

Parameters:

vectors - which make up the message.

Returns:

the same as Publication.offer(DirectBufferVector[]).

See Also:

Publication.offer(DirectBufferVector[])

sendKeepAlive

public boolean sendKeepAlive()

Send a keep alive message to the cluster to keep this session open.

Note: Sending keep-alive can fail during a leadership transition. The application should continue to call pollEgress() to ensure a connection to the new leader is established.

Returns:

true if successfully sent otherwise false if back pressured.

sendAdminRequestToTakeASnapshot

public boolean sendAdminRequestToTakeASnapshot(long correlationId)

Sends an admin request to initiate a snapshot action in the cluster. This request requires elevated privileges.

Parameters:

correlationId - for the request.

Returns:

true if the request was sent or false otherwise.

See Also:

EgressListener.onAdminResponse(long, long, AdminRequestType, AdminResponseCode, String, DirectBuffer, int, int), ControlledEgressListener.onAdminResponse(long, long, AdminRequestType, AdminResponseCode, String, DirectBuffer, int, int)

pollEgress

public int pollEgress()

Poll the egressSubscription() for session messages which are dispatched to AeronCluster.Context.egressListener(). Invoking this method, or controlledPollEgress(), frequently is important for detecting leadership changes in a cluster.

Note: if AeronCluster.Context.egressListener() is not set then a ConfigurationException could result.

Returns:

the number of fragments processed.

See Also:

controlledPollEgress()

controlledPollEgress

public int controlledPollEgress()

Poll the egressSubscription() for session messages which are dispatched to AeronCluster.Context.controlledEgressListener(). Invoking this method, or pollEgress(), frequently is important for detecting leadership changes in a cluster.

Note: if AeronCluster.Context.controlledEgressListener() is not set then a ConfigurationException could result.

Returns:

the number of fragments processed.

See Also:

pollEgress()

onNewLeader

public void onNewLeader(long clusterSessionId,
                        long leadershipTermId,
                        int leaderMemberId,
                        String ingressEndpoints)

To be called when a new leader event is delivered. This method needs to be called when using the EgressAdapter or EgressPoller rather than pollEgress() method.

Parameters:

clusterSessionId - which must match clusterSessionId().

leadershipTermId - that identifies the term for which the new leader has been elected.

leaderMemberId - which has become the new leader.

ingressEndpoints - comma separated list of cluster ingress endpoints to connect to with the leader first.