public final class AeronCluster extends Object implements AutoCloseable
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.
| 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.
|
| Modifier and Type | Field and Description |
|---|---|
static int |
SESSION_HEADER_LENGTH
Length of a session message header for cluster ingress or egress.
|
| 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.
|
public static final int SESSION_HEADER_LENGTH
public static AeronCluster connect()
public static AeronCluster connect(AeronCluster.Context ctx)
AeronCluster.Context for configuration.ctx - for configuration.public static AeronCluster.AsyncConnect asyncConnect()
AeronCluster.AsyncConnect.poll() until
it returns the client, before complete it will return null.AeronCluster.AsyncConnect that can be polled for completion.public static AeronCluster.AsyncConnect asyncConnect(AeronCluster.Context ctx)
AeronCluster.AsyncConnect.poll() until
it returns the client, before complete it will return null.ctx - for the cluster.AeronCluster.AsyncConnect that can be polled for completion.public void close()
close in interface AutoCloseablepublic boolean isClosed()
close() or the cluster sending an event.public AeronCluster.Context context()
public long clusterSessionId()
public long leadershipTermId()
public int leaderMemberId()
public Publication ingressPublication()
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.
Publication for connecting to the cluster.public Subscription egressSubscription()
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.
Subscription for receiving from the cluster.public long tryClaim(int length,
BufferClaim bufferClaim)
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();
}
}
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.Publication.tryClaim(int, BufferClaim).IllegalArgumentException - if the length is greater than Publication.maxPayloadLength().Publication.tryClaim(int, BufferClaim),
BufferClaim.commit(),
BufferClaim.abort()public long offer(DirectBuffer buffer, int offset, int length)
This version of the method will set the timestamp value in the header to zero.
buffer - containing message.offset - offset in the buffer at which the encoded message begins.length - in bytes of the encoded message.Publication.offer(DirectBuffer, int, int).public long offer(DirectBufferVector[] vectors)
vectors - which make up the message.Publication.offer(DirectBufferVector[]).Publication.offer(DirectBufferVector[])public boolean sendKeepAlive()
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.
public boolean sendAdminRequestToTakeASnapshot(long correlationId)
correlationId - for the request.true if the request was sent or false otherwise.EgressListener.onAdminResponse(long, long, AdminRequestType, AdminResponseCode, String, DirectBuffer, int, int),
ControlledEgressListener.onAdminResponse(long, long, AdminRequestType, AdminResponseCode, String, DirectBuffer, int, int)public int pollEgress()
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.
controlledPollEgress()public int controlledPollEgress()
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.
pollEgress()public void onNewLeader(long clusterSessionId,
long leadershipTermId,
int leaderMemberId,
String ingressEndpoints)
EgressAdapter or EgressPoller rather than pollEgress() method.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.Copyright © 2014-2023 Real Logic Limited. All Rights Reserved.