osl.service.shell
Class ShellActorImpl

java.lang.Object
  |
  +--java.lang.Thread
        |
        +--osl.manager.ActorImpl
              |
              +--osl.service.shell.ShellActorImpl

public class ShellActorImpl

extends ActorImpl

This class acts as the actor interface for sessions created by the Shell service. In particular, each shell session is associated with its own ShellActorImpl. A session uses the implementation to receive incoming messages as well as submit requests for sending messages or creating actors. Note that instances of ShellActorImpl can not be migrated.

Version:

$Revision: 1.6 $ ($Date: 1999/01/19 18:43:36 $)

See Also:

Shell, Serialized Form

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

ShellActorImpl()

Method Summary

protected void	actorDeliver(ActorMsgRequest msg) Receive a new message from our manager.
protected void	actorInitialize(ActorManager ourMgr, ActorName you, ActorCreateRequest req) This method initializes a new shell actor implementation which will be associated with a particular ShellSession.
protected void	actorPostMigrateRebuild(ActorManager ourMgr) As ShellActorImpl can not migrate, this method should never be called.
java.lang.Integer	available() Return the number of bytes that can be read from the internal input stream without blocking.
void	available(ActorName client, java.lang.String method) Determine the number of bytes that can be read from the internal input stream without blocking, and send the result to the specified caller.
void	close() Close the internal input stream.
void	close(java.io.OutputStream out) Close the internal output stream.
void	flush(java.io.OutputStream out) Flush the internal output stream.
protected ActorName	implCreate(ActorCreateRequest req) Request a new actor to be created.
protected void	implDestroy(java.lang.String reason) Destroy the shell actor.
protected java.lang.Object	implInvokeService(ServiceName name, java.lang.String meth, java.lang.Object[] args) Invoke a service on behalf of the associated shell session.
protected void	implMigrate(ActorManagerName loc) This method should never be invoked and results in an immediate fatal error.
protected java.lang.Object	implSend(ActorMsgRequest msg) Request that a message be sent.
void	mark(java.lang.Integer readlimit) Mark the current position in the internal stream.
java.lang.Boolean	markSupported() Test if the internal input stream supports the mark and reset methods.
void	markSupported(ActorName client, java.lang.String method) Test if the internal input stream supports the mark and reset methods.
void	print(java.io.OutputStream out, java.lang.String s) Print a string to the output stream.
void	println(java.io.OutputStream out, java.lang.String s) Print a string followed by a newline character.
void	read(ActorName client, java.lang.String method, java.lang.Integer max) Read an array of bytes from the input stream and send them to a specified actor.
java.lang.Byte[]	read(java.lang.Integer max) Read an array of bytes from the input stream and return them to the caller.
java.lang.Character[]	readln() Read a line of characters from the internal input stream.
void	readln(ActorName client, java.lang.String method) Read a line of characters from the internal input stream.
void	reset() Reposition the internal stream to the position marked by a previous call to mark.
void	run() The main processing loop for this actor.
void	skip(ActorName client, java.lang.String method, java.lang.Long n) Skip over and discard n bytes of data from the input stream.
java.lang.Long	skip(java.lang.Long n) Skip over and discard n bytes of data from the input stream.
void	write(java.io.OutputStream out, java.lang.Byte[] b) Write the contents of a byte array to the internal output stream.
void	write(java.io.OutputStream out, java.lang.Byte[] b, java.lang.Integer off, java.lang.Integer len) Write a subsequence of a byte array to the output stream.
void	write(java.io.OutputStream out, java.lang.Integer b) Writes a byte to the internal output stream.

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

Constructor Detail

ShellActorImpl

public ShellActorImpl()

Method Detail

actorInitialize

protected void actorInitialize(ActorManager ourMgr,
                               ActorName you,
                               ActorCreateRequest req)

This method initializes a new shell actor implementation which will be associated with a particular ShellSession. Within this method we immediately call managerServiceInvoke to set up a direct link with our session. The only constructor argument should be an Integer giving the ID of the local session we are associated with.

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 ActorCreateRequest which describes the new actor to be created.

Overrides:

actorInitialize in class ActorImpl

actorDeliver

protected void actorDeliver(ActorMsgRequest msg)

