Cluster (Aeron Message Transport)

```
public interface Cluster
```
Interface for a ClusteredService to interact with cluster hosting it.
This object should only be used to send messages to the cluster or schedule timers in response to other messages and timers. Sending messages and timers should not happen from cluster lifecycle methods like ClusteredService.onStart(Cluster, Image), ClusteredService.onRoleChange(Cluster.Role) or ClusteredService.onTakeSnapshot(ExclusivePublication), or ClusteredService.onTerminate(Cluster), except the session lifecycle methods ClusteredService.onSessionOpen(ClientSession, long), ClusteredService.onSessionClose(ClientSession, long, CloseReason), and ClusteredService.onNewLeadershipTermEvent(long, long, long, long, int, int, TimeUnit, int).

Nested Class Summary

Nested Classes
Modifier and Type Interface and Description

static class Cluster.Role
Role of the node in the cluster.

Nested Classes
Modifier and Type	Interface and Description
`static class`	`Cluster.Role` Role of the node in the cluster.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`Aeron`	`aeron()` Get the `Aeron` client used by the cluster.
`boolean`	`cancelTimer(long correlationId)` Cancel a previously scheduled timer.
`Collection<ClientSession>`	`clientSessions()` Get the current collection of cluster client sessions.
`boolean`	`closeClientSession(long clusterSessionId)` Request the close of a `ClientSession` by sending the request to the consensus module.
`ClusteredServiceContainer.Context`	`context()` Get the `ClusteredServiceContainer.Context` under which the container is running.
`void`	`forEachClientSession(Consumer<? super ClientSession> action)` For each iterator over `ClientSession`s using the most efficient method possible.
`ClientSession`	`getClientSession(long clusterSessionId)` Get the `ClientSession` for a given cluster session id.
`IdleStrategy`	`idleStrategy()` `IdleStrategy` which should be used by the service when it experiences back-pressure on egress, closing sessions, making timer requests, or any long-running actions.
`long`	`logPosition()` Position the log has reached in bytes as of the current message.
`int`	`memberId()` The unique id for the hosting member of the cluster.
`long`	`offer(DirectBuffer buffer, int offset, int length)` Offer a message as ingress to the cluster for sequencing.
`long`	`offer(DirectBufferVector[] vectors)` Offer a message as ingress to the cluster for sequencing.
`Cluster.Role`	`role()` The role the cluster node is playing.
`boolean`	`scheduleTimer(long correlationId, long deadline)` Schedule a timer for a given deadline and provide a correlation id to identify the timer when it expires or for cancellation.
`long`	`time()` Cluster time as `timeUnit()`s since 1 Jan 1970 UTC.
`TimeUnit`	`timeUnit()` The unit of time applied when timestamping and `time()` operations.
`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.

- Method Detail
  - memberId
```
int memberId()
```
    The unique id for the hosting member of the cluster. Useful only for debugging purposes.
    
    Returns:
    
    unique id for the hosting member of the cluster.
  - role
```
Cluster.Role role()
```
    The role the cluster node is playing.
    
    Returns:
    
    the role the cluster node is playing.
  - logPosition
```
long logPosition()
```
    Position the log has reached in bytes as of the current message.
    
    Returns:
    
    position the log has reached in bytes as of the current message.
  - aeron
```
Aeron aeron()
```
    Get the Aeron client used by the cluster.
    
    Returns:
    
    the Aeron client used by the cluster.
  - context
```
ClusteredServiceContainer.Context context()
```
    Get the ClusteredServiceContainer.Context under which the container is running.
    
    Returns:
    
    the ClusteredServiceContainer.Context under which the container is running.
  - getClientSession
```
ClientSession getClientSession(long clusterSessionId)
```
    Get the ClientSession for a given cluster session id.
    
    Parameters:
    
    clusterSessionId - to be looked up.
    
    Returns:
    
    the ClientSession that matches the clusterSessionId.
  - clientSessions
```
Collection<ClientSession> clientSessions()
```
    Get the current collection of cluster client sessions.
    The Iterator on this class does not support nested iteration. It reuses the iterator to avoid allocation.
    
    Returns:
    
    the current collection of cluster client sessions.
  - forEachClientSession
```
void forEachClientSession(Consumer<? super ClientSession> action)
```
    For each iterator over ClientSessions using the most efficient method possible.
    
    Parameters:
    
    action - to be taken for each ClientSession in turn.
  - closeClientSession
```
boolean closeClientSession(long clusterSessionId)
```
    Request the close of a ClientSession by sending the request to the consensus module.
    
    Parameters:
    
    clusterSessionId - to be closed.
    
    Returns:
    
    true if the event to close a session was sent or false if back pressure was applied.
    
    Throws:
    
    ClusterException - if the clusterSessionId is not recognised.
  - time
```
long time()
```
    Cluster time as timeUnit()s since 1 Jan 1970 UTC.
    
    Returns:
    
    time as timeUnit()s since 1 Jan 1970 UTC.
  - timeUnit
```
TimeUnit timeUnit()
```
    The unit of time applied when timestamping and time() operations.
    
    Returns:
    
    the unit of time applied when timestamping and time() operations.
  - scheduleTimer
```
boolean scheduleTimer(long correlationId,
                      long deadline)
