Class Proposal
- java.lang.Object
-
- org.eclipse.jgit.internal.ketch.Proposal
-
public class Proposal extends 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.
-
Constructor Summary
Constructors Constructor Description Proposal(List<Command> cmds)
Create a proposal from a list of Ketch commands.Proposal(RevWalk rw, Collection<ReceiveCommand> cmds)
Create a proposal from a collection of received commands.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addListener(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.void
await()
Wait for the proposal to be attempted andisDone()
to be true.boolean
await(long wait, TimeUnit unit)
Wait for the proposal to be attempted andisDone()
to be true.boolean
awaitStateChange(Proposal.State notIn, long wait, TimeUnit unit)
Wait for the proposal to exit a state.PersonIdent
getAuthor()
Get optional author of the proposal.Collection<Command>
getCommands()
Get commands from this proposal.String
getMessage()
Get optional message for the commit log of the RefTree.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 attemptedProposal
setAuthor(PersonIdent who)
Set the author for the proposal.Proposal
setMessage(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.String
toString()
-
-
-
Constructor Detail
-
Proposal
public Proposal(List<Command> cmds)
Create a proposal from a list of Ketch commands.- Parameters:
cmds
- prepared list of commands.
-
Proposal
public Proposal(RevWalk rw, Collection<ReceiveCommand> cmds) throws MissingObjectException, 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.IOException
- local objects cannot be accessed.
-
-
Method Detail
-
getCommands
public 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 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 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 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(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.
-
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 InterruptedException
Wait for the proposal to be attempted andisDone()
to be true.- Throws:
InterruptedException
- caller was interrupted before proposal executed.
-
await
public boolean await(long wait, TimeUnit unit) throws 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:
InterruptedException
- caller was interrupted before proposal executed.
-
awaitStateChange
public boolean awaitStateChange(Proposal.State notIn, long wait, TimeUnit unit) throws 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:
InterruptedException
- caller was interrupted before proposal executed.
-
-