osl.manager.basic
Class BasicActorImpl

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

public class BasicActorImpl

extends ActorImpl

This class defines the basic implementation of the ActorImpl class. The implementation provided here is very similar to the original ActorFoundry-0.2[alpha] implementation of the Actor class. Specifically, upon construction this implementation first discovers all of the available public methods (minus constructors) of the actor it encapsulates. Each such public method is a valid target for an external message.

After initializing itself, the implementation calls the encapsulated actor's constructor, after which messages are processed as usual. Any synchronous exceptions (that is, those that result directly from calls by the encapsulated actor) are immediately returned to the actor. Asynchronous exceptions are not yet passed back to the encapsulated actor.

Version:

$Revision: 1.15 $ ($Date: 1999/07/13 02:01:50 $)

See Also:

BasicActorManager, BasicActorName, MethodStructure, MethodStructureVector, Serialized Form

Field Summary

protected java.lang.Object[]	conArgs The array of arguments to pass to the constructor of the encapsulated actor when it is instantiated.
protected ActorCreateRequest	createReq A reference to the create request which was used to create this actor.
protected WaitQueue	mailQueue The mail queue for this actor.
ActorManagerName	managerName The ActorManagerName of our actor manager.
protected ActorManagerName	migrateTo If this field is non-null, then the actor wishes to be migrated after the current method has finished.
protected Actor	ourActor The actor instance that we manage.
protected ActorManager	ourManager The ActorManager which manages this actor.
protected java.util.Hashtable	ourMethods This hashtable hashes the names of our public methods to an array of MethodStructure instances for quick lookup during method invocation.
protected osl.manager.basic.BasicActorImpl.WaitRPCReply	scanQueue This field holds a class instance which is used to search mail queues for RPC reply messages.

Fields inherited from class osl.manager.ActorImpl

actorClass, classRef, context, extensionMethods, nextID, self

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

BasicActorImpl()

Method Summary

protected void	actorDeliver(ActorMsgRequest msg) This method is called by a manager to deliver a new message to the local actor.
protected void	actorInitialize(ActorManager ourMgr, ActorName you, ActorCreateRequest req) This method is called to initialize the actor implementation after it is instantiated.
protected void	actorPostMigrateRebuild(ActorManager ourMgr) This method is called by the new manager of an actor implementation just after migration has occurred.
protected java.lang.reflect.Constructor	findConstructor(java.lang.Class classType, java.lang.Object[] args) This function returns the appropriate constructor for building an actor class based on its type and the signatures of the arguments supplied.
protected ActorName	implCreate(ActorCreateRequest req) Request a new actor to be created.
protected void	implDestroy(java.lang.String reason) Request to remove this actor from the system.
protected java.lang.Object	implInvokeService(ServiceName name, java.lang.String meth, java.lang.Object[] args) Request a service invocation on the named node service.
protected void	implMigrate(ActorManagerName loc) Request that this actor wishes to be migrated to a new location.
protected java.lang.Object	implSend(ActorMsgRequest msg) Request a message to be sent.
protected void	initializeActor() This method initializes the standard streams for this implementation and attempts to create the Actor requested in the create message.
protected java.lang.Object	invokeMethod(java.lang.String nextMethod, java.lang.Object[] methodArgs) This method is called from run to invoke a method on this actor.
protected void	processMessage(ActorMsgRequest nextMsg) This method handles the processing of the next message on the actor's mail queue.
void	run() The run method for the basic actor implementation.

Methods inherited from class osl.manager.ActorImpl

buildAsynchException, finalize, formatAsynchException, implExtension, mgrActorCreate, mgrActorFatalError, mgrActorInvokeService, mgrActorMigrate, mgrActorSend, registerExtension, removeExtension, setCreatingThread, stampRequest

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, 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

ourActor

protected Actor ourActor

The actor instance that we manage.

conArgs

protected transient java.lang.Object[] conArgs

The array of arguments to pass to the constructor of the encapsulated actor when it is instantiated. We set this field to null after the new actor has been constructed so that this data may be GC'd.

mailQueue

protected WaitQueue mailQueue

The mail queue for this actor. This should only be modified by the manager which created this actor and the thread which schedules it.

ourManager

protected transient ActorManager ourManager

The ActorManager which manages this actor. This reference is used to access system level operations such as invoking create or send. Note that this need not be a BasicActorManager. The basic actor implementation should work fine if migrated to other manager implementations.

managerName

public transient ActorManagerName managerName

The ActorManagerName of our actor manager. Why is this public?

ourMethods

protected transient java.util.Hashtable ourMethods

This hashtable hashes the names of our public methods to an array of MethodStructure instances for quick lookup during method invocation. We initialize this table when the actor is instantiated by an ActorManager. Note that this table is transient because the things it contains (Method instances) are final and therefore can't be serialized for migration.

scanQueue

protected osl.manager.basic.BasicActorImpl.WaitRPCReply scanQueue

This field holds a class instance which is used to search mail queues for RPC reply messages. We detect these messages when the user sends an RPC request.

migrateTo

protected transient ActorManagerName migrateTo

If this field is non-null, then the actor wishes to be migrated after the current method has finished.

createReq

protected ActorCreateRequest createReq

