Package co.paralleluniverse.actors.behaviors

Class BehaviorActor

java.lang.Object

co.paralleluniverse.actors.ActorImpl<Message>

co.paralleluniverse.actors.Actor<java.lang.Object,java.lang.Void>

co.paralleluniverse.actors.behaviors.BehaviorActor

All Implemented Interfaces:

ActorBuilder<java.lang.Object,java.lang.Void>, Joinable<java.lang.Void>, Port<java.lang.Object>, PortAutoCloseable, ReceivePort<java.lang.Object>, Stranded, SuspendableCallable<java.lang.Void>, java.io.Serializable, java.lang.AutoCloseable

Direct Known Subclasses:

EventSourceActor, FiniteStateMachineActor, ServerActor, SupervisorActor

public abstract class BehaviorActor
extends Actor<java.lang.Object,java.lang.Void>
implements java.io.Serializable

A general behavior-actor class, extended by all behaviors. Behaviors are actor templates encapsulating common useful actor patterns. This provides standard, sane, actor lifecycle methods, as well as other useful services (like a logger object).

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class co.paralleluniverse.actors.ActorImpl

ActorImpl.ActorLifecycleListener

Nested classes/interfaces inherited from interface co.paralleluniverse.strands.channels.ReceivePort

ReceivePort.EOFException

Field Summary

Fields inherited from class co.paralleluniverse.actors.ActorImpl

flightRecorder, ref

Constructor Summary

Constructors

Modifier	Constructor	Description
	BehaviorActor()	Creates a new behavior actor.
	BehaviorActor(Initializer initializer)	Creates a new behavior actor.
	BehaviorActor(Initializer initializer, MailboxConfig mailboxConfig)	Creates a new behavior actor.
	BehaviorActor(MailboxConfig mailboxConfig)	Creates a new behavior actor.
	BehaviorActor(java.lang.String name)	Creates a new behavior actor.
	BehaviorActor(java.lang.String name, Initializer initializer)	Creates a new behavior actor.
	BehaviorActor(java.lang.String name, Initializer initializer, MailboxConfig mailboxConfig)	Creates a new behavior actor.
protected	BehaviorActor(java.lang.String name, Initializer initializer, Strand strand, MailboxConfig mailboxConfig)	Creates a new behavior actor.
	BehaviorActor(java.lang.String name, MailboxConfig mailboxConfig)	Creates a new behavior actor.

Method Summary

Modifier and Type	Method	Description
protected void	behavior()	Called by doRun() as the body of the logic.
protected void	checkCodeSwap()	Tests whether this actor has been upgraded via hot code-swapping.
protected java.lang.Void	doRun()	An actor must implement this method, which contains the actor's logic.
protected Initializer	getInitializer()	The initializer passed at construction which performs initialization and termination.
protected java.lang.Object	handleLifecycleMessage(LifecycleMessage m)	This method is called by this class during a call to any of the receive methods if a LifecycleMessage is found in the mailbox.
protected void	handleMessage(java.lang.Object message)	Called by the default behavior() method to handle each incoming message.
protected void	init()	Called by onStart to initialize the actor.
boolean	isRunning()
abstract org.slf4j.Logger	log()	The Logger object associated with this actor.
protected Behavior	makeRef(ActorRef<java.lang.Object> ref)
protected void	onStart()	This method is called by the BehaviorActor at the beginning of doRun().
protected void	onTerminate(java.lang.Throwable cause)	This method is called by the BehaviorActor at the end of doRun().
Behavior	ref()	Returns the ActorRef to this actor, if it has been started.
protected Behavior	self()	Returns the ActorRef to this actor, if it has been started.
protected void	shutdown()	Causes this actor to shut down.
Behavior	spawn()	Starts a new fiber and runs the actor in it.
Behavior	spawn(FiberFactory ff)	Starts a new fiber using the given scheduler and runs the actor in it.
Behavior	spawn(StrandFactory sf)	Starts a new fiber using the given scheduler and runs the actor in it.
Behavior	spawnThread()	Starts a new thread and runs the actor in it.
protected void	terminate(java.lang.Throwable cause)	Called by onTerminate to terminate the actor.

Methods inherited from class co.paralleluniverse.actors.Actor

