org.eclipse.jgit.internal.ketch

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 to await() for results or be notified by callback using addListener(Runnable).

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Proposal.State Current state of the proposal.

Constructor Summary

Constructors

Constructor and 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

Modifier and Type	Method and 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 and isDone() to be true.
boolean	await(long wait, TimeUnit unit) Wait for the proposal to be attempted and isDone() 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 attempted
Proposal	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()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

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 - a ProposedTimestamp 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 or Proposal.State.ABORTED state. If the proposal is already done callback.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 and isDone() 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 and isDone() 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.

toString

public String toString()

Overrides:

toString in class Object