Receive a new message from our manager. Depending on who the message is targeted to, we may either deliver the message to the shell session by calling ShellSession.newShellMsg, or we may perform a stream operation. In either case, we dump the message if this shell session is no longer active.

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

actorPostMigrateRebuild

protected void actorPostMigrateRebuild(ActorManager ourMgr)

As ShellActorImpl can not migrate, this method should never be called. If it is, then throw a fatal exception.

Parameters:

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

Overrides:

actorPostMigrateRebuild in class ActorImpl

run

public void run()

The main processing loop for this actor. All we do here is call ourSession.shellMainLoop. This allows the shell session to begin processing commands with the proper permissions for invoking the local "impl" commands.

Overrides:

run in class java.lang.Thread

implSend

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

Request that a message be sent. The sender field is automatically reset to be this local actor so that we correctly receive error messages resulting from the send. Note that RPC's are not handled automatically. That is, the caller will have to parse incoming messages for the __reply message.

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:

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.

Overrides:

implSend in class ActorImpl

implCreate

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

Request a new actor to be created. The "requester" field is automatically set to the name of this actor so that error messages are correctly received. The name of the new actor is returned.

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)

This method should never be invoked and results in an immediate fatal error.

Parameters:

loc - The ActorManagerName of the node to migrate to.

Overrides:

implMigrate in class ActorImpl

implInvokeService

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

Invoke a service on behalf of the associated shell session.

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)

Destroy the shell actor. Currently this is just a stub which returns an exception if it is called. I don't envision shell actor's ever being destroyed in this way (the SHOULD be garbage collected however).

Overrides:

implDestroy in class ActorImpl

read

public java.lang.Byte[] read(java.lang.Integer max)
                      throws java.io.IOException

Read an array of bytes from the input stream and return them to the caller. The maximum number of bytes to read is specified by max. This method blocks until input is available. Normally, this method will be invoked using the "call" actor operation, as this is the only way to obtain the data returned from this method.

Parameters:

in - The InputStream to use for the operation.

max - An Integer giving the maximum number of bytes to read from the stream.

Returns:

A Byte array giving the data read from the stream. The return value is null if no data was available because end-of-file was encountered. Otherwise, the length of the array indicates the actual number of bytes read.

Throws:

java.io.IOException - Thrown if an I/O error occurs while reading the attached stream, or if max is less than one.

read

public void read(ActorName client,
                 java.lang.String method,
                 java.lang.Integer max)
          throws java.io.IOException

Read an array of bytes from the input stream and send them to a specified actor. The maximum number of bytes to read is specified by max. This method blocks until input is available. The result is sent to the actor with name client by invoking method method. Thus, client is expected to define a method with signature:

public type method(Byte[]);

where type may be any legal return type. Any error resulting from the sending of the result (e.g. NoSuchMethodException, RemoteCodeException, etc) is ignored by the StreamInputActor (but it IS logged to the Actor log file). Normally, this method is used by actors wishing to perform asynchronous I/O.

Parameters:

in - The InputStream to use for the operation.

client - The ActorName of the actor which should receive the data.

method - The String name of the method in client which will accept the data.

max - An Integer giving the maximum number of bytes to read from the stream.

Throws:

java.io.IOException - Thrown if an I/O error occurs while reading the attached stream, or if max is less than one.

See Also:

StreamInputActor.read(Integer)

skip

public java.lang.Long skip(java.lang.Long n)
                    throws java.io.IOException

Skip over and discard n bytes of data from the input stream. Depending on the internal InputStream, the actual number of bytes skipped may vary. The number of bytes skipped is returned as the result of this method. Normally, this method will be invoked using the "call" actor operation, as this is the only way to obtain the data returned from this method.

Parameters:

in - The InputStream to use for the operation.

n - A Long giving the number of bytes to be skipped.

Returns:

An Long giving the actual number of bytes skipped.

Throws:

java.io.IOException - Thrown if an I/O error occurs while skipping bytes.

skip

public void skip(ActorName client,
                 java.lang.String method,
                 java.lang.Long n)
          throws java.io.IOException

Skip over and discard n bytes of data from the input stream. Depending on the internal InputStream, the actual number of bytes skipped may vary. The number of bytes skipped is sent to the actor with name client by invoking method method. Thus, client is expected to define a method with signature:

public type method(Long);

where type may be any legal return type. Any error resulting from the sending of the result (e.g. NoSuchMethodException, RemoteCodeException, etc) is ignored by the StreamInputActor (but it IS logged to the Actor log file). Normally, this method is used by actors wishing to perform asynchronous I/O.

Parameters:

in - The InputStream to use for the operation.

client - The ActorName of the actor which should receive the number of bytes skipped.

method - The String name of the method in client which will accept the number of bytes skipped.

n - A Long giving the number of bytes to be skipped.

Throws:

java.io.IOException - Thrown if an I/O error occurs while skipping bytes.

See Also:

StreamInputActor.skip(Long)

available

public java.lang.Integer available()
                            throws java.io.IOException

Return the number of bytes that can be read from the internal input stream without blocking. The number of bytes available is returned as an Integer to the caller. Normally, this method will be invoked using the "call" actor operation, as this is the only way to obtain the data returned from this method.

Parameters:

in - The InputStream to use for the operation.

Returns:

An Integer giving the number of bytes that can be read from this input stream without blocking.

Throws:

java.io.IOException - Thrown if an I/O error occurs while attempting to determine the number of bytes available.

available

public void available(ActorName client,
                      java.lang.String method)
               throws java.io.IOException

Determine the number of bytes that can be read from the internal input stream without blocking, and send the result to the specified caller. The number of bytes available is sent to the actor with name client by invoking method method. Thus, client is expected to define a method with signature:

public type method(Integer);

where type may be any legal return type. Any error resulting from the sending of the result (e.g. NoSuchMethodException, RemoteCodeException, etc) is ignored by the StreamInputActor (but it IS logged to the Actor log file). Normally, this method is used by actors wishing to perform asynchronous I/O.

Parameters:

in - The InputStream to use for the operation.

client - The ActorName of the actor which should receive the number of bytes available.

method - The String name of the method in client which will accept the number of bytes available.

Throws:

java.io.IOException - Thrown if an I/O error occurs while attempting to determine the number of bytes available.

See Also:

StreamInputActor.available()

close

public void close()
           throws java.io.IOException

Close the internal input stream. As this method has no return value, it may be called either synchronously or asynchronously.

Parameters:

in - The InputStream to use for the operation.

Throws:

java.io.IOException - Thrown if an I/O error occurs while attempting to close the stream.

mark

public void mark(java.lang.Integer readlimit)

Mark the current position in the internal stream. Later calls to reset will reposition the internal stream at the last marked position. A readlimit may be specified which indicates the number of bytes which may be read before the mark position becomes invalid. As this method has no return value, it may be called either synchronously or asynchronously.

Parameters:

in - The InputStream to use for the operation.

readlimit - An Integer indicating the maximum number of bytes that can be read before the mark position becomes invalid.

Throws:

java.io.IOException - Thrown if an I/O error occurs while placing the mark.

reset

public void reset()
           throws java.io.IOException

Reposition the internal stream to the position marked by a previous call to mark. As this method has no return value, it may be called either synchronously or asynchronously.

Parameters:

in - The InputStream to use for the operation.

Throws:

java.io.IOException - Thrown if the internal stream has not been marked, or if the previously placed mark has been invalidated.

markSupported

public java.lang.Boolean markSupported()

Test if the internal input stream supports the mark and reset methods. A Boolean is returned to the caller indicating the result of the query. Normally, this method will be invoked using the "call" actor operation, as this is the only way to obtain the data returned from this method.

Parameters:

in - The InputStream to use for the operation.

Returns:

A Boolean indicating true if mark and reset are supported, and false otherwise.

markSupported

public void markSupported(ActorName client,
                          java.lang.String method)

Test if the internal input stream supports the mark and reset methods. The Boolean result is sent to the actor with name client by invoking method method. Thus, client is expected to define a method with signature:

public type method(Boolean);

where type may be any legal return type. Any error resulting from the sending of the result (e.g. NoSuchMethodException, RemoteCodeException, etc) is ignored by the StreamInputActor (but it IS logged to the Actor log file). Normally, this method is used by actors wishing to perform asynchronous I/O.

Parameters:

in - The InputStream to use for the operation.

client - The ActorName of the actor which should receive the markSupported status

