com.ibm.tspaces.examples.simple
Class Example3

java.lang.Object
  |
  +--com.ibm.tspaces.examples.simple.Example3

public class Example3

extends java.lang.Object

implements Callback, java.lang.Runnable

Show how a client can register for events that are happening to a tuple space. This class will implement the Callback interface which requires that it have a "call" method. An instance of this class will be specified as a parameter to "eventRegister". Then when the event that we are waiting for occurs, the call method for the object will be given control.

 This example has 3 important Threads 
   - main    Thread that is started for the main method and also has control
             when the test() method is called.
             It will delete the Tuples that are written to the space.

   - run     This is the Thread that is started by the main() method and uses 
             the run() method to implement the thread.  
             This thread will write tuples to the space.  Normally this would 
             done by another application.
   
   - callback This is the callback thread.  This thread is started when the 
             TupleSpace is initially created and it handles the information 
             that is returned from TupleSpace commands.  It also is used 
             to implement Event Callbacks by invoking the call() method.
             Note that the user does not create this thread.  
 

This example how to register for TupleSpace events and how to correctly pass the tuples from the callback to other threads that will process them.

Author:

John Thomas

See Also:

Callback, Waiter, TupleSpace

Constructor Summary

Example3()
The constructor for this class will setup everything so that the call method will be given control when interesting things happen to the related TupleSpace

Method Summary

boolean	call(java.lang.String eventName, java.lang.String tsName, int seqNum, SuperTuple tuple, boolean isException) Implementation for the Callback interface.
static void	main(java.lang.String[] argv) The main method for this class
void	run() This run method will write some Tuples to the space This could represent the actions of another client.
void	test() This represents the main application processing.

Methods inherited from class java.lang.Object

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

Constructor Detail

Example3

public Example3()

The constructor for this class will setup everything so that the call method will be given control when interesting things happen to the related TupleSpace

Method Detail

run

public void run()

This run method will write some Tuples to the space This could represent the actions of another client.

Specified by:

run in interface java.lang.Runnable

test

public void test()

This represents the main application processing. It waits for a Tuple to appear in a Vector that represents a queue of work to be done. If there is a Tuple in the queue it will remove it from the queue and process it. In this case, it just deletes the tuples. When we get a tuple that has "quit" as the 2nd field then we clean up and leave. We could write a better queueing facility but this is supposed to be a simple example.

call

public boolean call(java.lang.String eventName,
                    java.lang.String tsName,
                    int seqNum,
                    SuperTuple tuple,
                    boolean isException)

Implementation for the Callback interface. call an application back with a tuple it requested. In the case of an exceptional condition occurring on the server, isException will be true and the exception will be inside the tuple_, i.e., the tuple will contain one field that is a TupleSpaceServerException.

EventRegister has an otional parameter that controls whether the callback is processed in the same thread that reads the response from server or whether a new Thread is started to process the callback.

The default is to use the same thread and simply callthe callback thread. Thus in this case the callback should be really quick and return, that is it should not take up lots of time. Typically, it might just check that an exception was not thrown and if not then queue up the tuple and wake up some other thread that will do the real processing, Likewise in default case, Because this method is running in a thread that reports all callbacks from the server, it is important that the call() method (or any method that it invokes directly) do not invoke another TupleSpace command. This would cause the communication to the TSpaces Server to hang.

However if eventRegister(cmd,template,callback,true) is specified then the callback will be in a new thread and there are no restrictions. Also, normally the call() method will return false. It would return true only if this is the last call this callback class is expecting. For a one time read or in etc this is the case, but for EventHandlers, this is not the case, they will keep on servicing more and more events.

Specified by:

call in interface Callback

Parameters:

eventName_ - String that indicates what type of TupleSpace action "Write" or "Delete" caused this call. Note that only events that a cause a Write or Delete to be done are reported. A READ operation at the server is not reported.

tsName_ - the name of the tuple space this command was executed on.

sequenceNumber_ - the sequenceNumber for this event/command

tuple_ - the returned tuple or a Tuple with an exception inside

isException_ - was the command processed normaly or was there an exception

Returns:

return false normally, true if this is the last call this method should be getting.

See Also:

TupleSpace, CallbackThread

main

public static void main(java.lang.String[] argv)

The main method for this class