org.actorsguildframework
Interface Agent

All Known Implementing Classes:

DefaultAgent

public interface Agent

The Agent is a controller for actors. The agent is responsible for creating new actors, and it will coordinate the execution of messages. It also provides a number of helper methods for message implementations. In order to acquire an Agent, you must create an instance of an implementation. Currently the only implementation is DefaultAgent.

Method Summary

void	awaitAll(AsyncResult... asyncResults) Waits until all given AsyncResults are available.
void	awaitAllUntilError(AsyncResult... asyncResults) Waits until all given AsyncResults are available, and throws the WrappedException of the first AsyncResult that failed, if one failed.
AsyncResult	awaitAny(AsyncResult... asyncResults) Waits until one of the given AsyncResults is available.
<T> T	create(Class<T> actorOrBeanClass) Creates a new instance of the given Bean or Actor.
<T> T	create(Class<T> actorOrBeanClass, Props props) Creates a new instance of the given Bean or Actor and sets its properties.
void	shutdown() Tries to shut down the agent with all its threads.

Method Detail

create

<T> T create(Class<T> actorOrBeanClass)

Creates a new instance of the given Bean or Actor. Create supports the following annotations:

1. Bean
2. Prop
3. DefaultValue

Type Parameters:

T - the type of the class to create

Parameters:

actorOrBeanClass - the class to create

Returns:

the new instance

Throws:

WrappedException - if the object's constructor threw an exception

ConfigurationException - if the class is not configured correctly, or not a Bean

create

<T> T create(Class<T> actorOrBeanClass,
             Props props)

Creates a new instance of the given Bean or Actor and sets its properties. Create supports the following annotations:

1. Bean
2. Prop
3. DefaultValue

The second argument allows specifying values for the instance's properties. The value of the Props must be compatible with the class of the property. If the property is a primitive (like int), specify the wrapper type (Number sub-classes, for example Integer). create also supports type conversion for all numeric type, as well as between Character and Integer. For those properties that are not given, the method will take the defined DefaultValue, if specified, or the type's default value (null for references, 0 for number primitives, false for boolean).

Type Parameters:

T - the type of the class to create

Parameters:

actorOrBeanClass - the class to create

props - the values for the instance's properties. Null for no initial properties.

Returns:

the new instance

Throws:

WrappedException - if the object's constructor threw an exception

ConfigurationException - if the class is not configured correctly, or not a Bean

IllegalArgumentException - if there was an error in the Props (unknown property, value can not be converted) or the given class was null

awaitAll

void awaitAll(AsyncResult... asyncResults)

Waits until all given AsyncResults are available. awaitAll can be invoked from all threads, including those that do not process a message.

Parameters:

asyncResults - the list of AsyncResult instances to wait for

Throws:

IllegalArgumentException - if one of the arguments was null or the array was null

See Also:

awaitAllUntilError(AsyncResult...), awaitAny(AsyncResult...)

awaitAllUntilError

void awaitAllUntilError(AsyncResult... asyncResults)

Waits until all given AsyncResults are available, and throws the WrappedException of the first AsyncResult that failed, if one failed. awaitAll can be invoked from all threads, including those that do not process a message.

Parameters:

asyncResults - the list of AsyncResult instances to wait for

Throws:

IllegalArgumentException - if one of the arguments was null or the array was null

WrappedException - if one of the AsyncResults threw an exception, this WrappedException contains the first one from the list.

See Also:

awaitAll(AsyncResult...)

awaitAny

AsyncResult awaitAny(AsyncResult... asyncResults)

Waits until one of the given AsyncResults is available. awaitAny can be invoked from all threads, including those that do not process a message.

Parameters:

asyncResults - the list of AsyncResult instances to wait for

Returns:

the AsyncResult that is ready, null for empty lists

Throws:

IllegalArgumentException - if one of the arguments was null

See Also:

awaitAll(AsyncResult...)

shutdown

void shutdown()

Tries to shut down the agent with all its threads. Messages that have not been processed yet will not be processed.

This call is useful if you want to terminate your Java application. Without it, the Agent's non-daemon threads may keep the application from terminating. A safer alternative to shutdown may be calling System.exit(int), as there is no guarantee that shutdown can terminate all threads.

A agent and its actors must not be used after calling this method. The behaviour would be undefined.