Using the BrokerClient

Connecting to the Broker

The first thing you must do before using the BrokerClient is to connect to the broker. This is done with the connect() method:

public void connect() throws ServerDownException

If a connection could not be made to the broker, a ServerDownException will be thrown. If this should happen, your application will probably either terminate or try again later.

Making Procedure Calls

Procedure calls are calls to methods made in such a way that any result or error condition is discarded.
They are made with the callProc method, which returns immediately. Be aware of the risk of making calls without knowing if they succeed or not!

public void callProc(String server,

                      String data) throws ServerDownException

The parameters are the name of the server to be called, and the one line of data which identifies the method and any parameters it takes.

If the connection to the Broker has been lost, a ServerDownException will be thrown.

NOTE: There should be an equivalent method which takes an array or a Vector of Strings for multiline calls, but this has not been implemented yet. If you need this functionality, send me an e-mail and I'll implement it.

Making Function Calls

Function calls are made in a similar way, but they block until a reply is received (either the result or an error):

public Object callFunc(String server,

                       String data) throws BrokerException, ServerDownException

The BrokerException is thrown if an error condition is recieved from the called method, and its message is set to the error message from the method. The ServerDownException is thrown

The reply can be either a String or a java.util.Vector of Strings (in the case of a multi-line return.) You can check which is the case by using Java's instanceof operator:

Object result;

result = brokerClient.callFunc( "Adder", "add 2 3 4" );

if( result instanceof String )

  System.out.println("The result was: " + ((String) result) );

else

  throw new Error("Expected a String as the result of Add, but got something else?");

Shutting Down

Before the application terminates, it should do a clean close of the connection to the broker by calling the disconnect() method. This will cause any outstanding function calls by other threads to throw the ServerDownException.

Prev: Creating a BrokerClient Up: Using the Broker Architecture in Java Next: An example