ewe.io
Class RemoteCall

java.lang.Object
  ewe.sys.Handle
      ewe.io.RemoteCall

All Implemented Interfaces:

ByteEncodable, Task, TimerProc

public class RemoteCall

extends Handle

implements ByteEncodable

A RemoteCall with a RemoteCallHandler can be used to invoke methods on an object running in one ewe application by a different remote application. The remote call handles marshalling the data into text streams which are then sent and reassembled into local data and invoked on the target object. A result is sent back indicating success or failure along with any return value. This is very useful when synchronizing ewe applications since you do not need to come up with any protocols or message passing system. All you need to do is invoke methods remotely.

See the EweSyncDemo application for an example of how to do this.

Please note the following restrictions when using remote calls.

• All individual Object parameters or objects within arrays or vectors must be text encodable/decodable in some way.

A RemoteCall represents a single method which is specified in its constructor. Once you have a RemoteCall object you set parameters for a call by calling the add() methods in sequence. The RemoteCall knows the exact type of each parameter so the data specified in each add() method is cast to the correct parameter type. Each add() method returns the RemoteCall object itself so it is easy to concatenate add() calls together.

Nested Class Summary

static class

RemoteCall.UnknownException

Field Summary

Class	classCreator Deprecated. - this is not needed.
String	id
Throwable	invocationError This will hold any exception generated by the remote object when the method was invoked.
String	method
RemoteCallHandler	myHandler This is initially null but can be set before calling call.
boolean	replied This is set true once a reply has been received.
String	retType
int	timeOut This is the timeout for the call.

Fields inherited from class ewe.sys.Handle

Aborted, Changed, doing, error, errorCode, errorObject, Failed, Failure, nativeResult, progress, progressResolution, returnValue, Running, shouldStop, startTime, state, Stopped, stopReason, Succeeded, Success, task

Constructor Summary

RemoteCall(byte[] source, int offset, int length)
This is used to create a RemoteCall from a sequence of bytes.

RemoteCall(String method)
Create a new RemoteCall targeted at the specified method.

Method Summary

RemoteCall	add(boolean value) Use this to add a parameter of type boolean.
RemoteCall	add(char value) Use this to add a char parameter.
RemoteCall	add(double value) Use this to add a parameter of type float or double.
RemoteCall	add(long value) Use this to add a parameter of type byte, short, int and long.
RemoteCall	add(Object value) Use this to add an object or array parameter (including null).
RemoteCall	addParameter(Wrapper w) This is used to add a parameter.
Wrapper	call() Invokes the remote call using the myHandler value as the transport mechanism and specifying a null (default) target object.
Wrapper	call(RemoteCallHandler handler, String targetCode) Invokes the remote call using the specified handler as the transport mechanism.
Wrapper	call(String targetCode) Invokes the remote call using the myHandler value as the transport mechanism.
RemoteCall	callAsync()
RemoteCall	callAsync(RemoteCallHandler handler, String targetCode)
int	encodeBytes(ByteArray dest) This requests the Object to encode itself as a stream of bytes which is appended to the destination ByteArray.
RemoteCall	getCopy() Get a copy of a RemoteCall that you can use for another invocation.
Throwable	getException()
Wrapper	getReturnValue()
ByteArray	invokeOn(Object dest, Reflect r) Invoke the remote call on a target object of the specified class.
protected boolean	invokeOn(Object dest, Reflect r, ByteArray ba)
void	reply(ByteArray reply) This is used to provide a reply to the remote call.
void	sent() This is used to tell the RemoteCall that it is in the process of transmission to the remote object.
RemoteCall	set(Wrapper[] parameters)
RemoteCall	setClassCreator(Class creator) This is used to set a special class creator.
RemoteCall	setTimeout(int milliseconds) This sets the timeout time for this RemoteCall.
void	timeout() This is used to tell the RemoteCall that no reply has been received past a timeout period and it should conisider itself timed out.
String	toString() Create a remote call from a received encoded call.

