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)