com.retrogui.dualrpc.client
Class DualRpcClient

java.lang.Object
  extended bycom.retrogui.dualrpc.client.DualRpcClient
All Implemented Interfaces:
IDualRpcMessageConstants

public class DualRpcClient
extends java.lang.Object
implements IDualRpcMessageConstants

Client component of the dual rpc framework. Establishes connection to the server.


Field Summary
 
Fields inherited from interface com.retrogui.dualrpc.common.IDualRpcMessageConstants
DEFAULT_RPC_CALL_TIMEOUT, PAYLOAD_TYPE_RPC_CALL, PAYLOAD_TYPE_RPC_FAULT, PAYLOAD_TYPE_RPC_RESULT, RPC_FAULTCODE_EXCEPTION
 
Constructor Summary
DualRpcClient(java.lang.String host, int port)
          Construct a client object but does not connect to the server until connect() is called.
 
Method Summary
 java.lang.Object call(java.lang.String handlerClassName, java.lang.String methodName)
          Call a remote method with no parameters.
 java.lang.Object call(java.lang.String handlerClassName, java.lang.String methodName, java.util.ArrayList parameters)
          Call a remote method with an unlimited number of parameters (passed via an ArrayList).
 java.lang.Object call(java.lang.String handlerClassName, java.lang.String methodName, boolean hasResults, int callTimeoutInSeconds, java.util.ArrayList parameters)
          Call a handler method and wait a specified number of seconds for a return object.
 java.lang.Object call(java.lang.String handlerClassName, java.lang.String methodName, int callTimeoutInSeconds, java.util.ArrayList parameters)
          Call a remote method with an unlimited number of parameters (passed via an ArrayList).
 java.lang.Object call(java.lang.String handlerClassName, java.lang.String methodName, java.lang.Object p1)
          Call a remote method with one parameter.
 java.lang.Object call(java.lang.String handlerClassName, java.lang.String methodName, java.lang.Object p1, java.lang.Object p2)
          Call a remote method with two parameters.
 java.lang.Object call(java.lang.String handlerClassName, java.lang.String methodName, java.lang.Object p1, java.lang.Object p2, java.lang.Object p3)
          Call a remote method with three parameters.
 java.lang.Object call(java.lang.String handlerClassName, java.lang.String methodName, java.lang.Object p1, java.lang.Object p2, java.lang.Object p3, java.lang.Object p4)
          Call a remote method with four parameters.
 java.lang.Object call(java.lang.String handlerClassName, java.lang.String methodName, java.lang.Object p1, java.lang.Object p2, java.lang.Object p3, java.lang.Object p4, java.lang.Object p5)
          Call a remote method with five parameters.
 void callAsync(java.lang.String handlerClassName, java.lang.String methodName)
          Asynchronously call a remote method with no parameters.
 void callAsync(java.lang.String handlerClassName, java.lang.String methodName, java.util.ArrayList parameters)
          Asynchronously call a remote method with an unlimited number of parameters (passed via an ArrayList).
 void callAsync(java.lang.String handlerClassName, java.lang.String methodName, java.lang.Object p1)
          Asynchronously call a remote method with one parameter.
 void callAsync(java.lang.String handlerClassName, java.lang.String methodName, java.lang.Object p1, java.lang.Object p2)
          Asynchronously call a remote method with two parameters.
 void callAsync(java.lang.String handlerClassName, java.lang.String methodName, java.lang.Object p1, java.lang.Object p2, java.lang.Object p3)
          Asynchronously call a remote method with three parameters.
 void callAsync(java.lang.String handlerClassName, java.lang.String methodName, java.lang.Object p1, java.lang.Object p2, java.lang.Object p3, java.lang.Object p4)
          Asynchronously call a remote method with four parameters.
 void callAsync(java.lang.String handlerClassName, java.lang.String methodName, java.lang.Object p1, java.lang.Object p2, java.lang.Object p3, java.lang.Object p4, java.lang.Object p5)
          Asynchronously call a remote method with five parameters.
 void connect()
          Connect to the server.
 void disconnect()
          Disconnect from the server.
protected  IClientCallbackHandler getCallbackHandler()
           
protected  java.util.Hashtable getCallWaitingRegistry()
          Get the call waiting registry.
protected  java.util.HashMap getClientHandlers()
          Get hash map of client handler classes.
protected  MessageClient getMessageclient()
          Get the message client.
protected  IMethodAccessControl getMethodAccessControl()
           
protected  java.lang.String getNextMessageId()
           
