tryllian.are
Class ExecutionEnvironment

java.lang.Object
  tryllian.are.ExecutionEnvironment

All Implemented Interfaces:

java.io.Serializable

public class ExecutionEnvironment

extends java.lang.Object

implements java.io.Serializable

The primary point of contact between an agent and the ARE. Provides everything that an agent without special access to the ARE can use from the ARE directly. However, in order to use the ExecutionEnvironment, the caller must be registered as an agent.

That includes sending messages and requesting TimeSliceEvents in order to do things pro-actively.

All other contact with the ARE by agents without special privileges is done by contacting system agents with messages.

This class does not have public constructors, instances can only be obtained with the static get() method.

See Also:

Serialized Form

Method Summary

OutgoingMessage	createOutgoingMessage() Returns a fresh instance of OutgoingMessage to the caller, that can use it to send an message to another agent.
static ExecutionEnvironment	get() Returns the ExecutionEnvironment for the calling agent.
AddressHelper	getAddressHelper() Returns an AddressHelper.
AddressURI	getCurrentAgentAddress() Returns the current address of the calling agent.
java.util.Date	getCurrentAgentCreationDate() Returns the creation date of the DNA file of the calling agent.
IDReference	getCurrentAgentIDReference() Returns the IDReference of the calling agent.
javax.naming.Context	getJNDIContext() Returns the JNDI Initial Context which can be used for all kinds of lookups.
void	replaceAgentEventListener(AgentEventListener newListener) Replaces the AgentEventListener that is the main execution entry point for this agent; other information about the agent is unaffected.
void	requestAbortAgent() This is a very forceful method; normally agents should kill themselves by asking their place to die; death will then happen gracefully; all Routines of the agent can exit gracefully, a pre-mortem persisted version of the agent can be made, etc..
void	requestHeartbeats(boolean flag) Request notification of each system heart beat.
void	scheduleRoutine(Routine target) Schedules a Routine for running.
void	send(OutgoingMessage message) Sends a message.

Methods inherited from class java.lang.Object

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

Method Detail

get

public static ExecutionEnvironment get()

Returns the ExecutionEnvironment for the calling agent. (Where each agent can have its own ExecutionEnvironment) If the agent is currently unregistered, it will get a temporary ExecutionEnviroment instance that will not work until the agent is registered.

This method is not very efficient: you should not call it regularly in an agent, rather you should call in in the constructor of the agent or in the constructor of a library class for agents, if objects of that class are not often constructed. Otherwise, pass the instance of ExecutionEnvironment that you requested earlier as an argument to methods or constructors that are often used.

It is allowed for the ExecutionEnvironment, in cooperation with the core of the ARE, to slow down agents that call this method too frequently, by giving them events less frequently or scheduling them on lower-priority threads.

Returns:

an ExecutionEnvironment instance, never null

replaceAgentEventListener

public void replaceAgentEventListener(AgentEventListener newListener)

Replaces the AgentEventListener that is the main execution entry point for this agent; other information about the agent is unaffected. If the agent is currently processing an event, only the next event will be passed to the new AgentEventListener.

requestHeartbeats

public void requestHeartbeats(boolean flag)

Request notification of each system heart beat. A system heart beat is issued whenever every agent has had the chance to execute.

Parameters:

flag - true if the caller wants to receive notifications, false if it does not want them (anymore)

createOutgoingMessage

public OutgoingMessage createOutgoingMessage()

Returns a fresh instance of OutgoingMessage to the caller, that can use it to send an message to another agent.

Returns:

an empty OutgoingMessage object, never null

getCurrentAgentAddress

public AddressURI getCurrentAgentAddress()

Returns the current address of the calling agent.

Returns:

an AddressURI object, never null.

Throws:

java.security.AccessControlException - is the caller has no permission to call this method, i.e. because it is not an agent in the ARE.

getCurrentAgentIDReference

public IDReference getCurrentAgentIDReference()

Returns the IDReference of the calling agent.

Returns:

an IDReference object, never null

Throws:

java.security.AccessControlException - is the caller has no permission to call this method because it is not an agent in the ARE.

getCurrentAgentCreationDate

public java.util.Date getCurrentAgentCreationDate()

Returns the creation date of the DNA file of the calling agent.

Returns:

a Date object, may be null (mainly due to bug XXX).

scheduleRoutine

public void scheduleRoutine(Routine target)

Schedules a Routine for running. As soon as a new Thread becomes available, it will start running the Routine under the privileges of the agent. An agent also need special privileges to schedule a Routine.

Please note that in the current setup, an agent can have at most one Routine scheduled at any moment. Attempts to schedule a Routine while another Routine is scheduled or running results in a SecurityException.

Throws:

java.security.AccessControlException - when the agent does not have the right to schedule this Routine.

send

public void send(OutgoingMessage message)
          throws NoSuchAgentException,
                 java.lang.IllegalArgumentException

Sends a message. The data in the OutgoingMessage is sent to the receiver.

Parameters:

message - the message to send. The receiver field must be set, or an IllegalArgumentException will be thrown. The message should not be null. XXX: define further exceptions (no such recipient, etc.)

Throws:

java.lang.IllegalArgumentException - if the message is not (yet) in a state in which it can be sent, for example because some important information is missing, such as the receiver. Or, equally possible, the recipient habitat is not compatible with our habitat. Or the message contains stuff that cannot be sent to the recipient habitat, like Unicode null characters.

NoSuchAgentException - if the intended receiver should be on this platform, but could not be found.

requestAbortAgent

public void requestAbortAgent()

This is a very forceful method; normally agents should kill themselves by asking their place to die; death will then happen gracefully; all Routines of the agent can exit gracefully, a pre-mortem persisted version of the agent can be made, etc.. However, in some cases this is not possible, for example when the internal state of an agent is so messed up that sending and responding to messages is not possible anymore. This method will throw an AgentDeath error which, if uncaught, ensures that the caller never returns normally. The agent will be unregistered. All Routines will be, as far as is possible, killed.

getJNDIContext

public javax.naming.Context getJNDIContext()
                                    throws javax.naming.NamingException

Returns the JNDI Initial Context which can be used for all kinds of lookups.

Throws:

javax.naming.NamingException

getAddressHelper

public AddressHelper getAddressHelper()

Returns an AddressHelper. This allows you to resolve AddressURIs to an agent's IDReference and vice versa.