addLifecycleListener, build, checkThrownIn, close, currentActor, filterMessage, get, get, getActor, getDeathCause, getMonitor, getName, getQueueLength, getStrand, hire, hire, internalSend, internalSendNonSuspendable, interrupt, isClosed, isDone, isInActor, isRegistered, isStarted, join, join, link, linked, mailbox, migrate, migrateAndRestart, monitor, monitorAddDeath, monitorAddMessage, monitorResetSkippedMessages, monitorSkippedMessage, newActor, newActor, onCodeChange, readResolve, receive, receive, receive, register, register, reinstantiate, removeLifecycleListener, removeObserverListeners, run, sendSync, setForwardWatch, setMonitor, setName, setStrand, start, stopMonitor, throwIn, toString, tryReceive, trySend, unlink, unlinked, unregister, unwatch, verifyInActor, verifyOnActorStrand, watch, writeReplace

Methods inherited from class co.paralleluniverse.actors.ActorImpl

close, getLifecycleListener, getMailbox, isRecordingLevel, record, record, record, record, record, record, record, sendOrInterrupt

Methods inherited from class java.lang.Object

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

Constructor Detail

BehaviorActor

protected BehaviorActor(java.lang.String name,
                        Initializer initializer,
                        Strand strand,
                        MailboxConfig mailboxConfig)

Creates a new behavior actor.

Parameters:

name - the actor name (may be null).

initializer - an optional delegate object that will be run upon actor initialization and termination. May be null.

strand - this actor's strand.

mailboxConfig - this actor's mailbox settings.

BehaviorActor

public BehaviorActor(java.lang.String name,
                     Initializer initializer,
                     MailboxConfig mailboxConfig)

Creates a new behavior actor.

Parameters:

name - the actor name (may be null).

initializer - an optional delegate object that will be run upon actor initialization and termination. May be null.

mailboxConfig - this actor's mailbox settings.

BehaviorActor

public BehaviorActor(java.lang.String name,
                     Initializer initializer)

Creates a new behavior actor.

Parameters:

name - the actor name (may be null).

initializer - an optional delegate object that will be run upon actor initialization and termination. May be null.

BehaviorActor

public BehaviorActor(Initializer initializer,
                     MailboxConfig mailboxConfig)

Creates a new behavior actor.

Parameters:

initializer - an optional delegate object that will be run upon actor initialization and termination. May be null.

mailboxConfig - this actor's mailbox settings.

BehaviorActor

public BehaviorActor(Initializer initializer)

Creates a new behavior actor.

Parameters:

initializer - an optional delegate object that will be run upon actor initialization and termination. May be null.

BehaviorActor

public BehaviorActor(java.lang.String name,
                     MailboxConfig mailboxConfig)

Creates a new behavior actor.

Parameters:

name - the actor name (may be null).

mailboxConfig - this actor's mailbox settings.

BehaviorActor

public BehaviorActor(java.lang.String name)

Creates a new behavior actor.

Parameters:

name - the actor name (may be null).

BehaviorActor

public BehaviorActor(MailboxConfig mailboxConfig)

Creates a new behavior actor.

Parameters:

mailboxConfig - this actor's mailbox settings.

BehaviorActor

public BehaviorActor()

Creates a new behavior actor.

Method Detail

makeRef

protected Behavior makeRef(ActorRef<java.lang.Object> ref)

Overrides:

makeRef in class Actor<java.lang.Object,java.lang.Void>

ref

public Behavior ref()

Description copied from class: Actor

Returns the ActorRef to this actor, if it has been started.

Overrides:

ref in class Actor<java.lang.Object,java.lang.Void>

Returns:

the ActorRef of this actor if it has been started, or null otherwise.

self

protected Behavior self()

Description copied from class: Actor

Returns the ActorRef to this actor, if it has been started.

Overrides:

self in class Actor<java.lang.Object,java.lang.Void>

Returns:

the ActorRef of this actor if it has been started, or null otherwise.

spawn

public Behavior spawn(StrandFactory sf)

Description copied from class: Actor

Starts a new fiber using the given scheduler and runs the actor in it. The fiber's name will be set to this actor's name.

Overrides:

spawn in class Actor<java.lang.Object,java.lang.Void>

Parameters:

sf - the factory (or scheduler) that will be used to create the actor's fiber.

Returns:

This actors' ActorRef

spawn

public Behavior spawn(FiberFactory ff)

Description copied from class: Actor

Starts a new fiber using the given scheduler and runs the actor in it. The fiber's name will be set to this actor's name.

Overrides:

spawn in class Actor<java.lang.Object,java.lang.Void>

Parameters:

ff - the factory (or scheduler) that will be used to create the actor's fiber.

Returns:

This actors' ActorRef

spawn

public Behavior spawn()

Description copied from class: Actor

Starts a new fiber and runs the actor in it. The fiber's name will be set to this actor's name.

Overrides:

spawn in class Actor<java.lang.Object,java.lang.Void>

Returns:

This actors' ActorRef

spawnThread

public Behavior spawnThread()

Description copied from class: Actor

Starts a new thread and runs the actor in it. The fiber's name will be set to this actor's name.

Overrides:

spawnThread in class Actor<java.lang.Object,java.lang.Void>

Returns:

This actors' ActorRef

shutdown

protected void shutdown()

Causes this actor to shut down.

getInitializer

protected Initializer getInitializer()

The initializer passed at construction which performs initialization and termination.

onStart

protected void onStart()
                throws java.lang.InterruptedException,
                       SuspendExecution

This method is called by the BehaviorActor at the beginning of doRun(). By default, this method calls init().

Throws:

java.lang.InterruptedException

SuspendExecution

onTerminate

protected void onTerminate(java.lang.Throwable cause)
                    throws java.lang.InterruptedException,
                           SuspendExecution

This method is called by the BehaviorActor at the end of doRun(). By default, this method calls terminate().

Throws:

java.lang.InterruptedException

SuspendExecution

init

protected void init()
             throws java.lang.InterruptedException,
                    SuspendExecution

Called by onStart to initialize the actor. By default, this method calls initializer.init() if the initializer in non-null; otherwise it does nothing.

Throws:

java.lang.InterruptedException

SuspendExecution

terminate

protected void terminate(java.lang.Throwable cause)
                  throws SuspendExecution

Called by onTerminate to terminate the actor. By default, this method calls initializer.terminate if the initializer in non-null; otherwise it does nothing.

Throws:

SuspendExecution

log

public abstract org.slf4j.Logger log()

The Logger object associated with this actor.

behavior

protected void behavior()
                 throws java.lang.InterruptedException,
                        SuspendExecution

Called by doRun() as the body of the logic. By default, this implementation runs code similar to:

 
   while (isRunning())
       handleMessage(receive());
 

Throws:

java.lang.InterruptedException

SuspendExecution

handleMessage

protected void handleMessage(java.lang.Object message)
                      throws java.lang.InterruptedException,
                             SuspendExecution

Called by the default behavior() method to handle each incoming message. By default, this method does nothing.

Parameters:

message - the message received by the actor.

Throws:

java.lang.InterruptedException

SuspendExecution

checkCodeSwap

protected void checkCodeSwap()
                      throws SuspendExecution

Description copied from class: Actor

Tests whether this actor has been upgraded via hot code-swapping. If a new version of this actor is found, this method never returns (a special Error is thrown which causes the actor to restart).

Overrides:

checkCodeSwap in class Actor<java.lang.Object,java.lang.Void>

Throws:

SuspendExecution

isRunning

public boolean isRunning()

doRun

protected java.lang.Void doRun()
                        throws java.lang.InterruptedException,
                               SuspendExecution

An actor must implement this method, which contains the actor's logic. This method begins executing on the actor's strand.

Upon a hot code-swap, this method is re-executed, so it is this method's responsibility to check this actor's state (which may not be blank after a code-swap) when it begins.

This implementation calls onStart() when it begins, behavior() for the body, and onTerminate() upon termination. The implementation runs code similar to the following:

 
   try {
       onStart();
       behavior();
   } catch (InterruptedException e) {
       if (shutdownCalled) {
           onTerminate(null);
           return null;
       } else {
           onTerminate(e);
           throw e;
       }
   } catch (Exception e) {
       log().info("Exception!", e);
       onTerminate(e);
       throw Exceptions.rethrow(e);
   }
   onTerminate(null);
 

Specified by:

doRun in class Actor<java.lang.Object,java.lang.Void>

Returns:

The actor's return value, which can be obtained with Actor.get().

Throws:

java.lang.InterruptedException

SuspendExecution

handleLifecycleMessage

protected java.lang.Object handleLifecycleMessage(LifecycleMessage m)

This method is called by this class during a call to any of the receive methods if a LifecycleMessage is found in the mailbox. By default, if the message is an ExitMessage and its watch is null, i.e. it's a result of a link rather than a watch, it will throw a LifecycleException, which will, in turn, cause this exception to be thrown by the call to receive. This method is not allowed to block. If you want to block as a result of a lifecycle message, return the message from this method (rather than returning null), and have it processed by the caller to receive.

This implementation respects ShutdownMessage and, upon receiving it, calls shutdown().

Overrides:

handleLifecycleMessage in class Actor<java.lang.Object,java.lang.Void>

Parameters:

m - the message

Returns:

null if the message has been processed and should not be returned by receive