protected  IRpcWorkerFactory getRpcWorkerFactory()
           
 long getSessionId()
          Get the session id of the client connection.
 void registerClientSideHandler(AbstractClientRpcHandler clientRpcHandler)
          Register (add) a client side handler class.
 void setCallbackHandler(IClientCallbackHandler callbackHandler)
          Set the callback handler.
 void setDefaultCallTimeoutInSeconds(int defaultCallTimeoutInSeconds)
          Set the default RPC call timeout.
 void setMessageEncoder(IMessageEncoder messageEncoder)
          Set an alternate message encoder.
 void setMessageSerializer(IMessageSerializer messageSerializer)
          Set an alternate message serializer for SOAP, XML-RPC, JSON, etc.
 void setMethodAccessControl(IMethodAccessControl methodAccessControl)
           
 void setRpcWorkerFactory(IRpcWorkerFactory rpcWorkerFactory)
           
 void setSocketFactory(javax.net.SocketFactory factory)
          Specify an alternate (SSL) socket factory.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DualRpcClient

public DualRpcClient(java.lang.String host,
                     int port)
Construct a client object but does not connect to the server until connect() is called.

Parameters:
host - - the server host (or ip address)
port - - the server port
See Also:
Method Detail

registerClientSideHandler

public void registerClientSideHandler(AbstractClientRpcHandler clientRpcHandler)
Register (add) a client side handler class. A client side handler must be registered before it can be called by the server. The client handler processes RPC requests from the server.

Parameters:
clientRpcHandler - - the handler object
See Also:

connect

public void connect()
             throws java.net.UnknownHostException,
                    java.io.IOException,
                    java.security.GeneralSecurityException
Connect to the server. A java.net.ConnectException is thrown if cannot connect to server. In a production environment you may want to retry a couple of times or try to connect to a backup server.

Throws:
java.net.UnknownHostException
java.io.IOException
java.security.GeneralSecurityException

call

public java.lang.Object call(java.lang.String handlerClassName,
                             java.lang.String methodName)
                      throws CallException
Call a remote method with no parameters. Default timeout is 60 seconds.

Parameters:
handlerClassName - - classname of the server-side handler
methodName - - server-side method name to call
Returns:
- the return object. This return object must then be cast to the appropriate payloadType. For example, if the server handler method returns a string then you must cast the return object as a string.
Throws:
CallException

call

public java.lang.Object call(java.lang.String handlerClassName,
                             java.lang.String methodName,
                             java.lang.Object p1)
                      throws CallException
Call a remote method with one parameter. Default timeout is 60 seconds.

Parameters:
handlerClassName - - classname of the server-side handler
methodName - - server-side method name to call
Returns:
- the return object. This return object must then be cast to the appropriate payloadType. For example, if the server handler method returns a string then you must cast the return object as a string.
Throws:
CallException

call

public java.lang.Object call(java.lang.String handlerClassName,
                             java.lang.String methodName,
                             java.lang.Object p1,
                             java.lang.Object p2)
                      throws CallException
Call a remote method with two parameters. Default timeout is 60 seconds.

Parameters:
handlerClassName - - classname of the server-side handler
methodName - - server-side method name to call
Returns:
- the return object. This return object must then be cast to the appropriate payloadType. For example, if the server handler method returns a string then you must cast the return object as a string.
Throws:
CallException

call

public java.lang.Object call(java.lang.String handlerClassName,
                             java.lang.String methodName,
                             java.lang.Object p1,
                             java.lang.Object p2,
                             java.lang.Object p3)
                      throws CallException
Call a remote method with three parameters. Default timeout is 60 seconds.

Parameters:
handlerClassName - - classname of the server-side handler
methodName - - server-side method name to call
Returns:
- the return object. This return object must then be cast to the appropriate payloadType. For example, if the server handler method returns a string then you must cast the return object as a string.
Throws:
CallException

call

public java.lang.Object call(java.lang.String handlerClassName,
                             java.lang.String methodName,
                             java.lang.Object p1,
                             java.lang.Object p2,
                             java.lang.Object p3,
                             java.lang.Object p4)
                      throws CallException
Call a remote method with four parameters. Default timeout is 60 seconds.

Parameters:
handlerClassName - - classname of the server-side handler
methodName - - server-side method name to call
Returns:
- the return object. This return object must then be cast to the appropriate payloadType. For example, if the server handler method returns a string then you must cast the return object as a string.
Throws:
CallException

call

