osl.manager
Class ActorImpl

java.lang.Object
  |
  +--java.lang.Thread
        |
        +--osl.manager.ActorImpl

Direct Known Subclasses:

BasicActorImpl, ShellActorImpl, StreamInputActorImpl, StreamOutputActorImpl

public abstract class ActorImpl

extends java.lang.Thread

implements java.io.Serializable

This class defines the basic functionality required of all classes which provide actor implementations. An actor implementation provides the interface used by the actor manager to do such things as deliver messages and exceptions, or instruct the actor that it should rebuild its state after a migration. Similarly, an actor implementation provides the interface by which the Actor class translates user service requests into actual service invocations on the ActorManager.

This class is an abstract extension of thread (rather than just an interface) in order to solve a technical problem involving the instantiation of user-written extensions of Actor. In particular, in order to allow user-written actors to invoke actor operations within their constructors, it is first necessary to properly initialize the Actor fields "self" and "implementor". Moreover, these fields should have at least package protection so that they are inaccessible to the user-written portion of an actor. The easy solution would be to initialize these fields by passing arguments to the actor constructor. However, since this must be done through a user-written constructor then we immediately give the user access to sensitive fields. The solution used is to take advantage of package level protection and have the Actor constructor (which is always called before any user-written constructor) consult package protected fields in the ActorImpl class. In particular, the "self" field in this class must be initialized before the actor implementation instantiates the user-written actor. Moreover, the protected status of the fields given below SHOULD NOT be weakened any further (e.g. made public) otherwise smart users will be able to mangle these fields from their constructor.

Version:

$Revision: 1.11 $ ($Date: 1998/10/05 15:47:38 $)

See Also:

ActorManager, ActorName, Actor, Serialized Form

Field Summary

protected java.lang.Class	actorClass This field holds the run-time class of the actor managed by this implementation.
static java.lang.Class	classRef A convenient constant which holds the class reference for this class.
protected ActorContext	context The context passed in the initialize method of this actor.
protected java.util.Hashtable	extensionMethods A hashtable which holds the Method structures pointing to extension methods.
protected long	nextID The ID to associate with the next request.
protected ActorName	self This field holds the name of the actor managed by this implementation.

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

ActorImpl()

Method Summary

protected abstract void	actorDeliver(ActorMsgRequest msg) This method is called by a manager to deliver a new message to the local actor.
protected abstract void	actorInitialize(ActorManager ourMgr, ActorName you, ActorCreateRequest req) This method is called by a manager to initialize an actor implementation after it is instantiated.
protected abstract void	actorPostMigrateRebuild(ActorManager ourMgr) This method is called by the new manager of an actor implementation just after migration has occurred.
static ActorMsgRequest	buildAsynchException(ActorName sender, ActorName receiver, ActorRequest cause, java.lang.Exception E) Build an asynchException message.
protected void	finalize() Output to the system log that we are being GC'd.
static boolean	formatAsynchException(ActorMsgRequest msg) Check if a message is formatted correctly for an "asynchException" message.
protected abstract ActorName	implCreate(ActorCreateRequest req) Request a new actor to be created.
protected abstract void	implDestroy(java.lang.String reason) Request to remove this actor from the system.
protected java.lang.Object	implExtension(java.lang.String name, java.lang.Object[] args) Invoke an extension provided by this implementation.
protected abstract java.lang.Object	implInvokeService(ServiceName name, java.lang.String meth, java.lang.Object[] args) Request a service invocation on the named node service.
protected abstract void	implMigrate(ActorManagerName loc) Request that this actor wishes to be migrated to a new location.
protected abstract java.lang.Object	implSend(ActorMsgRequest msg) Request a message to be sent.
protected ActorName	mgrActorCreate(ActorManager mgr, ActorCreateRequest request) Call actorCreate in a manager.
protected void	mgrActorFatalError(ActorManager mgr, java.lang.Exception e) Call actorFatalError in a manager.
protected java.lang.Object	mgrActorInvokeService(ActorManager mgr, ServiceName serviceName, java.lang.String meth, java.lang.Object[] serviceArgs) Call actorInvokeService in a manager.
protected void	mgrActorMigrate(ActorManager mgr, ActorManagerName where) Call actorMigrate in a manager.
protected void	mgrActorSend(ActorManager mgr, ActorMsgRequest message) Call actorSend in a manager.
protected void	registerExtension(java.lang.String extensionName) Register an extension method.
protected void	removeExtension(java.lang.String extensionName) Remove a previously registered extension method.
protected void	setCreatingThread(java.lang.Thread caller, ActorImpl creator) This method is used by an actor implementation to synchronize with the underlying Actor being created.
protected void	stampRequest(ActorRequest req) Stamp a request structure with a timestamp and our ID.

