akka.transactor
Class Coordinated

java.lang.Object
  extended by akka.transactor.Coordinated

public class Coordinated
extends java.lang.Object

Coordinated is a message wrapper that adds a CommitBarrier for explicitly coordinating transactions across actors or threads.

Creating a Coordinated will create a commit barrier with initially one member. For each member in the coordination set a transaction is expected to be created using the coordinated atomic method, or the coordination cancelled using the cancel method.

The number of included members must match the number of transactions, otherwise a successful transaction cannot be coordinated.

To start a new coordinated transaction set that you will also participate in just create a Coordinated object:


 val coordinated = Coordinated()
 

To start a coordinated transaction that you won't participate in yourself you can create a Coordinated object with a message and send it directly to an actor. The recipient of the message will be the first member of the coordination set:


 actor ! Coordinated(Message)
 

To receive a coordinated message in an actor simply match it in a case statement:


 def receive = {
   case coordinated @ Coordinated(Message) => ...
 }
 

To include another actor in the same coordinated transaction set that you've created or received, use the apply method on that object. This will increment the number of parties involved by one and create a new Coordinated object to be sent.


 actor ! coordinated(Message)
 

To enter the coordinated transaction use the atomic method of the coordinated object:


 coordinated.atomic { implicit txn =>
   // do something in transaction ...
 }
 

The coordinated transaction will wait for the other transactions before committing. If any of the coordinated transactions fail then they all fail.

See Also:
akka.transactor.Transactor} for an actor that implements coordinated transactions

Constructor Summary
Coordinated(java.lang.Object message, scala.concurrent.stm.CommitBarrier.Member member)
           
Coordinated(Timeout timeout)
           
 
Method Summary
 Coordinated apply(java.lang.Object msg)
          Create a new Coordinated object and increment the number of members by one.
<A> A
atomic(java.util.concurrent.Callable<A> callable)
          Java API: coordinated atomic method that accepts a java.util.concurrent.Callable.
<A> A
atomic(scala.Function1<scala.concurrent.stm.InTxn,A> body)
          Delimits the coordinated transaction.
 void atomic(java.lang.Runnable runnable)
          Java API: coordinated atomic method that accepts a java.lang.Runnable.
 void await()
          An empty coordinated atomic block.
 void cancel(java.lang.Object info)
          Cancel this Coordinated transaction.
 Coordinated coordinate(java.lang.Object msg)
          Java API: create a new Coordinated object and increment the number of members by one.
 java.lang.Object getMessage()
          Java API: get the message for this Coordinated.
 java.lang.Object message()
           
 Coordinated noIncrement(java.lang.Object msg)
          Create a new Coordinated object but *do not* increment the number of members by one.
static scala.Option<java.lang.Object> unapply(Coordinated c)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Coordinated

public Coordinated(java.lang.Object message,
                   scala.concurrent.stm.CommitBarrier.Member member)

Coordinated

public Coordinated(Timeout timeout)
Method Detail

unapply

public static scala.Option<java.lang.Object> unapply(Coordinated c)
Parameters:
c - - a Coordinated to be unapplied
Returns:
the message associated with the given Coordinated

message

public java.lang.Object message()

apply

public Coordinated apply(java.lang.Object msg)
Create a new Coordinated object and increment the number of members by one. Use this method to ''pass on'' the coordination.


noIncrement

public Coordinated noIncrement(java.lang.Object msg)
Create a new Coordinated object but *do not* increment the number of members by one. Only use this method if you know this is what you need.


getMessage

public java.lang.Object getMessage()
Java API: get the message for this Coordinated.


coordinate

public Coordinated coordinate(java.lang.Object msg)
Java API: create a new Coordinated object and increment the number of members by one. Use this method to ''pass on'' the coordination.


atomic

public <A> A atomic(scala.Function1<scala.concurrent.stm.InTxn,A> body)
Delimits the coordinated transaction. The transaction will wait for all other transactions in this coordination before committing. The timeout is specified when creating the Coordinated.

Throws:
CoordinatedTransactionException - if the coordinated transaction fails.

atomic

public void atomic(java.lang.Runnable runnable)
Java API: coordinated atomic method that accepts a java.lang.Runnable. Delimits the coordinated transaction. The transaction will wait for all other transactions in this coordination before committing. The timeout is specified when creating the Coordinated.

Throws:
CoordinatedTransactionException - if the coordinated transaction fails.

atomic

public <A> A atomic(java.util.concurrent.Callable<A> callable)
Java API: coordinated atomic method that accepts a java.util.concurrent.Callable. Delimits the coordinated transaction. The transaction will wait for all other transactions in this coordination before committing. The timeout is specified when creating the Coordinated.

Throws:
CoordinatedTransactionException - if the coordinated transaction fails.

await

public void await()
An empty coordinated atomic block. Can be used to complete the number of members involved and wait for all transactions to complete.


cancel

public void cancel(java.lang.Object info)
Cancel this Coordinated transaction.