org.multiverse.commitbarriers

## Class CommitBarrier

- java.lang.Object
- - org.multiverse.commitbarriers.CommitBarrier

Direct Known Subclasses:
  CountDownCommitBarrier, VetoCommitBarrier

    public abstract class CommitBarrier
    extends java.lang.Object

A CommitBarrier is a blocking structure like the `CyclicBarrier` but tailored to work with transactions. Based on this functionality, it is possible to create a 2-phase commit for example.

### Field Summary

Fields
`protected java.util.concurrent.locks.Lock` `lock`
`protected java.util.concurrent.locks.Condition` `statusCondition`

### Constructor Summary

Constructors
Constructor and Description
`CommitBarrier(org.multiverse.commitbarriers.CommitBarrier.Status status, boolean fair)` Creates a new CommitBarrier.

### Method Summary

Methods
`void` `abort()` Aborts this CommitBarrier.
`protected void` `addJoiner()` Adds a waiters.
`void` `awaitOpen()` Awaits for this barrier to open (commit or abort).
`void` `awaitOpenUninterruptibly()` Awaits for this barrier to open (commit or abort).
`protected static void` `ensureNotDead(Txn tx, java.lang.String operation)` Ensures that a transaction is not dead.
`protected static void` `executeTasks(java.util.List<java.lang.Runnable> tasks)` Executes the tasks.
`protected void` `finish(Txn tx)` Finishes a Txn.
`int` `getNumberWaiting()` Returns the number of Transactions that have prepared and are waiting to commit.
`protected org.multiverse.commitbarriers.CommitBarrier.Status` `getStatus()`
`boolean` `isAborted()` Checks if this CommitBarrier already is aborted.
`boolean` `isClosed()` Checks if this CommitBarrier is closed.
`boolean` `isCommitted()` Checks if this CommitBarrier already is committed.
`protected abstract boolean` `isLastParty()`
`void` `joinCommit(Txn tx)` Joins this CommitBarrier with the provided transaction.
`void` `joinCommitUninterruptibly(Txn tx)` Joins this CommitBarrier with the provided transaction.
`void` `registerOnAbortTask(java.lang.Runnable task)` Registers a task that is executed once the CommitBarrier aborts.
`void` `registerOnCommitTask(java.lang.Runnable task)` Registers a task that is executed once the CommitBarrier commits.
`void` `setScheduledExecutorService(java.util.concurrent.ScheduledExecutorService executorService)` Sets the ScheduledExecutorService to be used by this CommitBarrier for the timeout.
`void` `setTimeout(long timeout, java.util.concurrent.TimeUnit unit)` Sets the timeout on this CommitBarrier.
`protected java.util.List<java.lang.Runnable>` `signalAborted()` Only should be made when the lock is acquired.
`protected java.util.List<java.lang.Runnable>` `signalCommit()` Only should be made when the lock is acquired.
`boolean` `tryAwaitOpen(long timeout, java.util.concurrent.TimeUnit unit)` Waits for this barrier to open (abort or commit).
`boolean` `tryAwaitOpenUninterruptibly(long timeout, java.util.concurrent.TimeUnit unit)` Tries to await the close of the barrier.
`boolean` `tryJoinCommit(Txn tx)` Tries to joins this CommitBarrier with the provided transaction.
`boolean` `tryJoinCommit(Txn tx, long timeout, java.util.concurrent.TimeUnit unit)` Tries to joins this CommitBarrier with the provided transaction.
`boolean` `tryJoinCommitUninterruptibly(Txn tx, long timeout, java.util.concurrent.TimeUnit unit)` Tries to joins this CommitBarrier with the provided transaction.

### Methods inherited from class java.lang.Object

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

### Field Detail

#### lock

    protected final java.util.concurrent.locks.Lock lock

#### statusCondition

    protected final java.util.concurrent.locks.Condition statusCondition

### Constructor Detail

#### CommitBarrier

    public CommitBarrier(org.multiverse.commitbarriers.CommitBarrier.Status status,
                 boolean fair)

Creates a new CommitBarrier.

Parameters:
  `status` - the initial status of the CommitBarrier.
  `fair` - if waking up threads is going to be fair.
Throws:
  `java.lang.NullPointerException` - if status is null.

### Method Detail

#### getStatus

    protected final org.multiverse.commitbarriers.CommitBarrier.Status getStatus()

#### getNumberWaiting

    public final int getNumberWaiting()

Returns the number of Transactions that have prepared and are waiting to commit. Value eventually becomes null after a commit or abort.

Returns:
  the number of transactions prepared.

#### isClosed

    public final boolean isClosed()

Checks if this CommitBarrier is closed. This is the initial status of the barrier.

Returns:
  true if closed, false otherwise.

#### isCommitted

    public final boolean isCommitted()

Checks if this CommitBarrier already is committed.

Returns:
  true if committed, false otherwise.

#### isAborted

    public final boolean isAborted()

Checks if this CommitBarrier already is aborted.

