com.funambol.client.ipc.rpc
Class RPCManager

java.lang.Object
  extended by com.funambol.client.ipc.rpc.RPCManager

public class RPCManager
extends java.lang.Object

This class represents the main entry point to access Remote Procedure Call services. There are two basic functionalities:

The class provides methods that implement these functionalities. The protocol used to perform the remote calls is hidden to the user. The current implementation uses Xml Rpc over a socket connection. The following example shows how a remote method can be invoked:
 RPCManager manager = RPCManager.getInstance();
 // Invoke TestMethod with no arguments
 RPCParam res = manager.invoke("TestMethod", null);
 // We expect a string in return
 String retState = res.getStringValue();
 
It is also possible to publish a method that can be invoked from remote parties. The following example shows an example:

  private class GetStateInfoMethod extends RPCMethod {

      public GetStateInfoMethod() {
          super("getStateInfo");
      }

      public RPCParam execute(RPCParam[] params) throws Exception {
          // We expect one parameter (the state name)
          if (params.length != 1) {
              throw new IllegalArgumentException("Expected one parameter");
          }
          RPCParam param = params[0];
          if (param.getType() != RPCParam.TYPE_STRING) {
              throw new IllegalArgumentException("Expected a string parameter");
          }

          // Perform the operation
          String res = "No info available";
          RPCParam ret = new RPCParam();
          ret.setStringValue(res);
          return ret;
      }
  }



  RPCManager manager = RPCManager.getInstance();
  GetStateInfoMethod method1 = new GetStateInfoMethod(this);
  manager.register(method1);

 
The class GetStateInfoMethod is an extension of RPCMethod and it is used to represent the method getStateInfo which is the method being published. Its method execute is invoked on remote invokation. The list of input parameters is in the params parameter and the method can return one value (or null if its type is void). The rest of the example shows the mechanism in the RPCManager to register (or publish) a method).


Method Summary
static RPCManager getInstance()
          Default singleton instance access method
 RPCParam invoke(java.lang.String methodName, RPCParam[] params)
          Invoke a remote method.
 void messageReceived(java.lang.String msg)
          This method is called by the RPCServer on incoming messages.
 void messageSent()
          This method is called by the RPCServer on outgoing messages that are sent.
 void register(RPCMethod method)
          Register a method so that is is made available externally.
 void serviceConnected()
          This method is called by the RPCServer on service connection.
 void serviceDisconnected()
          This method is called by the RPCServer on service disconnection.
 void serviceListening()
          This method is called by the RPCServer when the service starts listening for incoming messages (after the connection phase).
 void serviceStopped()
          This method is called by the RPCServer on service connection termination.
 void setRPCServer(com.funambol.client.ipc.rpc.RPCServer service)
          This method allows the user to set its own RPCServer.
 void start()
          Start the service if it is not running already.
 void stop()
          Stops the service.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getInstance

public static RPCManager getInstance()
Default singleton instance access method

Returns:
RPCManager the only available instance of this class

setRPCServer

public void setRPCServer(com.funambol.client.ipc.rpc.RPCServer service)
This method allows the user to set its own RPCServer. This is normally not intended for normal uses, but it is required to mock the RPCServer in unit tests.

Parameters:
service - the RPCServer

invoke

public RPCParam invoke(java.lang.String methodName,
                       RPCParam[] params)
                throws RPCException
Invoke a remote method. The method is synchronous, it stops the calling thread execution until a response is received from the remote server (or an exception is thrown). This method is synchronized, as it serves one request at a time.

Parameters:
methodName - the name of the method
params - the list of parameters (can be null if no parameters are given)
Returns:
a RPCParam representing the return value (it can be null if the method is void)
Throws:
RPCException - if an exception occurs during the remote invokation

register

public void register(RPCMethod method)
Register a method so that is is made available externally.

Parameters:
method - the method descriptor (@see RPCMethod)

stop

public void stop()
Stops the service. This operation may take some time, and the call is asynchronous. It may return before the service is actually stopped.


start

public void start()
Start the service if it is not running already. The call is synchronous and the method returns when the underlying service is actually running or an error stopped it. After this call returns, it is possible to check if the service is running by invoking isRunning().


messageReceived

public void messageReceived(java.lang.String msg)
This method is called by the RPCServer on incoming messages. It is not meant for the service user, but it is the implementation of the RPCServerListener interface.

Parameters:
msg - the received message

messageSent

public void messageSent()
This method is called by the RPCServer on outgoing messages that are sent. It is not meant for the service user, but it is the implementation of the RPCServerListener interface.


serviceConnected

public void serviceConnected()
This method is called by the RPCServer on service connection. When the connection is established, this method is called. It is part of the implementation of the RPCServerListener interface.


serviceDisconnected

public void serviceDisconnected()
This method is called by the RPCServer on service disconnection. When the connection is dropped, this method is called. It is part of the implementation of the RPCServerListener interface.


serviceListening

public void serviceListening()
This method is called by the RPCServer when the service starts listening for incoming messages (after the connection phase).


serviceStopped

public void serviceStopped()
This method is called by the RPCServer on service connection termination. When the connection is established, this method is called. It is part of the implementation of the RPCServerListener interface.



Copyright © 2001-2009 Funambol.