public interface Commit<T extends io.atomix.copycat.Operation> extends ReferenceCounted<Commit<T>>
Commits are representative of a log Entry that has been replicated
and committed via the Raft consensus algorithm.
When commands and queries are applied to the Raft StateMachine, they're
wrapped in a commit object. The commit object provides useful metadata regarding the location of the commit
in the Raft replicated log, the time() at which the commit was logged, and the Session that
submitted the operation to the cluster.
All metadata exposed by this interface is backed by disk. The operation and its metadata is
guaranteed to be consistent for a given index across all servers in the cluster.
When state machines are done using a commit object, users should release the commit by calling close().
This notifies Copycat that it's safe to remove the commit from the log as it no longer contributes to the state
machine's state. Copycat guarantees that a commit will be retained in the log and replicated as long as it is
held open by the state machine. Failing to call either method is a bug and will result in disk eventually filling
up, and Copycat will log a warning message in such cases.
| Modifier and Type | Method and Description |
|---|---|
Commit<T> |
acquire()
Acquires a reference to the commit.
|
void |
close()
Closes the commit, releasing all references.
|
default T |
command()
Returns the command submitted by the client.
|
long |
index()
Returns the commit index.
|
T |
operation()
Returns the operation submitted by the client.
|
default T |
query()
Returns the query submitted by the client.
|
int |
references()
Returns the number of open references to the commit.
|
boolean |
release()
Releases a reference to the commit.
|
ServerSession |
session()
Returns the session that submitted the operation.
|
Instant |
time()
Returns the time at which the operation was committed.
|
Class<T> |
type()
Returns the commit type.
|
long index()
This is the index at which the committed Operation was written in the Raft log.
Copycat guarantees that this index will be unique for Command commits and will be the same for all
instances of the given operation on all servers in the cluster.
For Query operations, the returned index may actually be representative of the last committed
index in the Raft log since queries are not actually written to disk. Thus, query commits cannot be assumed
to have unique indexes.
IllegalStateException - if the commit is closedServerSession session()
The returned Session is representative of the session that submitted the operation
that resulted in this Commit. The session can be used to ServerSession.publish(String, Object)
event messages to the client.
IllegalStateException - if the commit is closedInstant time()
The time is representative of the time at which the leader wrote the operation to its log. Because instants are replicated through the Raft consensus algorithm, they are guaranteed to be consistent across all servers and therefore can be used to perform time-dependent operations such as expiring keys or timeouts. Additionally, commit times are guaranteed to progress monotonically, never going back in time.
Users should never use System time to control behavior in a state machine and should instead rely
upon Commit times or use the StateMachineExecutor for time-based controls.
IllegalStateException - if the commit is closedClass<T> type()
This is the Class returned by the committed operation's Object.getClass() method.
IllegalStateException - if the commit is closedT operation()
IllegalStateException - if the commit is closeddefault T command()
This method is an alias for the operation() method. It is intended to aid with clarity in code.
This method does not perform any type checking of the operation to ensure it is in fact a
Command object.
IllegalStateException - if the commit is closeddefault T query()
This method is an alias for the operation() method. It is intended to aid with clarity in code.
This method does not perform any type checking of the operation to ensure it is in fact a
Query object.
IllegalStateException - if the commit is closedCommit<T> acquire()
Initially, all open commits have a single reference. Acquiring new references to a commit will
increase the commit's reference count which is used to determine when it's
safe to recycle the Commit object and compact the underlying entry from the log. Acquired
references must be released once the commit is no longer needed to free up
memory and disk space.
acquire in interface ReferenceCounted<Commit<T extends io.atomix.copycat.Operation>>boolean release()
If releasing the commit results in the reference count decreasing to
0 then the commit will be released back to a pool and the log entry underlying the commit
may be compacted from the log. Once all references to the commit have been released it should
no longer be accessed.
release in interface ReferenceCounted<Commit<T extends io.atomix.copycat.Operation>>int references()
references in interface ReferenceCounted<Commit<T extends io.atomix.copycat.Operation>>void close()
Closing a commit will make it immediately available for compaction from the replicated log. Once the commit is closed, it may be recycled and should no longer be accessed by the closer.
close in interface AutoCloseableclose in interface ReferenceCounted<Commit<T extends io.atomix.copycat.Operation>>Copyright © 2013–2016. All rights reserved.