Returns:
  true if aborted, false otherwise.

#### signalCommit

    protected final java.util.List<java.lang.Runnable> signalCommit()

Only should be made when the lock is acquired.

Returns:
  the List of onCommitTasks that needs to be executed (is allowed to be null).

#### signalAborted

    protected final java.util.List<java.lang.Runnable> signalAborted()

Only should be made when the lock is acquired.

Returns:
  the List of onAbortTasks that needs to be executed (is allowed to be null).

#### abort

    public final void abort()

Aborts this CommitBarrier. If there are any prepared transactions that are waiting for this CommitBarrier to complete, they are aborted as well.

If the CommitBarrier already is aborted, this call is ignored.

Throws:
  `CommitBarrierOpenException` - if this CommitBarrier already is committed.

#### executeTasks

    protected static void executeTasks(java.util.List<java.lang.Runnable> tasks)

Executes the tasks. Can be called with a null argument.

Parameters:
  `tasks` - the tasks to execute.

#### awaitOpen

    public final void awaitOpen()
                         throws java.lang.InterruptedException

Awaits for this barrier to open (commit or abort). This call doesn't influence the state of this CommitBarrier.

Throws:
  `java.lang.InterruptedException` - if the calling thread is interrupted while waiting.

#### awaitOpenUninterruptibly

    public final void awaitOpenUninterruptibly()

Awaits for this barrier to open (commit or abort). This call doesn't influence the state of this CommitBarrier.

This call is not responsive to interrupts.

#### tryAwaitOpen

    public final boolean tryAwaitOpen(long timeout,
                       java.util.concurrent.TimeUnit unit)
                               throws java.lang.InterruptedException

Waits for this barrier to open (abort or commit). This call doesn't influence the state of this CommitBarrier.

Parameters:
  `timeout` - the maximum amount of time to wait for the barrier to close.
  `unit` - the TimeUnit for the timeout argument.
Returns:
  true if the wait was a success, false if the barrier still is closed.
Throws:
  `java.lang.InterruptedException` - if the thread is interrupted while waiting.
  `java.lang.NullPointerException` - if unit is null.

#### tryAwaitOpenUninterruptibly

    public final boolean tryAwaitOpenUninterruptibly(long timeout,
                                      java.util.concurrent.TimeUnit unit)

Tries to await the close of the barrier. This call doesn't influence the state of this CommitBarrier.

This call is not responsive to interrupts.

Parameters:
  `timeout` - the maximum amount of time to wait for the barrier to be closed.
  `unit` - the timeunit for the timeout argument.
Returns:
  true if the wait was a success, false otherwise.

#### setScheduledExecutorService

    public void setScheduledExecutorService(java.util.concurrent.ScheduledExecutorService executorService)

Sets the ScheduledExecutorService to be used by this CommitBarrier for the timeout. This method can always be called no matter the state of the CommitBarrier.

Parameters:
  `executorService` - the ScheduledExecutorService this CommitBarrier is going to use for timeout.
Throws:
  `java.lang.NullPointerException` - if executorService is null.

#### setTimeout

    public final void setTimeout(long timeout,
                  java.util.concurrent.TimeUnit unit)

Sets the timeout on this CommitBarrier. If the barrier hasn't committed/aborted before the timeout it automatically is aborted. This is a function that typically is used when initializing the CommitBarrier.

The timeout starts running when this method is called.

Parameters:
  `timeout` - the maximum amount of time this barrier is allowed to run.
  `unit` - the TimeUnit of the timeout parameter.
Throws:
  `java.lang.NullPointerException` - if unit is null.
  `CommitBarrierOpenException` - if the CommitBarrier already is aborted or committed.

#### registerOnAbortTask

    public final void registerOnAbortTask(java.lang.Runnable task)

Registers a task that is executed once the CommitBarrier aborts.

The task will be executed after the abort and will be executed by the thread that does the actual abort.

The tasks will be executed in the order they are registered and will be executed at most once. If one of the tasks throws a RuntimeException, the following will not be executed.

Parameters:
  `task` - the task that is executed once the CommitBarrier commits.
Throws:
  `java.lang.NullPointerException` - if task is null.
  `CommitBarrierOpenException` - if this CommitBarrier already is aborted or committed.

#### registerOnCommitTask

    public final void registerOnCommitTask(java.lang.Runnable task)

Registers a task that is executed once the CommitBarrier commits.

The task will be executed after the commit and will be executed by the thread that does the actual commit.

The tasks will be executed in the order they are registered and will be executed at most once. If one of the tasks throws a RuntimeException, the following will not be executed.

Parameters:
  `task` - the task that is executed once the CommitBarrier commits.
Throws:
  `java.lang.NullPointerException` - if task is null.
  `CommitBarrierOpenException` - if this CommitBarrier already is aborted or committed.

#### addJoiner

    protected final void addJoiner()

Adds a waiters.

Should only be called when the main lock is acquired.

