ewe.io
Class RemoteCallHandler

java.lang.Object
  ewe.io.RemoteCallHandler

public class RemoteCallHandler

extends Object

A remote call handler is a class that performs two functions:

• It receives remote calls from a remote object, invokes it on a local object and then dispatches the results to the source remote object.
• It takes local remote calls, dispatches it to a remote object and waits for the results.

This implementation performs these functions with the following constraints:

• Remote calls are received and dispatch via a single stream.

This implementation handles calls to multiple objects by using a Hashtable to map target codes to local objects. To override this implementation - override the Object findTarget(String targetCode) method.

If you want to change the method for receiving and sending data (i.e. not via the default stream) you must override boolean sendData(ByteArray data) and TextDecoder getData(ByteArray dest)

To close the RemoteCallHandler simply close the Stream object. If you want to close the handler without closing the stream, call the close() method.

Field Summary

protected boolean	closed
Handle	handle This can be used to monitor the progress of the RemoteCallHandler.
protected BlockInputStream	in
IOException	ioException If an IOException occured, it will be placed here.
protected BlockOutputStream	out
Object	target If this is not null then all calls with a null targetCode assumed to be to this target.
Hashtable	targets This Hashtable contains the local target objects and is used by the default implementation to match a target code with the target object.
int	timeOut This is the timeout in milliseconds for receiving a reply.

Constructor Summary

RemoteCallHandler()
Create a RemoteCallHandler with no stream or target object.

RemoteCallHandler(InputStream in, OutputStream out, Object target)

RemoteCallHandler(Stream stream, Object target)
Create a RemoteCallHandler using the specified stream and with the specified target object (i.e.

Method Summary

Wrapper	call(RemoteCall call) This calls and waits for the remote call to complete, fail or timeout.
boolean	call(RemoteCall rc, String targetCode) This dispatches the RemoteCall to the remote handler.
Wrapper	call(RemoteCall call, String targetCode, StringBuffer error) This calls and waits for the remote call to complete, fail or timeout.
RemoteCall	callAndWait(RemoteCall call, String targetCode) This calls and waits for the remote call to complete, fail or timeout.
protected boolean	callReceived(ByteArray received)
void	close() Closes the RemoteCallHandler and stops its operation.
void	closeConnection() Closes the RemoteCallHandler and stops its operation and closes the stream connection.
protected ByteArray	doInvoke(Object target, RemoteCall rc)
protected Tag	findTag(int id, Vector where)
protected Object	findTarget(String targetCode) Override this to find a target given a text encoded targetCode.
ByteArray	getData(ByteArray dest) This is responsible for receiving data - either remote calls or replies to remote calls.
protected void	queueSend(ByteArray toSend, int id, boolean isCall)
protected void	queueSend(Tag toSend)
void	sendData(ByteArray data) This is responsible for sending data - either remote calls or replies to remote calls.
void	setEncryption(DataProcessor decryptor, DataProcessor encryptor) Set the encryption to use for sending and receiving calls.
void	setEncryption(String password) Set the encryption to use for sending and receiving calls.
void	setKeys(EncryptionKey remotePublicKey, EncryptionKey localPrivateKey)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, toString

Field Detail

handle

public Handle handle

This can be used to monitor the progress of the RemoteCallHandler. If it is flagged as Handle.Stopped, this implies that the RemoteCallHandler has stopped operating (probably because the stream has closed).

targets

public Hashtable targets

This Hashtable contains the local target objects and is used by the default implementation to match a target code with the target object. Add to it as needed.

out

protected BlockOutputStream out

in

protected BlockInputStream in

target

public Object target

If this is not null then all calls with a null targetCode assumed to be to this target.

timeOut

public int timeOut

This is the timeout in milliseconds for receiving a reply. You can change this as you wish.

ioException

public IOException ioException

If an IOException occured, it will be placed here. An IOException will terminate the operations of the handler.

closed

protected boolean closed

Constructor Detail

RemoteCallHandler

public RemoteCallHandler()

Create a RemoteCallHandler with no stream or target object.

RemoteCallHandler

public RemoteCallHandler(Stream stream,
                         Object target)

Create a RemoteCallHandler using the specified stream and with the specified target object (i.e. the default object that all methods will be invoked on).

Parameters:

stream - The stream for the communication between RemoteCallHandlers.

target - A default object for methods to be invoked on. This can be null, in which case you will have to add targets to the targets Hashtable.

RemoteCallHandler

public RemoteCallHandler(InputStream in,
                         OutputStream out,
                         Object target)

Method Detail

findTarget

protected Object findTarget(String targetCode)

Override this to find a target given a text encoded targetCode. It is up to you to supply a mechanism for producing target codes and for locating objects based on that code.

setEncryption

public void setEncryption(DataProcessor decryptor,
                          DataProcessor encryptor)
                   throws IOException

Set the encryption to use for sending and receiving calls.

Throws:

IOException

setEncryption

public void setEncryption(String password)
                   throws IOException

Set the encryption to use for sending and receiving calls.

Throws:

IOException

setKeys

public void setKeys(EncryptionKey remotePublicKey,
                    EncryptionKey localPrivateKey)
             throws IOException

Throws:

IOException

sendData

public void sendData(ByteArray data)
              throws IOException

This is responsible for sending data - either remote calls or replies to remote calls.

This method may block the current mThread - the other operations of the handler operate in their own mThread threads.

Throws:

IOException

getData

public ByteArray getData(ByteArray dest)
                  throws IOException

This is responsible for receiving data - either remote calls or replies to remote calls. By default it reads a 32-bit integer value specifying the size of an array of bytes, which represents the call itself.

This method should block the current mThread until a full TextDecoder object has been read - the other operations of the handler operate in their own mThread threads.

Throws:

IOException

close

public void close()

Closes the RemoteCallHandler and stops its operation. The stream is not closed however. Note that closing the stream will automatically stop the handlers operation as well.

closeConnection

public void closeConnection()

Closes the RemoteCallHandler and stops its operation and closes the stream connection.

queueSend

protected void queueSend(ByteArray toSend,
                         int id,
                         boolean isCall)

queueSend

protected void queueSend(Tag toSend)

doInvoke

protected ByteArray doInvoke(Object target,
                             RemoteCall rc)

findTag

protected Tag findTag(int id,
                      Vector where)

callReceived

protected boolean callReceived(ByteArray received)

call

public boolean call(RemoteCall rc,
                    String targetCode)

This dispatches the RemoteCall to the remote handler. The targetCode can be null if the remote handler only handles invokation on a single object (e.g. this RemoteCallHandler). It returns true once the remote call has been queued for dispatch. The RemoteCall is itself a Handle and you should poll it to see when the Success or Failure flags have been set.

callAndWait

public RemoteCall callAndWait(RemoteCall call,
                              String targetCode)

This calls and waits for the remote call to complete, fail or timeout. The RemoteCall itself is returned and you should check to see if the "error" member is null.

call

public Wrapper call(RemoteCall call,
                    String targetCode,
                    StringBuffer error)

This calls and waits for the remote call to complete, fail or timeout. It returns the Wrapper which has the return value. If the return value is null, then there was an error.

call

public Wrapper call(RemoteCall call)

This calls and waits for the remote call to complete, fail or timeout. It returns the Wrapper which has the return value. If the return value is null, then there was an error. This assumes a null target, and that you are not interested in the error string.