Class Proposal
- java.lang.Object
-
- org.eclipse.jgit.internal.ketch.Proposal
-
public class Proposal extends java.lang.Object
A proposal to be applied in a Ketch system.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 toawait()
for results or be notified by callback usingaddListener(Runnable)
.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
Proposal.State
Current state of the proposal.
-
Field Summary
Fields Modifier and Type Field 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 Summary
Constructors Constructor 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.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method 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 andisDone()
to be true.boolean
await(long wait, java.util.concurrent.TimeUnit unit)
Wait for the proposal to be attempted andisDone()
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()
-
-
-
Field Detail
-
commands
private final java.util.List<Command> commands
-
author
private PersonIdent author
-
message
private java.lang.String message
-
pushCert
private PushCertificate pushCert
-
timestamps
private java.util.List<ProposedTimestamp> timestamps
-
listeners
private final java.util.List<java.lang.Runnable> listeners
-
state
private final java.util.concurrent.atomic.AtomicReference<Proposal.State> state
-
-
Constructor Detail
-
Proposal
public Proposal(java.util.List<Command> cmds)
Create a proposal from a list of Ketch commands.- Parameters:
cmds
- prepared list of commands.
-
Proposal
public Proposal(RevWalk rw, java.util.Collection<ReceiveCommand> cmds) throws MissingObjectException, java.io.IOException
Create a proposal from a collection of received commands.- Parameters:
rw
- walker to assist in preparing commands.cmds
- list of pending commands.- Throws:
MissingObjectException
- newId of a command is not found locally.java.io.IOException
- local objects cannot be accessed.
-
-
Method Detail
-
asCommandList
private static java.util.List<Command> asCommandList(RevWalk rw, java.util.Collection<ReceiveCommand> cmds) throws MissingObjectException, java.io.IOException
- Throws:
MissingObjectException
java.io.IOException
-
getCommands
public java.util.Collection<Command> getCommands()
Get commands from this proposal.- Returns:
- commands from this proposal.
-
getAuthor
@Nullable public PersonIdent getAuthor()
Get optional author of the proposal.- Returns:
- optional author of the proposal.
-
setAuthor
public Proposal setAuthor(@Nullable PersonIdent who)
Set the author for the proposal.- Parameters:
who
- optional identity of the author of the proposal.- Returns:
this
-
getMessage
@Nullable public java.lang.String getMessage()
Get optional message for the commit log of the RefTree.- Returns:
- optional message for the commit log of the RefTree.
-
setMessage
public Proposal setMessage(@Nullable java.lang.String msg)
Set the message to appear in the commit log of the RefTree.- Parameters:
msg
- message text for the commit.- Returns:
this
-
getPushCertificate
@Nullable public PushCertificate getPushCertificate()
Get optional certificate signing the references.- Returns:
- optional certificate signing the references.
-
setPushCertificate
public Proposal setPushCertificate(@Nullable PushCertificate cert)
Set the push certificate signing the references.- Parameters:
cert
- certificate, may be null.- Returns:
this
-
getProposedTimestamps
public java.util.List<ProposedTimestamp> getProposedTimestamps()
Get timestamps that Ketch must block for.- Returns:
- timestamps that Ketch must block for. These may have been used as commit times inside the objects involved in the proposal.
-
addProposedTimestamp
public Proposal addProposedTimestamp(ProposedTimestamp ts)
Request the proposal to wait for the affected timestamps to resolve.- Parameters:
ts
- aProposedTimestamp
object.- Returns:
this
.
-
addListener
public void addListener(java.lang.Runnable callback)
Add a callback to be invoked when the proposal is done.A proposal is done when it has entered either
Proposal.State.EXECUTED
orProposal.State.ABORTED
state. If the proposal is already donecallback.run()
is immediately invoked on the caller's thread.- Parameters:
callback
- method to run after the proposal is done. The callback may be run on a Ketch system thread and should be completed quickly.
-
success
void success()
Set command result as OK.
-
abort
void abort()
Mark commands as "transaction aborted".
-
getState
public Proposal.State getState()
Read the current state of the proposal.- Returns:
- read the current state of the proposal.
-
isDone
public boolean isDone()
Whether the proposal was attempted- Returns:
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.
-
await
public void await() throws java.lang.InterruptedException
Wait for the proposal to be attempted andisDone()
to be true.- Throws:
java.lang.InterruptedException
- caller was interrupted before proposal executed.
-
await
public boolean await(long wait, java.util.concurrent.TimeUnit unit) throws java.lang.InterruptedException
Wait for the proposal to be attempted andisDone()
to be true.- Parameters:
wait
- how long to wait.unit
- unit describing the wait time.- Returns:
- true if the proposal is done; false if the method timed out.
- Throws:
java.lang.InterruptedException
- caller was interrupted before proposal executed.
-
awaitStateChange
public boolean awaitStateChange(Proposal.State notIn, long wait, java.util.concurrent.TimeUnit unit) throws java.lang.InterruptedException
Wait for the proposal to exit a state.- Parameters:
notIn
- state the proposal should not be in to return.wait
- how long to wait.unit
- unit describing the wait time.- Returns:
- true if the proposal exited the state; false on time out.
- Throws:
java.lang.InterruptedException
- caller was interrupted before proposal executed.
-
notifyState
void notifyState(Proposal.State s)
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
-