Methods inherited from class java.lang.Thread

activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getContextClassLoader, getName, getPriority, getThreadGroup, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, run, setContextClassLoader, setDaemon, setName, setPriority, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

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

Field Detail

self

protected ActorName self

This field holds the name of the actor managed by this implementation.

actorClass

protected java.lang.Class actorClass

This field holds the run-time class of the actor managed by this implementation.

context

protected ActorContext context

The context passed in the initialize method of this actor.

nextID

protected long nextID

The ID to associate with the next request. This is basically a timestamp.

extensionMethods

protected transient java.util.Hashtable extensionMethods

A hashtable which holds the Method structures pointing to extension methods. Note that since instances of Method are not serializable, this table must be rebuilt after migration. That is, the extending implementation will need to re-register each of its extension methods after migration.

classRef

public static java.lang.Class classRef

A convenient constant which holds the class reference for this class.

Constructor Detail

ActorImpl

public ActorImpl()

Method Detail

stampRequest

protected void stampRequest(ActorRequest req)

Stamp a request structure with a timestamp and our ID.

formatAsynchException

public static final boolean formatAsynchException(ActorMsgRequest msg)

Check if a message is formatted correctly for an "asynchException" message.

Parameters:

msg - The ActorMsgRequest to check.

Returns:

true if the message is a valid "asynchException" message, and false otherwise.

buildAsynchException

public static final ActorMsgRequest buildAsynchException(ActorName sender,
                                                         ActorName receiver,
                                                         ActorRequest cause,
                                                         java.lang.Exception E)

Build an asynchException message. It is still up to the caller to correctly stamp the message after it has been built.

Parameters:

sender - The ActorName of the sender of the message.

receiver - The ActorName of the receiver of the message.

cause - The ActorRequest giving the original request which caused the exception.

E - The Exception which was generated as a result of the request.

Returns:

An ActorMsgRequest formatted as an "asynchException" message with the given sender, receiver, cause and exception E.

registerExtension

protected void registerExtension(java.lang.String extensionName)

Register an extension method. Note that this must be done before the method may be called by internal actors. Moreover, extension methods must be re-registered after every migration since instances of Method are not serializable. Note that ALL variants of the given method name are registered. That is, only one call is necessary to register an overloaded method.

removeExtension

protected void removeExtension(java.lang.String extensionName)

Remove a previously registered extension method. Note that this method removes ALL overloaded copies of the method. This method has no effect if the named method was not registered.

setCreatingThread

protected void setCreatingThread(java.lang.Thread caller,
                                 ActorImpl creator)

This method is used by an actor implementation to synchronize with the underlying Actor being created. This is necessary to relay private information between an actor and it's creator.

mgrActorCreate

protected ActorName mgrActorCreate(ActorManager mgr,
                                   ActorCreateRequest request)
                            throws java.lang.SecurityException,
                                   RemoteCodeException

Call actorCreate in a manager.

Parameters:

mgr - The manager on which actorCreate should be invoked.

request - The ActorCreateRequest structure which describes the new actor to be created.

Returns:

The ActorName of the newly created actor.

Throws:

java.lang.SecurityException - Thrown if the class of new requested actor is not a subclass of Actor, or if the class of the new requested actor implementation is not a subclass of ActorImpl.

RemoteCodeException - Thrown for any other error encountered while attempting to perform the create. Note that this error may also be thrown asynchronously (e.g. when performing a remote create).

mgrActorSend

protected void mgrActorSend(ActorManager mgr,
                            ActorMsgRequest message)
                     throws RemoteCodeException

Call actorSend in a manager.

Parameters:

mgr - The manager on which actorSend should be invoked.

message - The ActorMsg structure which indicates the sender and receiver of the message, the method to invoke on the receiver, and any arguments to pass to the target method.

Throws:

RemoteCodeException - Thrown for any other error encountered while attempting to perform the send. This usually indicates a local error in the manager implementation rather than an error encountered at the target of the message.