Throws:
  `java.lang.IllegalStateException` - if the transaction isn't closed.

#### finish

    protected final void finish(Txn tx)

Finishes a Txn.

Can be called without the mainlock is acquired.

Parameters:
  `tx` - the transaction to finish

#### ensureNotDead

    protected static void ensureNotDead(Txn tx,
                     java.lang.String operation)

Ensures that a transaction is not dead.

Can be called without the mainlock is acquired.

Parameters:
  `tx` - the transaction to check.
  `operation` - the name of the operation to checks if this transaction is not dead. Needed to provide a useful message.
Throws:
  `DeadTxnException` - if tx is dead.
  `java.lang.NullPointerException` - if tx is null.

#### joinCommit

    public void joinCommit(Txn tx)
                    throws java.lang.InterruptedException

Joins this CommitBarrier with the provided transaction. If the CommitBarrier can't commit yet, the method will block.

If the CommitBarrier already is aborted or committed, the transaction is aborted.

This method is responsive to interrupts. If the waiting thread is interrupted, it will abort itself and this CommitGroup.

Parameters:
  `tx` - the Txn to commit.
Throws:
  `java.lang.InterruptedException` - if the thread is interrupted while waiting.
  `java.lang.NullPointerException` - if tx is null.
  `IllegalTxnStateException` - if the tx is no in the correct state for this operation.
  `CommitBarrierOpenException` - if this VetoCommitBarrier is committed or aborted.

#### joinCommitUninterruptibly

    public void joinCommitUninterruptibly(Txn tx)

Joins this CommitBarrier with the provided transaction. If the CommitBarrier can't commit yet, this method will block without being interruptible.

If the CommitBarrier already is aborted or committed, the transaction is aborted.

Parameters:
  `tx` - the Txn to join in the commit.
Throws:
  `java.lang.NullPointerException` - if tx is null.
  `IllegalTxnStateException` - if the tx is not in the correct state for the operation.
  `CommitBarrierOpenException` - if this VetoCommitBarrier is committed or aborted.

#### tryJoinCommit

    public boolean tryJoinCommit(Txn tx)

Tries to joins this CommitBarrier with the provided transaction. If the CommitBarrier can't commit yet, the transaction and CommitBarrier will be aborted. So this method will not block (for a long period).

If the CommitBarrier already is aborted or committed, the transaction is aborted.

Parameters:
  `tx` - the Txn that wants to join the other parties to commit with.
Returns:
  true if CountDownCommitBarrier was committed, false if aborted.
Throws:
  `CommitBarrierOpenException` - if tx or this CountDownCommitBarrier is aborted or committed.
  `java.lang.NullPointerException` - if tx is null.

#### tryJoinCommit

    public boolean tryJoinCommit(Txn tx,
                        long timeout,
                        java.util.concurrent.TimeUnit unit)
                          throws java.lang.InterruptedException

Tries to joins this CommitBarrier with the provided transaction. If the CommitBarrier can't commit yet, this call will block until one of the following things happens:

1. the CommitBarrier is committed before timeing out: the transaction also is committed
2. the CommitBarrier is aborted before timeing out: the transaction also is aborted
3. the thread is interrupted: the transaction and commit barrier also is aborted
4. the thread times out: the transaction and commit barrier are aborted

If the CommitBarrier already is aborted or committed, the transaction is aborted.

This method is responsive to interrupts. If the waiting thread is interrupted, it will abort itself and this CommitBarrier.

Parameters:
  `tx` - the Txn that wants to join the other parties to commit with.
  `timeout` - the maximum time to wait.
  `unit` - the TimeUnit for the timeout argument.
Returns:
  true if CountDownCommitBarrier was committed, false if aborted.
Throws:
  `CommitBarrierOpenException` - if tx or this CountDownCommitBarrier is aborted or committed.
  `java.lang.NullPointerException` - if tx or unit is null is null.
  `java.lang.InterruptedException` - if the calling thread is interrupted while waiting.

#### tryJoinCommitUninterruptibly

    public boolean tryJoinCommitUninterruptibly(Txn tx,
                                       long timeout,
                                       java.util.concurrent.TimeUnit unit)

Tries to joins this CommitBarrier with the provided transaction. If the CommitBarrier can't commit yet, this call will block until one of the following things happens:

1. the CommitBarrier is committed
2. the CommitBarrier is aborted

If the CommitBarrier already is aborted or committed, the transaction is aborted.

This method is not responsive to interrupts.

Parameters:
  `tx` - the Txn that wants to join the other parties to commit with.
  `timeout` - the maximum time to wait.
  `unit` - the TimeUnit for the timeout argument.
Returns:
  true if CountDownCommitBarrier was committed, false if aborted.
Throws:
  `CommitBarrierOpenException` - if tx or this CountDownCommitBarrier is aborted or committed.
  `java.lang.NullPointerException` - if tx or unit is null is null.

#### isLastParty

    protected abstract boolean isLastParty()