osl.manager
Interface RemoteActorManager

All Known Implementing Classes:

ActorManager

public abstract interface RemoteActorManager

extends RequestClient

This interface defines the externally visible portion of the ActorManager class. In particular, actor manager implementations are expected to implement this interface in order to provide access to external services (off-node or otherwise). Typically, an instance of this interface is used to open one or more RequestHandler sessions, which provide the means for interacting with an actor manager.

Version:

$Revision: 1.4 $ ($Date: 1998/07/18 18:59:46 $)

See Also:

ActorManager, RequestHandler

Method Summary

ActorName	managerCreate(ActorCreateRequest request, ActorName newName) This method is called to request that a new local actor be created and managed by the target actor.
void	managerDeliver(ActorMsgRequest del) This method is called to indicate that a new message should be delivered to a local actor.
ActorManagerName	managerGetName() Returns the name of this actor manager.
java.lang.Object	managerInvokeService(ServiceName serviceName, java.lang.String meth, java.lang.Object[] serviceArgs) Called by other foundry modules (or remote managers) to invoke a local service.
void	managerMigrate(ActorMigrationStructure mig) This method is called to pass an actor migration request.
void	managerRegisterService(ServiceName sName, Service S) Called externally to register a new node service.
void	managerRemoveService(ServiceName sName) Called externally to remove a node service.

Methods inherited from interface osl.handler.RequestClient

handlerException

Method Detail

managerCreate

public ActorName managerCreate(ActorCreateRequest request,
                               ActorName newName)
                        throws RemoteRequestRefusedException,
                               RemoteCodeException,
                               IllegalTargetException,
                               java.lang.IllegalAccessException

This method is called to request that a new local actor be created and managed by the target actor. Both the ID properties and the site field of the request are ignored and the actor is always created locally. Unlike actorCreate, the caller may optionally specify the name of the new actor. This is done to allow more efficient implementations of remote creation where a name is immediately returned to a local actor although the creation itself is taking place asynchronously at a remote manager. Normally this method is called using the RPC features of the request handler. This is done so that the name of the new actor may be returned and so that the caller may determine when it is legal to send the new actor messages. However, this method MAY be called asynchronously (e.g. if the caller already knows the name of the new actor because the newName field has been specified) in which case other means will need to be used to determine when it is legal to send the actor messages.

Parameters:

request - An ActorCreateRequest structure describing the new actor to be created. The ID and site fields are ignored and the new actor is always created locally.

newName - An optional argument indicating the desired ActorName of the new actor. If null then a new actor name is generated, otherwise an attempt is made to use the provided name.

Returns:

The ActorName of the newly created actor. This actor is a legal target for messages once the caller has received its name.

Throws:

RemoteRequestRefusedException - Thrown if this manager decides to refuse the creation request.

RemoteCodeException - Thrown if the constructor of the new actor throws an exception.

IllegalTargetException - Thrown if the specified value for newName is non-NULL but does not correspond to a legal actor name.

java.lang.IllegalAccessException - Thrown if the requested class of the new actor does not inherit from Actor.

managerDeliver

public void managerDeliver(ActorMsgRequest del)
                    throws IllegalTargetException,
                           RemoteRequestRefusedException,
                           RemoteCodeException

This method is called to indicate that a new message should be delivered to a local actor. This method is normally called asynchronously using the exception handling mechanism of the request layer. Because messages are processed by actors asynchronously, a separate method is used to return exceptions resulting from actor message processing.

Parameters:

del - The ActorMsg structure to deliver to a local actor.

Throws:

IllegalTargetException - Thrown if either the specified target actor name is malformed, or the target is not managed locally.

RemoteRequestRefusedException - Thrown if the local manager decides to refuse the remote request.

RemoteCodeException - Thrown for any other exception encountered while attempting to deliver the message.

managerMigrate

public void managerMigrate(ActorMigrationStructure mig)
                    throws RemoteRequestRefusedException,
                           RemoteCodeException

This method is called to pass an actor migration request. An actor migration structure contains all the information necessary to reassemble an actor on the local manager including the serialized form of the actor and the actor's name. Normally, this method is called using RPC. Upon successful completion (i.e. no thrown exceptions), the caller may assume that the migrated actor is now running on the local manager. Otherwise, the migration request was not satisfied and the caller should assume that the actor did not migrate.

Parameters:

mig - The ActorMigrationStructure giving the properties of the actor to migrate.

Throws:

RemoteRequestRefusedException - Thrown if the local manager decides to refuse the migration request.

RemoteCodeException - Thrown if an error is encountered while attempting to restart the migrated actor on the local manager.

managerRegisterService

public void managerRegisterService(ServiceName sName,
                                   Service S)

Called externally to register a new node service. The service provider is responsible for providing a unique service name. Any existing service with the same name is removed.

Parameters:

sName - The ServiceName of the new service.

S - A reference to the new Service.

managerRemoveService

public void managerRemoveService(ServiceName sName)
                          throws ServiceNotFoundException

Called externally to remove a node service. An exception is thrown if the named service does not exist.

Parameters:

sName - The name of the service to remove.

Throws:

ServiceNotFoundException - Thrown if no service with the given name is associated with this manager.

managerInvokeService

public java.lang.Object managerInvokeService(ServiceName serviceName,
                                             java.lang.String meth,
                                             java.lang.Object[] serviceArgs)
                                      throws ServiceNotFoundException,
                                             ServiceException

Called by other foundry modules (or remote managers) to invoke a local service. This equivalent to the actorInvokeService method except that no check is made to ensure that the caller is an actor.

Parameters:

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.

managerGetName

public ActorManagerName managerGetName()

Returns the name of this actor manager.