org.lsst.ccs.utilities.dispatch
Class InvocationDispenser

java.lang.Object
  org.lsst.ccs.utilities.dispatch.InvocationDispenser

public class InvocationDispenser
extends Object

Typical use of this pattern is to have two threads:

• one is going to write commands to a stream. Before writing the command data the calling thread registers a code that may handle the corresponding asynchronous reply. This is done by invoking one of the register methods. So there must be a token that must be sent with the command and must be delivered with the correponding response.
• The other Thread is reading responses on a stream. Each time it receives a response it gathers: the token needed for correlation, and the data needed to execute the response code. The correlation token and the data is passed to the callBack method of the InvocationDispenser

examples:

     public synchronized void replytoA(Object elem1, elem2) {
         //do something
     }
     public void sendCommandA(Object someData) {
        String token = this.myInvocationDispenser.register( new Invoker() {
        public void invoke(Object... args) {
            //check args ?
            replytoA(args[0], args[1]) ;
        }

        } ) ;
        ACommand toBeSent = buildCommand(token, someData) ;
        sendCommand(toBeSent)
     }
 

The listening Thread :

     public void run() {
         while(doItAgain) {
             // don't forget exception handling!
             CommandData receivedData = readReply() ;
             String correlationString =  receivedData.getToken() ;
             Object[] responseData = receivedData.getData() ;
             myInvocationDispenser.callBack(correlationString, responseData) ;
         }
     }
 

Author:

bamade

Nested Class Summary

static class

InvocationDispenser.TokenLostException

Constructor Summary

InvocationDispenser()

Method Summary

Object	call(String token, Object... args) calls the registered invoker which corresponds to the token.
Object	callBack(String token, Object... args) calls the registered invoker which corresponds to the token.
void	dumpTask(String token) Removes a response task
String	generateToken() generates a unique token (for this ClassLoader context!)
boolean	isTokenUsed(String token) tells if the token is known.
String	register(Invoker invoker) registers an Invoker and returns a token to be used to run the invocation code
String	register(String token, Invoker invoker) registers an invoker and the token is given by the calling code.
Future	registerFuture(String token, Invoker invoker) Gets a Future object from this task registration.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

InvocationDispenser

public InvocationDispenser()

Method Detail

generateToken

public String generateToken()

generates a unique token (for this ClassLoader context!)

Returns:

register

public String register(Invoker invoker)

registers an Invoker and returns a token to be used to run the invocation code

Parameters:

invoker - should not be null.

Returns:

register

public String register(String token,
                       Invoker invoker)

registers an invoker and the token is given by the calling code.

Parameters:

token -

invoker -

Returns:

registerFuture

public Future registerFuture(String token,
                             Invoker invoker)

Gets a Future object from this task registration. This can be used by methods that are "nearly synchronous" : that is it is a synchronous call but the process that reads the response may be polluted by other incoming events.

Exemple of call may be :

      public String pleaseCall(String arg) {
           String token = myInvocationDispenser.generateToken() ;
          Future future = registerFuture(token, new Invoker() {
              public Object invoke(Object... args) {
                  return args[0] ;
              }
          }
        ACommand toBeSent = buildCommand(token, arg) ;
        sendCommand(toBeSent)
          return (String) future.get() ;
      }
  

Parameters:

token -

invoker -

Returns:

dumpTask

public void dumpTask(String token)

Removes a response task

Parameters:

token -

isTokenUsed

public boolean isTokenUsed(String token)

tells if the token is known. beware : in a multihreaded environment there may be race condition where this method returns true but where an Exception is fired upon call of callback Method.

Parameters:

token -

Returns:

callBack

public Object callBack(String token,
                       Object... args)
                throws Exception

calls the registered invoker which corresponds to the token. The token is no longer valid.

Parameters:

token -

args -

Returns:

Throws:

InvocationDispenser.TokenLostException

Exception

call

public Object call(String token,
                   Object... args)
            throws Exception

calls the registered invoker which corresponds to the token. The token is still valid. That is to be used when there is a registration of a code that is to treat purely incoming events (without a corresponding send). The invoker should be able to run many times.

Parameters:

token -

args -

Returns:

Throws:

InvocationDispenser.TokenLostException

Exception