mgrActorFatalError

protected void mgrActorFatalError(ActorManager mgr,
                                  java.lang.Exception e)

Call actorFatalError in a manager.

Parameters:

mgr - The manager on which actorFatalError should be called.

thrower - The ActorImpl which is signalling the fatal error.

e - The Exception which describes the fatal error encountered in the actor.

mgrActorMigrate

protected void mgrActorMigrate(ActorManager mgr,
                               ActorManagerName where)
                        throws IllegalNodeException,
                               RemoteRequestRefusedException,
                               RemoteCodeException

Call actorMigrate in a manager.

Parameters:

mgr - The manager on which actorMigrate should be called.

thrower - A reference to the ActorImpl which wishes to be migrated.

where - The ActorManagerName of the manager where this actor should be moved.

Throws:

IllegalNodeException - Thrown if the where argument does not correspond to a legal ActorManagerName.

RemoteRequestRefusedException - Thrown if the target manager of the migration refuses to accept the migrated actor.

RemoteCodeException - Thrown if the restart code after the migration throws an exception. The remote copy is destroyed in this case and the actor is treated as if it never migrated.

mgrActorInvokeService

protected java.lang.Object mgrActorInvokeService(ActorManager mgr,
                                                 ServiceName serviceName,
                                                 java.lang.String meth,
                                                 java.lang.Object[] serviceArgs)
                                          throws ServiceNotFoundException,
                                                 ServiceException

Call actorInvokeService in a manager.

Parameters:

mgr - The manager on which actorInvokeService should be called.

serviceName - The ServiceName of the service to invoke.

serviceArgs - An Object which represents the sole argument to pass to the invocation function of the service.

Returns:

An Object representing the value returned by the service invocation.

Throws:

ServiceNotFoundException - Thrown if no instance of the named service can be found on this node.

ServiceException - Thrown if the service throws an exception while processing the request.

actorInitialize

protected abstract void actorInitialize(ActorManager ourMgr,
                                        ActorName you,
                                        ActorCreateRequest req)
                                 throws java.lang.Exception

This method is called by a manager to initialize an actor implementation after it is instantiated. The manager provides a reference to itself, a reference giving the name of the new actor, and a create request describing the new Actor that should be created and managed. After calling this method, a manager will call the run method in this class to start the actor executing. Note that the protection of this method prevents it from being called external to osl.manager. This was done to prevent arbitrary classes from initializing new actors. However, managers in different packages may invoke this method using implInitialize.

Parameters:

ourMgr - The ActorManager which should be used by this actor implementation to invoke actor services.

you - The ActorName that should be used as the name of the new actor.

rtClass - The run-time Class of the user-written actor that should be instantiated by this implementation. This class will always be an extension of the Actor class.

initArgs - The array of arguments to pass to the constructor of the user-defined actor when it is instantiated.

Throws:

java.lang.Exception - The actual type of exception thrown depends on the implementation being used.

See Also:

ActorManager.implInitialize(osl.manager.ActorImpl, osl.manager.ActorName, osl.manager.ActorCreateRequest)

actorDeliver

protected abstract void actorDeliver(ActorMsgRequest msg)

This method is called by a manager to deliver a new message to the local actor. Any exceptions resulting from the processing of this message should be sent back to the original caller using an "asynchException" message. This method is protected so that it has package level protection and therefore may not be invoked directly by user-written actor code.

Parameters:

msg - The ActorMsgRequest structure to be delivered. This structure must be maintained by the actor as it is required if an exception is returned to the manager.

actorPostMigrateRebuild

protected abstract void actorPostMigrateRebuild(ActorManager ourMgr)

This method is called by the new manager of an actor implementation just after migration has occurred. The implementation is expected to perform any re-initialization necessary after a migration (e.g. rebuilding transient fields). This method will be called before the implementations thread is restarted.

Parameters:

ourMgr - A reference to the new manager of the implementation after migration has occurred.

implSend

protected abstract java.lang.Object implSend(ActorMsgRequest msg)
                                      throws RemoteCodeException

Request a message to be sent. The message argument is forwarded to the manager. If the RPC field of the message is set to true then the caller is blocked while the RPC takes place. This method is protected so that it has package level protection and therefore may not be invoked directly by user-written actor code.

Parameters:

msg - The ActorMsgRequest describing the message to send.

Returns:

If this is an RPC request, then the return value from the message call is returned. Otherwise, null is returned.

Throws:

IllegalTargetException - Thrown if the destination address of msg does not correspond to a legal actor name. Note that it is not necessary for implementations to verify that msg.dest != null since this check is already performed in Actor.sendImpl

RemoteCodeException - Thrown only if this is an RPC exception which throws an exception during invocation. An exception thrown in any other case is an error.

See Also:

Actor.send(ActorName, String), Actor.call(ActorName, String)

implCreate

protected abstract ActorName implCreate(ActorCreateRequest req)
                                 throws java.lang.SecurityException,
                                        RemoteCodeException

Request a new actor to be created. The request argument is forwarded to the manager and the returned name is passed on to the Actor caller. This method is protected so that it has package level protection and therefore may not be invoked directly by user-written actor code.

Parameters:

req - The ActorCreateRequest describing the new actor to create.

Returns:

The ActorName of the new actor.

Throws:

java.lang.SecurityException - Thrown if the behavior of the new actor is not a subclass of Actor.

RemoteCodeException - Thrown as a wrapper for any other error that is encountered while attempting the create. Note that such errors may also be thrown asynchronously.

See Also:

Actor.create(String), Actor.create(Class), Actor.create(ActorManagerName, String), Actor.create(ActorManagerName, Class)

implMigrate

protected abstract void implMigrate(ActorManagerName loc)

Request that this actor wishes to be migrated to a new location. By convention, this call is meant to indicate a request rather than serving as a notice to immediately migrate the actor. Normally, the implementation will record the request but wait to migrate the actor until the current message being processed has completed. Once this occurs the actor is migrated and restarted at its new node. This method is protected so that it has package level protection and therefore may not be invoked directly by user-written actor code.

Parameters:

loc - The ActorManagerName of the node to migrate to.

See Also:

Actor.migrate(osl.manager.ActorManagerName), Actor.cancelMigrate()

implInvokeService

protected abstract java.lang.Object implInvokeService(ServiceName name,
                                                      java.lang.String meth,
                                                      java.lang.Object[] args)
                                               throws ServiceNotFoundException,
                                                      ServiceException

Request a service invocation on the named node service. This request is forwarded to the actor manager and the appropriate return value is provided. This method is protected so that it has package level protection and therefore may not be invoked directly by user-written actor code.

Parameters:

name - The ServiceName describing the service to invoke.

args - The Object argument to pass to the service invocation function.

Returns:

The Object returned as a result of the service invocation.

Throws:

ServiceNotFoundException - Thrown if no instance of the named service can be found on this node.

ServiceException - Thrown if the service throws an exception while processing the request.

See Also:

Actor.invokeService(osl.service.ServiceName, java.lang.String)

implDestroy

protected abstract void implDestroy(java.lang.String reason)

Request to remove this actor from the system. Normally, this method will not return as the actor is immediately removed from the system. Note that any actor garbage collection process is ignored in this call so that this actor may be removed even though it is accessible by other actors.

Parameters:

reason - A String giving a "reason" for the removal. This string should normally be appended to the log for the actor before removing it from the system.

See Also:

Actor.destroy(java.lang.String)

implExtension

protected java.lang.Object implExtension(java.lang.String name,
                                         java.lang.Object[] args)
                                  throws ExtensionException

Invoke an extension provided by this implementation. Implementations register extensions using the registerExtension method. An extension consists of an otherwise protected method which an implementation wishes to export to its internal actor. Once registered, an extension may be invoked by calling implExtension which attempts to look up the method and make a direct call, returning any exception wrapped in an ExtensionException.

Parameters:

name - The name of the extension to invoke.

args - An Object[] of arguments to pass to the invoked extension. If no arguments are required, this should be an array of length 0 (i.e. NOT null). The number and format of the arguments depends on the extension being invoked.

Returns:

An Object giving the result of the extension invocation. The type of this object depends on the extension being invoked.

Throws:

ExtensionException - Thrown as a wrapper for any error which occurs while invoking the extension.

finalize

protected void finalize()
                 throws java.lang.Throwable

Output to the system log that we are being GC'd. We mainly use this for testing at the moment.

Throws:

java.lang.Throwable - This exception is thrown so that any exceptions caught in Object.finalize() are forwarded to the runtime system.

Overrides:

finalize in class java.lang.Object