public java.lang.Object call(java.lang.String handlerClassName,
                             java.lang.String methodName,
                             java.lang.Object p1,
                             java.lang.Object p2,
                             java.lang.Object p3,
                             java.lang.Object p4,
                             java.lang.Object p5)
                      throws CallException
Call a remote method with five parameters. Default timeout is 60 seconds.

Parameters:
handlerClassName - - classname of the server-side handler
methodName - - server-side method name to call
Returns:
- the return object. This return object must then be cast to the appropriate payloadType. For example, if the server handler method returns a string then you must cast the return object as a string.
Throws:
CallException

callAsync

public void callAsync(java.lang.String handlerClassName,
                      java.lang.String methodName)
               throws CallException
Asynchronously call a remote method with no parameters.

Parameters:
handlerClassName - - classname of the server-side handler
methodName - - server-side method name to call
Throws:
CallException

callAsync

public void callAsync(java.lang.String handlerClassName,
                      java.lang.String methodName,
                      java.lang.Object p1)
               throws CallException
Asynchronously call a remote method with one parameter.

Parameters:
handlerClassName - - classname of the server-side handler
methodName - - server-side method name to call
Throws:
CallException

callAsync

public void callAsync(java.lang.String handlerClassName,
                      java.lang.String methodName,
                      java.lang.Object p1,
                      java.lang.Object p2)
               throws CallException
Asynchronously call a remote method with two parameters.

Parameters:
handlerClassName - - classname of the server-side handler
methodName - - server-side method name to call
Throws:
CallException

callAsync

public void callAsync(java.lang.String handlerClassName,
                      java.lang.String methodName,
                      java.lang.Object p1,
                      java.lang.Object p2,
                      java.lang.Object p3)
               throws CallException
Asynchronously call a remote method with three parameters.

Parameters:
handlerClassName - - classname of the server-side handler
methodName - - server-side method name to call
Throws:
CallException

callAsync

public void callAsync(java.lang.String handlerClassName,
                      java.lang.String methodName,
                      java.lang.Object p1,
                      java.lang.Object p2,
                      java.lang.Object p3,
                      java.lang.Object p4)
               throws CallException
Asynchronously call a remote method with four parameters.

Parameters:
handlerClassName - - classname of the server-side handler
methodName - - server-side method name to call
Throws:
CallException

callAsync

public void callAsync(java.lang.String handlerClassName,
                      java.lang.String methodName,
                      java.lang.Object p1,
                      java.lang.Object p2,
                      java.lang.Object p3,
                      java.lang.Object p4,
                      java.lang.Object p5)
               throws CallException
Asynchronously call a remote method with five parameters.

Parameters:
handlerClassName - - classname of the server-side handler
methodName - - server-side method name to call
Throws:
CallException

callAsync

public void callAsync(java.lang.String handlerClassName,
                      java.lang.String methodName,
                      java.util.ArrayList parameters)
               throws CallException
Asynchronously call a remote method with an unlimited number of parameters (passed via an ArrayList).

Parameters:
handlerClassName - - classname of the server-side handler
methodName - - server-side method name to call
parameters - - ArrayList of parameters. The array elements must be in the same order as the method parameters. If the calling method does not have any parameters defined then pass an empty ArrayList to the call(). All array list elements MUST BE SERIALIZABLE.
Throws:
CallException

call

public java.lang.Object call(java.lang.String handlerClassName,
                             java.lang.String methodName,
                             java.util.ArrayList parameters)
                      throws CallException
Call a remote method with an unlimited number of parameters (passed via an ArrayList). Default timeout is 60 seconds.

Parameters:
handlerClassName - - classname of the server-side handler
methodName - - server-side method name to call
parameters - - ArrayList of parameters. The array elements must be in the same order as the method parameters. If the calling method does not have any parameters defined then pass an empty ArrayList to the call(). All array list elements MUST BE SERIALIZABLE.
Returns:
- the return object. This return object must then be cast to the appropriate payloadType. For example, if the server handler method returns a string then you must cast the return object as a string.
Throws:
CallException

call

public java.lang.Object call(java.lang.String handlerClassName,
                             java.lang.String methodName,
                             int callTimeoutInSeconds,
                             java.util.ArrayList parameters)
                      throws CallException
Call a remote method with an unlimited number of parameters (passed via an ArrayList). The timeout is specified.

