Package org.eclipse.jgit.internal.ketch

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

    • Field Detail

      • commands

        private final java.util.List<Command> commands

      • message

        private java.lang.String message

      • 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

      • 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 - a ProposedTimestamp 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 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.

      • 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 and isDone() 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 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:
        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.

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • format

        private static void format​(java.lang.StringBuilder s,
                           @Nullable
                           Ref r,
                           java.lang.String n)