method - The String name of the method in client which will accept the markSupported status.

See Also:

StreamInputActor.markSupported()

readln

public java.lang.Character[] readln()
                             throws java.io.IOException

Read a line of characters from the internal input stream. A line is any sequence of characters terminated by a newline. This call will block until either a newline terminates a sequence of characters, or end-of-file is encountered. In either case, a Character array containing the characters read (minus the newline terminator) is returned to the caller. If no characters were available (e.g. because end-of-file was encountered immediately), then null is returned. Normally, this method will be invoked using the "call" actor operation, as this is the only way to obtain the data returned from this method.

Parameters:

in - The InputStream to use for the operation.

Returns:

A Character array containing all the characters read up to a terminating newline or end-of-file, or null if no characters were available do to end-of-file.

Throws:

java.io.IOException - Thrown if an I/O error occurs while reading a line of characters.

readln

public void readln(ActorName client,
                   java.lang.String method)
            throws java.io.IOException

Read a line of characters from the internal input stream. A line is any sequence of characters terminated by a newline. This call will block until either a newline terminates a sequence of characters, or end-of-file is encountered. In either case, a Character array containing the characters read (minus the newline terminator) is sent to the actor with name client by invoking method method. If no characters were available (e.g. because end-of-file was encountered immediately), then null is sent to client. Thus, client is expected to define a method with signature:

public type method(Character);

where type may be any legal return type. Any error resulting from the sending of the result (e.g. NoSuchMethodException, RemoteCodeException, etc) is ignored by the StreamInputActor (but it IS logged to the Actor log file). Normally, this method is used by actors wishing to perform asynchronous I/O.

Parameters:

in - The InputStream to use for the operation.

client - The ActorName of the actor which should receive the line of characters.

method - The String name of the method in client which should recieve the line of characters.

Throws:

java.io.IOException - Thrown if an I/O error occurs while reading a line of characters.

See Also:

StreamInputActor.readln()

write

public void write(java.io.OutputStream out,
                  java.lang.Integer b)
           throws java.io.IOException

Writes a byte to the internal output stream.

Parameters:

out - The OutputStream to perform the operation on.

b - An Integer giving the byte to write.

Throws:

java.io.IOException - Thrown if an I/O error occurs while writing the byte.

write

public void write(java.io.OutputStream out,
                  java.lang.Byte[] b)
           throws java.io.IOException

Write the contents of a byte array to the internal output stream.

Parameters:

out - The OutputStream to perform the operation on.

b - A Byte array of data to write to the output stream.

Throws:

java.io.IOException - Thrown if an I/O error occurs while writing the byte array.

write

public void write(java.io.OutputStream out,
                  java.lang.Byte[] b,
                  java.lang.Integer off,
                  java.lang.Integer len)
           throws java.io.IOException

Write a subsequence of a byte array to the output stream.

Parameters:

out - The OutputStream to perform the operation on.

b - A Byte array of data from which a subsequence will be written to the output stream.

off - An Integer giving the index in the data to start the write from.

len - An Integer giving the total number of bytes to write.

Throws:

java.io.IOException - Thrown if an I/O error occurs while writing the subsequence of the byte array.

print

public void print(java.io.OutputStream out,
                  java.lang.String s)
           throws java.io.IOException

Print a string to the output stream.

Parameters:

out - The OutputStream to perform the operation on.

s - The String to display.

Throws:

java.io.IOException - Thrown if an I/O error occurs while displaying the string.

println

public void println(java.io.OutputStream out,
                    java.lang.String s)
             throws java.io.IOException

Print a string followed by a newline character.

Parameters:

out - The OutputStream to perform the operation on.

s - The String to display.

Throws:

java.io.IOException - Thrown if an I/O error occurs while displaying the string.

flush

public void flush(java.io.OutputStream out)
           throws java.io.IOException

Flush the internal output stream.

Parameters:

out - The OutputStream to perform the operation on.

Throws:

java.io.IOException - Thrown if an I/O error occurs while flushing the input stream.

close

public void close(java.io.OutputStream out)
           throws java.io.IOException

Close the internal output stream.

Parameters:

out - The OutputStream to perform the operation on.

Throws:

java.io.IOException - Thrown if an I/O error occurs while attempting to close the stream.