Methods inherited from class ewe.sys.Handle

callBackOnAnyFlag, callBackOnFlags, callWhenStopped, callWhenStopped, cancelCallBack, changed, check, check, checkAny, clearTag, doCallBackOnFlags, fail, failed, getErrorText, getHandle, getSubHandle, getSubHandle, getTag, getTask, hasStopped, resetProgress, resetTime, set, setFlags, setProgress, setTag, start, startDoing, startTask, stop, stopAlsoIfStopped, stopTask, ticked, waitOn, waitOn, waitOn, waitOn, waitOnAny, waitOnAny, waitOnAny, waitOnAny, waitOnAnyFlag, waitOnFlags, waitOnFlags, waitUntilStopped, waitUntilStopped

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode

Field Detail

method

public String method

retType

public String retType

id

public String id

classCreator

public Class classCreator

Deprecated. - this is not needed.

This is used if you intend to send/receive parameters that are classes that are loaded using a non-system class loader.

invocationError

public Throwable invocationError

This will hold any exception generated by the remote object when the method was invoked. If the exception generated on the remote side could not be recreated on this side - it will be set to RemoteCall.UnknownException and the message will be set to be the same.

timeOut

public int timeOut

This is the timeout for the call. By default it is zero, which will then let the remote call handler being used to send the call use its own timeout.

myHandler

public RemoteCallHandler myHandler

This is initially null but can be set before calling call.

replied

public boolean replied

This is set true once a reply has been received.

Constructor Detail

RemoteCall

public RemoteCall(String method)

Create a new RemoteCall targeted at the specified method. Parameter and return specs MUST be provided e.g.

new RemoteCall("aMethod(IILjava/lang/String;)Z");

Standard Java type specifiers are used, specifically.