A reference to the create request which was used to create this actor. This field may be set to null once the new internal actor is successfully created.

Constructor Detail

BasicActorImpl

public BasicActorImpl()

Method Detail

invokeMethod

protected java.lang.Object invokeMethod(java.lang.String nextMethod,
                                        java.lang.Object[] methodArgs)
                                 throws java.lang.NoSuchMethodException,
                                        java.lang.reflect.InvocationTargetException,
                                        java.lang.IllegalAccessException

This method is called from run to invoke a method on this actor. Any exception is passed up to the caller of this method. All exceptions are passed up to the caller.

Parameters:

nextMethod - The String naming the next method to invoke on the encapsulated actor.

methodArgs - An array of Objects to pass to the target method.

Returns:

The Object returned by the target method.

Throws:

java.lang.NoSuchMethodException - Thrown if no method can be found with a signature that matches nextMethod(methodArgs).

java.lang.reflect.InvocationTargetException - Thrown if an error is encountered while invoking nextMethod.

java.lang.IllegalAccessException - Thrown if the target method is inaccessible.

processMessage

protected void processMessage(ActorMsgRequest nextMsg)
                       throws java.lang.Exception

This method handles the processing of the next message on the actor's mail queue. We also inspect our local state after the message has been processed in order to determine whether or not to migrate. If migration is necessary then it is performed and we return to the caller (which should just kill us off).

Parameters:

nextMsg - The ActorMsgRequest to process.

Throws:

java.lang.Exception - Just about anything can be thrown from this method since it calls user-written code. So we just throw an instance of Exception and rely on the caller to catch it and process it appropriately.

initializeActor

protected void initializeActor()
                        throws java.lang.Exception

This method initializes the standard streams for this implementation and attempts to create the Actor requested in the create message. An exception is returned if the initialization failed.

Throws:

java.lang.Exception - A wide variety of exceptions may be thrown by this method.

run

public void run()

The run method for the basic actor implementation. This method is called after this class has been instantiated and after the actorInitialize has been called. If the actor we are managing has not yet been created, then the first thing we do is create the local actor and call its constructor. Note that we can't do this in actorInitialize because the user's constructor might invoke "send" or "create", which require an up call to the manager which can't be performed because the calling thread is the manager's, not an instance of ActorImpl. After creating the actor, the main purpose of this method is to dequeue the next ready message and call the appropriate method on the encapsulated actor. This method also suspends the actor's thread when it has no more messages to process. Because the mail queue is a WaitQueue, the sleeping thread is automatically awoken when a new message arrives.

Overrides:

run in class java.lang.Thread

findConstructor

protected java.lang.reflect.Constructor findConstructor(java.lang.Class classType,
                                                        java.lang.Object[] args)
                                                 throws java.lang.NoSuchMethodException

This function returns the appropriate constructor for building an actor class based on its type and the signatures of the arguments supplied.

Parameters:

classType - A Class describing the complete class type of the actor.

args - The set of arguments to be supplied to the constructor. If the default constructor is to be invoked, then this must be a 0 length array NOT null.

Returns:

The Constructor which should be used to instantiate the new actor.

Throws:

java.lang.NoSuchMethodException - Thrown if no matching constructor could be found using the given arguments.

actorInitialize

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

This method is called to initialize the actor implementation after it is instantiated. The caller provides the name of the new actor, the run-time class of the user-defined actor that should be instantiated, and the array of arguments that should be passed to the constructor of the new actor when it is created. This method is protected so that it has package level protection and therefore may not be invoked directly by user-written actor code.

The semantics of ActorImpl require that any exceptions which result from the creation of the actor should be thrown from this method. Therefore, the new user actor is created within this method and its constructor is called. If the user actor attempts to make a "call" to the creating actor, then a run-time exception is returned and the actor is never created. This is done because any such call never has a hope of completing as the creator is blocked waiting for the address of the new actor (and therefore can't respond to the call).

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.

req - The ActorCreateReq that requested this new actor to be created. Error messages during the creation should be sent to the "requester" stored in this request.

Throws:

java.lang.Exception - The actual exception thrown depends on the exceptions which may be thrown by the constructor of a new actor. This is a run-time rather than compile-time property.

Overrides:

actorInitialize in class ActorImpl

actorPostMigrateRebuild

protected 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.

Overrides:

actorPostMigrateRebuild in class ActorImpl

actorDeliver

protected 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 passed back to the manager using the managerMsgException method. 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.

Overrides:

actorDeliver in class ActorImpl

implSend

protected 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 as a wrapper for any error that is encountered while attempting the send. Errors which occur on the receiving end are delivered asynchronously.

Overrides:

implSend in class ActorImpl

implCreate

protected 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. For the basic implementation, the requested implementation type of the new actor is set to "BasicActorImpl".

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.

Overrides:

implCreate in class ActorImpl

implMigrate

protected 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. Passing a value of null cancels any previous migration request.

Overrides:

implMigrate in class ActorImpl

implInvokeService

protected 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.

Overrides:

implInvokeService in class ActorImpl

implDestroy

protected 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. For the "basic" implementation, we just log the reason and call mgrActorFatalError.

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.

Overrides:

implDestroy in class ActorImpl

See Also:

Actor.destroy(java.lang.String)