Package co.paralleluniverse.actors.behaviors

Class RequestReplyHelper

java.lang.Object

co.paralleluniverse.actors.behaviors.RequestReplyHelper

public final class RequestReplyHelper
extends java.lang.Object

This class contains static methods that implement a request-reply pattern with actors. These methods can be used to communicate with actors by other actors, or even by non-actor strands.

Method Summary

Modifier and Type	Method	Description
static <V,M extends RequestMessage<V>> V	call(ActorRef<? super M> actor, M m)	Sends a request message to an actor, awaits a response value and returns it.
static <V> V	call(ActorRef actor, RequestMessage<V> m, long timeout, java.util.concurrent.TimeUnit unit)	Sends a request message to an actor, awaits a response value (but no longer than the given timeout) and returns it.
static <V> V	call(ActorRef actor, RequestMessage<V> m, Timeout timeout)	Sends a request message to an actor, awaits a response value (but no longer than the given timeout) and returns it.
static <Message> ActorRef<Message>	from()	Returns an ActorRef that should be used as the from property of a RequestMessage.
static java.lang.Object	makeId()	Generates a random, probably unique, message identifier.
static <V> void	reply(RequestMessage<V> req, V result)	Replies with a result to a RequestMessage.
static void	replyError(RequestMessage<?> req, java.lang.Throwable e)	Replies with an exception to a RequestMessage.
static void	setDefaultTimeout(long timeout, java.util.concurrent.TimeUnit unit)	Sets a default timeout for non-timed calls on this strand.

Methods inherited from class java.lang.Object

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

Method Detail

makeId

public static java.lang.Object makeId()

Generates a random, probably unique, message identifier. This method simply calls ActorUtil.randtag().

Returns:

a newly allocated, probably unique, message identifier.

setDefaultTimeout

public static void setDefaultTimeout(long timeout,
                                     java.util.concurrent.TimeUnit unit)

Sets a default timeout for non-timed calls on this strand. Non-timed calls that take longer than the default timeout, will throw a TimeoutException wrapped in a RuntimeException. Timed calls (those that take a timeout parameter) will not be affected.

This method only affects the current strand.

Parameters:

timeout - the timeout duration

unit - the time unit of the timeout, or null to unset.

from

public static <Message> ActorRef<Message> from()

Returns an ActorRef that should be used as the from property of a RequestMessage. If called from an actor strand, this method returns the current actor. If not, it creates a temporary faux-actor that will be used internally to receive the response, even if the current strand is not running an actor.

Type Parameters:

Message -

Returns:

an ActorRef that should be used as the from property of a request, even if not called from within an actor.

call

public static <V,M extends RequestMessage<V>> V call(ActorRef<? super M> actor,
                                                           M m)
                                                    throws java.lang.InterruptedException,
                                                           SuspendExecution

Sends a request message to an actor, awaits a response value and returns it. This method can be called by any code, even non-actor code. If the actor responds with an error message, a RuntimeException will be thrown by this method.
The message's id and from properties may be left unset.

This method should be used as in the following example (assuming a String return value:

 
 String res = call(actor, new MyRequest());
 

In the example, MyRequest extends RequestMessage. Note how the result of the from method is passed to the request's constructor, but the message ID isn't.

Type Parameters:

V - the return value's type

Parameters:

actor - the actor to which the request is sent

m - the RequestMessage, whose id and from properties may be left unset.

Returns:

the value sent by the actor as a response

Throws:

java.lang.RuntimeException - if the actor responds with an error message, its contained exception will be thrown, possibly wrapped by a RuntimeException, or if a default timeout has been set and has expired.

java.lang.InterruptedException

SuspendExecution

call

public static <V> V call(ActorRef actor,
                         RequestMessage<V> m,
                         long timeout,
                         java.util.concurrent.TimeUnit unit)
                  throws java.util.concurrent.TimeoutException,
                         java.lang.InterruptedException,
                         SuspendExecution

Sends a request message to an actor, awaits a response value (but no longer than the given timeout) and returns it. This method can be called by any code, even non-actor code. If the actor responds with an error message, a RuntimeException will be thrown by this method.
The message's id and from properties may be left unset.

This method should be used as in the following example (assuming a String return value:

 
 String res = call(actor, new MyRequest());
 

In the example, MyRequest extends RequestMessage. Note how the result of the from method is passed to the request's constructor, but the message ID isn't.

Type Parameters:

V - the return value's type

Parameters:

actor - the actor to which the request is sent

timeout - the maximum duration to wait for a response

unit - the time unit of the timeout

Returns:

the value sent by the actor as a response

Throws:

java.lang.RuntimeException - if the actor responds with an error message, its contained exception will be thrown, possibly wrapped by a RuntimeException.

java.util.concurrent.TimeoutException - if the timeout expires before a response is received from the actor.

java.lang.InterruptedException

SuspendExecution

call

public static <V> V call(ActorRef actor,
                         RequestMessage<V> m,
                         Timeout timeout)
                  throws java.util.concurrent.TimeoutException,
                         java.lang.InterruptedException,
                         SuspendExecution

Sends a request message to an actor, awaits a response value (but no longer than the given timeout) and returns it. This method can be called by any code, even non-actor code. If the actor responds with an error message, a RuntimeException will be thrown by this method.
The message's id and from properties may be left unset.

This method should be used as in the following example (assuming a String return value:

 
 String res = call(actor, new MyRequest());
 

In the example, MyRequest extends RequestMessage. Note how the result of the from method is passed to the request's constructor, but the message ID isn't.

Type Parameters:

V - the return value's type

Parameters:

actor - the actor to which the request is sent

timeout - the method will not block for longer than the amount remaining in the Timeout

Returns:

the value sent by the actor as a response

Throws:

java.lang.RuntimeException - if the actor responds with an error message, its contained exception will be thrown, possibly wrapped by a RuntimeException.

java.util.concurrent.TimeoutException - if the timeout expires before a response is received from the actor.

java.lang.InterruptedException

SuspendExecution

reply

public static <V> void reply(RequestMessage<V> req,
                             V result)
                      throws SuspendExecution

Replies with a result to a RequestMessage. If the request has been sent by a call to call, the result argument will be the value returned by call. This method should only be called by an actor.

Internally this method uses a ValueResponseMessage to send the reply.

Parameters:

req - the request we're responding to

result - the result of the request

Throws:

SuspendExecution

replyError

public static void replyError(RequestMessage<?> req,
                              java.lang.Throwable e)
                       throws SuspendExecution

Replies with an exception to a RequestMessage. If the request has been sent by a call to call, the e argument will be the exception thrown by call (possibly wrapped by a RuntimeException). This method should only be called by an actor.

Internally this method uses an ErrorResponseMessage to send the reply.

Parameters:

req - the request we're responding to

e - the error the request has caused

Throws:

SuspendExecution