akka.contrib.pattern
Class ReliableProxy

java.lang.Object
  extended by akka.contrib.pattern.ReliableProxy
All Implemented Interfaces:
Actor, ActorLogging, FSM<ReliableProxy.State,scala.collection.immutable.Vector<ReliableProxy.Message>>, Listeners

public class ReliableProxy
extends java.lang.Object
implements Actor, FSM<ReliableProxy.State,scala.collection.immutable.Vector<ReliableProxy.Message>>

A ReliableProxy is a means to wrap a remote actor reference in order to obtain certain improved delivery guarantees:

- as long as none of the JVMs crashes and the proxy and its remote-deployed peer are not forcefully terminated or restarted, no messages will be lost - messages re-sent due to the first point will not be delivered out-of-order, message ordering is preserved

These guarantees are valid for the communication between the two end-points of the reliable “tunnel”, which usually spans an unreliable network. Delivery from the remote end-point to the target actor is still subject to in-JVM delivery semantics (i.e. not strictly guaranteed due to possible OutOfMemory situations or other VM errors).

You can create a reliable connection like this:


 val proxy = context.actorOf(Props(new ReliableProxy(target)))
 
or in Java:

 final ActorRef proxy = getContext().actorOf(new Props(new UntypedActorFactory() {
   public Actor create() {
     return new ReliableProxy(target);
   }
 }));
 

'''''Please note:''''' the tunnel is uni-directional, and original sender information is retained, hence replies by the wrapped target reference will go back in the normal “unreliable” way unless also secured by a ReliableProxy from the remote end.

==Message Types==

This actor is an FSM, hence it offers the service of transition callbacks to those actors which subscribe using the SubscribeTransitionCallBack and UnsubscribeTransitionCallBack messages; see FSM for more documentation. The proxy will transition into ReliableProxy.Active state when ACKs are outstanding and return to the ReliableProxy.Idle state when every message send so far has been confirmed by the peer end-point. Any other message type sent to this actor will be delivered via a remote-deployed child actor to the designated target. Message types declared in the companion object are for internal use only and not to be sent from the outside.

==Failure Cases==

All failures of either the local or the remote end-point are escalated to the parent of this actor; there are no specific error cases which are predefined.

==Arguments==

'''''target''''' is the ActorRef to which all messages will be forwarded which are sent to this actor. It can be any type of actor reference, but the “remote” tunnel endpoint will be deployed on the node where the target ref points to.

'''''retryAfter''''' is the ACK timeout after which all outstanding messages will be resent. There is not limit on the queue size or the number of retries.


Nested Class Summary
static class ReliableProxy.Ack
           
static class ReliableProxy.Ack$
           
static class ReliableProxy.Active$
           
static class ReliableProxy.Idle$
           
static class ReliableProxy.Message
           
static class ReliableProxy.Message$
           
static class ReliableProxy.Receiver
           
static interface ReliableProxy.State
           
static class ReliableProxy.Tick$
           
 
Nested classes/interfaces inherited from interface akka.actor.Actor
Actor.emptyBehavior$
 
Nested classes/interfaces inherited from interface akka.actor.FSM
FSM.$minus$greater$, FSM.CurrentState<S>, FSM.CurrentState$, FSM.Event, FSM.Event$, FSM.Failure, FSM.Failure$, FSM.LogEntry<S,D>, FSM.LogEntry$, FSM.Normal$, FSM.NullFunction$, FSM.Reason, FSM.Shutdown$, FSM.State$, FSM.StateTimeout$, FSM.StopEvent, FSM.StopEvent$, FSM.SubscribeTransitionCallBack, FSM.SubscribeTransitionCallBack$, FSM.TransformHelper, FSM.Transition<S>, FSM.Transition$, FSM.UnsubscribeTransitionCallBack, FSM.UnsubscribeTransitionCallBack$
 
Constructor Summary
ReliableProxy(ActorRef target, scala.concurrent.duration.FiniteDuration retryAfter)
           
 
Method Summary
static ReliableProxy.Active$ active()
           
static int compare(int a, int b)
          Wrap-around aware comparison of integers: differences limited to 2^31-1 in magnitude will work correctly.
static ReliableProxy.Idle$ idle()
           
 int nextSerial()
           
static Props receiver(ActorRef target)
           
 void scheduleTick()
           
 ReliableProxy.Message send(java.lang.Object msg)
           
 OneForOneStrategy supervisorStrategy()
          User overridable definition the strategy to use for supervising child actors.
 ActorRef tunnel()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface akka.actor.Actor
context, noSender, postRestart, postStop, preRestart, preStart, receive, self, sender, unhandled
 
Methods inherited from interface akka.actor.FSM
applyState, cancelTimer, currentState, debugEvent, generation, handleEvent, handleEventDefault, handleTransition, initialize, makeTransition, nextState, nextStateData, onTermination, onTransition, postStop, processEvent, processMsg, receive, register, setStateTimeout, setTimer, startWith, stateData, stateFunctions, stateName, StateTimeout, stateTimeouts, stay, stop, stop, stop, terminate, terminateEvent, timeoutFuture, timerGen, timers, total2pf, transform, transitionEvent, when, whenUnhandled
 
Methods inherited from interface akka.routing.Listeners
gossip, listenerManagement, listeners
 
Methods inherited from interface akka.actor.ActorLogging
log
 

Constructor Detail

ReliableProxy

public ReliableProxy(ActorRef target,
                     scala.concurrent.duration.FiniteDuration retryAfter)
Method Detail

compare

public static int compare(int a,
                          int b)
Wrap-around aware comparison of integers: differences limited to 2^31-1 in magnitude will work correctly.


receiver

public static Props receiver(ActorRef target)

idle

public static ReliableProxy.Idle$ idle()

active

public static ReliableProxy.Active$ active()

tunnel

public ActorRef tunnel()

supervisorStrategy

public OneForOneStrategy supervisorStrategy()
Description copied from interface: Actor
User overridable definition the strategy to use for supervising child actors.

Specified by:
supervisorStrategy in interface Actor

scheduleTick

public void scheduleTick()

nextSerial

public int nextSerial()

send

public ReliableProxy.Message send(java.lang.Object msg)