Parameters:
handlerClassName - - classname of the server-side handler
methodName - - server-side method name to call
callTimeoutInSeconds - - time to wait for a return object. Set to 0 to wait forever.
parameters - - ArrayList of parameters. The array elements must be in the same order as the method parameters. If the calling method does not have any parameters defined then pass an empty ArrayList to the call(). All array list elements MUST BE SERIALIZABLE.
Returns:
- the return object. This return object must then be cast to the appropriate payloadType. For example, if the server handler method returns a string then you must cast the return object as a string.
Throws:
CallException

call

public java.lang.Object call(java.lang.String handlerClassName,
                             java.lang.String methodName,
                             boolean hasResults,
                             int callTimeoutInSeconds,
                             java.util.ArrayList parameters)
                      throws CallException
Call a handler method and wait a specified number of seconds for a return object. This method will wait for the specified length of time before throwing a timeout exception. Must be connected to work.

Parameters:
handlerClassName - - classname of the server-side handler
methodName - - server-side method name to call
callTimeoutInSeconds - - time to wait for a return object. Set to 0 to wait forever.
parameters - - ArrayList of parameters. The array elements must be in the same order as the method parameters. If the calling method does not have any parameters defined then pass an empty ArrayList to the call(). All array list elements MUST BE SERIALIZABLE.
hasResults - - flag to wait for a result object.
Returns:
- the return object. This return object must then be cast to the appropriate payloadType. For example, if the server handler method returns a string then you must cast the return object as a string.
Throws:
CallException

disconnect

public void disconnect()
                throws NotConnectedException
Disconnect from the server.

Throws:
NotConnectedException

getMessageclient

protected MessageClient getMessageclient()
Get the message client. For internal use.

Returns:
the message client

getCallWaitingRegistry

protected java.util.Hashtable getCallWaitingRegistry()
Get the call waiting registry. For internal use.

Returns:
the call waiting registry

setDefaultCallTimeoutInSeconds

public void setDefaultCallTimeoutInSeconds(int defaultCallTimeoutInSeconds)
Set the default RPC call timeout. Note that you can also set the call timeout for an individual call.

Parameters:
defaultCallTimeoutInSeconds -

getClientHandlers

protected java.util.HashMap getClientHandlers()
Get hash map of client handler classes. For internal use.

Returns:
hash of client side handler classes

getCallbackHandler

protected IClientCallbackHandler getCallbackHandler()
Returns:
Returns the callbackHandler. For internal use.

setCallbackHandler

public void setCallbackHandler(IClientCallbackHandler callbackHandler)
Set the callback handler. Typically used for defining a handler method that is called if the network connection is severed.

Parameters:
callbackHandler -

getSessionId

public long getSessionId()
                  throws NotConnectedException
Get the session id of the client connection. Must be connected.

Returns:
session id, a long
Throws:
NotConnectedException

setSocketFactory

public void setSocketFactory(javax.net.SocketFactory factory)
Specify an alternate (SSL) socket factory. The default socket factory is for normal TCP/IP sockets.

Parameters:
factory -

setMessageSerializer

public void setMessageSerializer(IMessageSerializer messageSerializer)
Set an alternate message serializer for SOAP, XML-RPC, JSON, etc. This is optional since the messageclient has a default java serializer. This alternate serializer is set into the messageclient in the connect() method. For an example implementation of a message serializer, see the JavaSerializer class.

Parameters:
messageSerializer - The messageSerializer to set.

setMessageEncoder

public void setMessageEncoder(IMessageEncoder messageEncoder)
Set an alternate message encoder. This is optional since the messageclient has a default Base64 encoder. A message encoder cannot use a newline character because it is reserved as the message delimiter. This alternate encoder is set into the messageclient in the connect() method. For an example implementation of a message encoder, see the Base64Encoder class.

Parameters:
messageEncoder - The messageEncoder to set.

getNextMessageId

protected java.lang.String getNextMessageId()
Returns:
get next message id string. For internal use.

setMethodAccessControl

public void setMethodAccessControl(IMethodAccessControl methodAccessControl)
Parameters:
methodAccessControl - The methodAccessControl to set.

getMethodAccessControl

protected IMethodAccessControl getMethodAccessControl()
Returns:
Returns the methodAccessControl.For internal use.

setRpcWorkerFactory

public void setRpcWorkerFactory(IRpcWorkerFactory rpcWorkerFactory)
Parameters:
rpcWorkerFactory - The rpcWorkerFactory to set.

getRpcWorkerFactory

protected IRpcWorkerFactory getRpcWorkerFactory()
Returns:
Returns the rpcWorkerFactory.