```
    Schedule a timer for a given deadline and provide a correlation id to identify the timer when it expires or for cancellation. This action is asynchronous and will race with the timer expiring.
    If the correlationId is for an existing scheduled timer then it will be rescheduled to the new deadline. However, it is best to generate correlationIds in a monotonic fashion and be aware of potential clashes with other services in the same cluster. Service isolation can be achieved by using the upper bits for service id.
    Timers should only be scheduled or cancelled in the context of processing a ClusteredService.onSessionMessage(ClientSession, long, DirectBuffer, int, int, Header), ClusteredService.onTimerEvent(long, long), ClusteredService.onSessionOpen(ClientSession, long), or ClusteredService.onSessionClose(ClientSession, long, CloseReason). If applied to other events then they are not guaranteed to be reliable.
    Callers of this method should loop until the method succeeds.
```
 private Cluster cluster;
 // Lines omitted...

 cluster.idleStrategy().reset();
 while (!cluster.scheduleTimer(correlationId, deadline))
 {
     cluster.idleStrategy().idle();
 }
 
```
    The cluster's idle strategy must be used in the body of the loop to allow for the clustered service to be shutdown if required.
    Parameters:
    
    correlationId - to identify the timer when it expires. Long.MAX_VALUE not supported.
    
    deadline - time after which the timer will fire. Long.MAX_VALUE not supported.
    
    Returns:
    
    true if the event to schedule a timer request has been sent or false if back-pressure is applied.
    
    See Also:
    
    cancelTimer(long)
  - cancelTimer
```
boolean cancelTimer(long correlationId)
```
    Cancel a previously scheduled timer. This action is asynchronous and will race with the timer expiring.
    Timers should only be scheduled or cancelled in the context of processing a ClusteredService.onSessionMessage(ClientSession, long, DirectBuffer, int, int, Header), ClusteredService.onTimerEvent(long, long), ClusteredService.onSessionOpen(ClientSession, long), or ClusteredService.onSessionClose(ClientSession, long, CloseReason). If applied to other events then they are not guaranteed to be reliable.
    Callers of this method should loop until the method succeeds, see scheduleTimer(long, long) for an example.
    
    Parameters:
    
    correlationId - for the timer provided when it was scheduled. Long.MAX_VALUE not supported.
    
    Returns:
    
    true if the event to cancel request has been sent or false if back-pressure is applied.
    
    See Also:
    
    scheduleTimer(long, long)
  - offer
```
long offer(DirectBuffer buffer,
           int offset,
           int length)
```
    Offer a message as ingress to the cluster for sequencing. This will happen efficiently over IPC to the consensus module and have the cluster session of as the negative value of the ClusteredServiceContainer.Configuration.SERVICE_ID_PROP_NAME.
    Callers of this method should loop until the method succeeds.
```
 private Cluster cluster;
 // Lines omitted...

 cluster.idleStrategy().reset();
 do
 {
     final long position = cluster.offer(buffer, offset, length);
     if (position > 0)
     {
         break;
     }
     else if (Publication.ADMIN_ACTION != position && Publication.BACK_PRESSURED != position)
     {
         throw new ClusterException("Internal offer failed: " + position);
     }

     cluster.idleStrategy.idle();
 }
 while (true);
 
```
    The cluster's idle strategy must be used in the body of the loop to allow for the clustered service to be shutdown if required.
    Parameters:
    
    buffer - containing the message to be offered.
    
    offset - in the buffer at which the encoded message begins.
    
    length - in the buffer of the encoded message.
    
    Returns:
    
    positive value if successful.
    
    See Also:
    
    Publication.offer(DirectBuffer, int, int)
  - offer
```
long offer(DirectBufferVector[] vectors)
```
    Offer a message as ingress to the cluster for sequencing. This will happen efficiently over IPC to the consensus module and have the cluster session of as the negative value of the ClusteredServiceContainer.Configuration.SERVICE_ID_PROP_NAME.
    The first vector must be left free to be filled in for the session message header.
    Callers of this method should loop until the method succeeds, see offer(DirectBuffer, int, int) for an example.
    
    Parameters:
    
    vectors - containing the message parts with the first left to be filled.
    
    Returns:
    
    positive value if successful.
    
    See Also:
    
    Publication.offer(DirectBufferVector[])
  - tryClaim
```
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 session header will be written to the start of the claimed buffer section. Clients MUST write into the claimed buffer region at offset + AeronCluster.SESSION_HEADER_LENGTH.
```
     final DirectBuffer srcBuffer = acquireMessage();

     if (cluster.tryClaim(length, bufferClaim))
     {
         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();
         }
     }
 
```
    Callers of this method should loop until the method succeeds, see offer(DirectBuffer, int, int) for an example.
    Parameters:
    
    length - of the range to claim, in bytes.
    
    bufferClaim - to be populated if the claim succeeds.
    
    Returns:
    
    positive value if successful.
    
    Throws:
    
    IllegalArgumentException - if the length is greater than Publication.maxPayloadLength().
    
    See Also:
    
    Publication.tryClaim(int, BufferClaim), BufferClaim.commit(), BufferClaim.abort()
  - idleStrategy
```
IdleStrategy idleStrategy()
```
    IdleStrategy which should be used by the service when it experiences back-pressure on egress, closing sessions, making timer requests, or any long-running actions.
    
    Returns:
    
    the IdleStrategy which should be used by the service when it experiences back-pressure.

Interface Cluster

Nested Class Summary

Method Summary

Method Detail

memberId

role

logPosition

aeron

context

getClientSession

clientSessions

forEachClientSession

closeClientSession

time

timeUnit

scheduleTimer

cancelTimer

offer

offer

tryClaim

idleStrategy