public class Proposal
extends java.lang.Object
Pushing to a Ketch leader results in the leader making a proposal. The
proposal includes the list of reference updates. The leader attempts to send
the proposal to a quorum of replicas by pushing the proposal to a "staging"
area under the refs/txn/stage/
namespace. If the proposal succeeds
then the changes are durable and the leader can commit the proposal.
Proposals are executed by
KetchLeader.queueProposal(Proposal)
,
which runs them asynchronously in the background. Proposals are thread-safe
futures allowing callers to await()
for results or be notified by
callback using addListener(Runnable)
.
Modifier and Type | Class and Description |
---|---|
static class |
Proposal.State
Current state of the proposal.
|
Modifier and Type | Field and Description |
---|---|
private PersonIdent |
author |
private java.util.List<Command> |
commands |
private java.util.List<java.lang.Runnable> |
listeners |
private java.lang.String |
message |
private PushCertificate |
pushCert |
private java.util.concurrent.atomic.AtomicReference<Proposal.State> |
state |
private java.util.List<ProposedTimestamp> |
timestamps |
Constructor and Description |
---|
Proposal(java.util.List<Command> cmds)
Create a proposal from a list of Ketch commands.
|
Proposal(RevWalk rw,
java.util.Collection<ReceiveCommand> cmds)
Create a proposal from a collection of received commands.
|
Modifier and Type | Method and Description |
---|---|
(package private) void |
abort()
Mark commands as "transaction aborted".
|
void |
addListener(java.lang.Runnable callback)
Add a callback to be invoked when the proposal is done.
|
Proposal |
addProposedTimestamp(ProposedTimestamp ts)
Request the proposal to wait for the affected timestamps to resolve.
|
private static java.util.List<Command> |
asCommandList(RevWalk rw,
java.util.Collection<ReceiveCommand> cmds) |
void |
await()
Wait for the proposal to be attempted and
isDone() to be true. |
boolean |
await(long wait,
java.util.concurrent.TimeUnit unit)
Wait for the proposal to be attempted and
isDone() to be true. |
boolean |
awaitStateChange(Proposal.State notIn,
long wait,
java.util.concurrent.TimeUnit unit)
Wait for the proposal to exit a state.
|
private static void |
format(java.lang.StringBuilder s,
Ref r,
java.lang.String n) |
PersonIdent |
getAuthor()
Get optional author of the proposal.
|
java.util.Collection<Command> |
getCommands()
Get commands from this proposal.
|
java.lang.String |
getMessage()
Get optional message for the commit log of the RefTree.
|
java.util.List<ProposedTimestamp> |
getProposedTimestamps()
Get timestamps that Ketch must block for.
|
PushCertificate |
getPushCertificate()
Get optional certificate signing the references.
|
Proposal.State |
getState()
Read the current state of the proposal.
|
boolean |
isDone()
Whether the proposal was attempted
|
(package private) void |
notifyState(Proposal.State s) |
Proposal |
setAuthor(PersonIdent who)
Set the author for the proposal.
|
Proposal |
setMessage(java.lang.String msg)
Set the message to appear in the commit log of the RefTree.
|
Proposal |
setPushCertificate(PushCertificate cert)
Set the push certificate signing the references.
|
(package private) void |
success()
Set command result as OK.
|
java.lang.String |
toString() |
private final java.util.List<Command> commands
private PersonIdent author
private java.lang.String message
private PushCertificate pushCert
private java.util.List<ProposedTimestamp> timestamps
private final java.util.List<java.lang.Runnable> listeners
private final java.util.concurrent.atomic.AtomicReference<Proposal.State> state
public Proposal(java.util.List<Command> cmds)
cmds
- prepared list of commands.public Proposal(RevWalk rw, java.util.Collection<ReceiveCommand> cmds) throws MissingObjectException, java.io.IOException
rw
- walker to assist in preparing commands.cmds
- list of pending commands.MissingObjectException
- newId of a command is not found locally.java.io.IOException
- local objects cannot be accessed.private static java.util.List<Command> asCommandList(RevWalk rw, java.util.Collection<ReceiveCommand> cmds) throws MissingObjectException, java.io.IOException
MissingObjectException
java.io.IOException
public java.util.Collection<Command> getCommands()
@Nullable public PersonIdent getAuthor()
public Proposal setAuthor(@Nullable PersonIdent who)
who
- optional identity of the author of the proposal.this
@Nullable public java.lang.String getMessage()
public Proposal setMessage(@Nullable java.lang.String msg)
msg
- message text for the commit.this
@Nullable public PushCertificate getPushCertificate()
public Proposal setPushCertificate(@Nullable PushCertificate cert)
cert
- certificate, may be null.this
public java.util.List<ProposedTimestamp> getProposedTimestamps()
public Proposal addProposedTimestamp(ProposedTimestamp ts)
ts
- a ProposedTimestamp
object.this
.public void addListener(java.lang.Runnable callback)
A proposal is done when it has entered either
Proposal.State.EXECUTED
or
Proposal.State.ABORTED
state. If
the proposal is already done callback.run()
is immediately
invoked on the caller's thread.
callback
- method to run after the proposal is done. The callback may be
run on a Ketch system thread and should be completed quickly.void success()
void abort()
public Proposal.State getState()
public boolean isDone()
true
if the proposal was attempted. A true value does not
mean consensus was reached, only that the proposal was considered
and will not be making any more progress beyond its current
state.public void await() throws java.lang.InterruptedException
isDone()
to be true.java.lang.InterruptedException
- caller was interrupted before proposal executed.public boolean await(long wait, java.util.concurrent.TimeUnit unit) throws java.lang.InterruptedException
isDone()
to be true.wait
- how long to wait.unit
- unit describing the wait time.java.lang.InterruptedException
- caller was interrupted before proposal executed.public boolean awaitStateChange(Proposal.State notIn, long wait, java.util.concurrent.TimeUnit unit) throws java.lang.InterruptedException
notIn
- state the proposal should not be in to return.wait
- how long to wait.unit
- unit describing the wait time.java.lang.InterruptedException
- caller was interrupted before proposal executed.void notifyState(Proposal.State s)
public java.lang.String toString()
toString
in class java.lang.Object