B - byte, C - char, S - short, I - int, J - long, F - float, D - Double Z - boolean, V - void (for method types only)
[type-specifier - for an array.
LclassName; - for object (NOTE the ending semi-colon).

For object (L) you should use / instead of . as the package separator.

The format for a method is: method_name(concatenated parameter type specifiers)return_type

There are no separators between the parameter type specifiers. If the the method is void you should use V as the return type.

RemoteCall

public RemoteCall(byte[] source,
                  int offset,
                  int length)
           throws StreamCorruptedException,
                  ClassNotFoundException

This is used to create a RemoteCall from a sequence of bytes. This is used by the handler to reconstruct the call after it has been received.

Method Detail

getCopy

public RemoteCall getCopy()

Get a copy of a RemoteCall that you can use for another invocation. RemoteCalls should only be used once to invoke on the remote object - so if you want to invoke the call repeatedly you will need to call this method. However after doing so you will always need to add the parameters again.

Returns:

A copy of the RemoteCall with no parameters added yet.

setClassCreator

public RemoteCall setClassCreator(Class creator)

This is used to set a special class creator. This is in case you are going to be sending/receiving objects that were loaded from a non-system class loader. The creator supplied must have been loaded from the same class loader.

Parameters:

creator - A Class object that was loaded from the same class loader.

Returns:

this RemoteCall

addParameter

public RemoteCall addParameter(Wrapper w)

This is used to add a parameter.

Parameters:

w - a Wrapper with the parameter value. It must be of the correct type.

Returns:

this RemoteCall object.

add

public RemoteCall add(char value)

Use this to add a char parameter.

Parameters:

value - The character parameter

Returns:

itself.

add

public RemoteCall add(long value)

Use this to add a parameter of type byte, short, int and long.

Parameters:

value - The long value to add.

Returns:

itself.

add

public RemoteCall add(double value)

Use this to add a parameter of type float or double.

Parameters:

value - The double or float value to add.

Returns:

itself.

add

public RemoteCall add(boolean value)

Use this to add a parameter of type boolean.

Parameters:

value - The boolean value to add.

Returns:

itself.

add

public RemoteCall add(Object value)

Use this to add an object or array parameter (including null).

Parameters:

value - The object or array value to add.

Returns:

itself.

set

public RemoteCall set(Wrapper[] parameters)

encodeBytes

public int encodeBytes(ByteArray dest)
                throws IllegalStateException

Description copied from interface: ByteEncodable

This requests the Object to encode itself as a stream of bytes which is appended to the destination ByteArray. If the destination ByteArray is null, then the object should report how many bytes would be used if the object was encoded.

Specified by:

encodeBytes in interface ByteEncodable

Parameters:

dest - The destination ByteArray, or null to determine the number of bytes needed to encode.

Returns:

The number of bytes appended to the ByteArray or the number of bytes needed to encode.

Throws:

IllegalStateException

invokeOn

public ByteArray invokeOn(Object dest,
                          Reflect r)

Invoke the remote call on a target object of the specified class. You would not need to use this unless you were writing a RemoteCallHandler.

Parameters:

dest - The destination Object to invoke the method on - can be

r - The Reflect object for the destination Object.

Returns:

An encoded return value.

invokeOn

protected boolean invokeOn(Object dest,
                           Reflect r,
                           ByteArray ba)

sent

public void sent()

This is used to tell the RemoteCall that it is in the process of transmission to the remote object. You would not need to use this unless you were writing a RemoteCallHandler.

setTimeout

public RemoteCall setTimeout(int milliseconds)

This sets the timeout time for this RemoteCall. This overrides the timeout of the remote call handler being used to send the call.

Parameters:

milliseconds - the timeout in milliseconds. Setting it to zero will cause the remote call handler timeout to be used instead.

Returns:

this RemoteCall.

timeout

public void timeout()

This is used to tell the RemoteCall that no reply has been received past a timeout period and it should conisider itself timed out. You would not need to use this unless you were writing a RemoteCallHandler.

reply

public void reply(ByteArray reply)

This is used to provide a reply to the remote call. It will then prepare the return value Wrapper and set its flags to be successfull. You would not need to use this unless you were writing a RemoteCallHandler.

call

public Wrapper call(RemoteCallHandler handler,
                    String targetCode)
             throws RemoteCallException

Invokes the remote call using the specified handler as the transport mechanism.

Parameters:

handler - the RemoteCallHandler handling the call.

targetCode - the target object.

Returns:

a Wrapper containing the return value. Use getInt(), getDouble(), getObject(), etc. on the returned value to convert to the appropriate type.

Throws:

RemoteCallException - if an error occured during the RemoteCall.

callAsync

public RemoteCall callAsync(RemoteCallHandler handler,
                            String targetCode)

callAsync

public RemoteCall callAsync()

getReturnValue

public Wrapper getReturnValue()

getException

public Throwable getException()

call

public Wrapper call(String targetCode)
             throws RemoteCallException

Invokes the remote call using the myHandler value as the transport mechanism.

Parameters:

targetCode - the target object.

Returns:

a Wrapper containing the return value. Use getInt(), getDouble(), getObject(), etc. on the returned value to convert to the appropriate type. A Wrapper is always returned, even if the method is a void method.

Throws:

RemoteCallException - if an error occured during the RemoteCall.

call

public Wrapper call()
             throws RemoteCallException

Invokes the remote call using the myHandler value as the transport mechanism and specifying a null (default) target object. The method waits until the call returns.

Returns:

a Wrapper containing the return value. Use getInt(), getDouble(), getObject(), etc. on the returned value to convert to the appropriate type. A Wrapper is always returned, even if the method is a void method.

Throws:

RemoteCallException - if an error occured during the RemoteCall.

toString

public String toString()

Create a remote call from a received encoded call. You would not use this unless you were writing your own RemoteCallHandler.

Overrides:

toString in class Object

Returns:

a String representing this object.