We have included a number of sample programs with the TSpaces package. These examples are not intended as complete useful application but rather each one is intended to show the use of one or more features.  The source for each sample is distributed along with the pre compiled class file and one or more shell scripts that will invoke the sample.

In the following examples, I will assume that you are running on Win95 or NT. OS/2 users will need to rename the *.bat files to *.cmd. We have provided a limited number of *.sh scripts for Unix users. Unix users will have to make the necessary translations for their cmdline environment. We would like to distribute whatever is needed to implement Mac support and would welcome a volunteer to help us with this.

The included scripts assume that the current directory is the "tspaces" directory that is created when you unzip (or untar) the distribution file.

We also have a directory of TSpaces applications that have been contributed by people outside of IBM.

TSpaces Server

This is not really an example program, but a script to start a TSpaces server. All of the examples require that a TSpaces (TupleSpace) server be started on either the local host or on a network attached host. So we have provided a shell script that will start a TSpaces server on the local host. Although all of the examples will run with the server running on one system and the example on another, for simplicity, we will assume that both are on the same system.
Before trying to start the server, you should make the current directory be the high level tspaces directory that is created when you unzip the distribution file. Then you should invoke:

bin\tspaces.bat

Additional information on starting the server and the available options can be found in the Programmer's Guide.

Whiteboard

This is a very simple shared whiteboard application.  Multiple users can startup the whiteboard application or applet, all pointing to the same server and the lines and points that are drawn on each white board will be written to TSpaces when the "publish" button is pressed.  Since all Whiteboard  applications have used the TSpaces "eventRegister", they will all be notified and will display the new lines/points in their own window.

To invoke the Whiteboard applet from your browser:

If you are viewing this page from the Almaden Web site and if you have started your own version of the TSpaces server on a local system, then manually enter the following URL into your browser to access the HTTP server that is built into TSpaces.

  http://localname:8201/html/examples.html#whiteboard

where "localname" is the name of the system that is running the TSpaces server.

If you are already viewing this page by using the HTTP server that is built into TSpaces, then either:

click here to use the Java PlugIn technology from Sun, If you have not already installed the Java PlugIn, you will be prompted to install it.

or click here to use the native java support in Netscape or Microsoft IE. If your browser does not support the Java PlugIn, then you can invoke the Whiteboard via the appletviewer by issuing the following command:


bin\whiteboard  applet [hostname]

The parameters are:
   applet   - Causes the appletviewer to be used.
   hostname - Host name (defaults to localhost)

It will also run as a Java application by issuing the following commands


bin\whiteboard   [hostname]

The parameters are:
   hostname - Host name (defaults to localhost)

The most important part of the whiteboard demo is that it shows how easy it is to write a multi-client application using TSpaces. The web page shows the important code fragments that implement the TSpaces client/server communication. It also shows the interface to the HTTP Server that is built into the TSpaces Server for use in debugging.

MergeSort

This example shows a typical use of TSpaces for distributed computing. The sample generates a number of random numbers and writes them to TSpaces where they can be accessed and sorted by any number of SortThread tasks that are running. The SortThread tasks can be on any number of network systems.

To invoke it issue the following commands:


bin\mergesort  [number]  [hostname]

The optional parameters are:
    number   - number of things to sort (defaults to 40)
    hostname - Host name (defaults to localhost)


The script will automatically start a 2nd window to run an instance of SortThread.

TClipboard

This example shows the use of TSpaces to implement a Global Clipboard that will work across any system connected to the network. The TClipboard application will display a window with 4 Text areas. The top text area shows the contents of the System clipboard on the local system. The other 3 text areas show the contents of 3 buffers that are stored on TSpaces and can be accessed from any system.

The idea is that the user has multiple clipboard windows -- one on each of multiple machines. Something cut from one machine and placed into the clipboard automatically appears in all of the clipboards. Thus, it becomes trivial to either share cut buffer contents between users or share cut buffer contents between machines of the same user (for example, it's not uncommon for a power user to have a UNIX machine side-by-side with an NT machine or a Macintosh)

To invoke a copy of TClipboard on the local system, issue the following commands:


bin\copypaste   [-h hostname] [id]

The optional parameters are:
    id       - An id that represents a set of shared clipboards.  Could be your Userid.
    hostname - Host name (defaults to localhost)

To do anything interesting, you need to then start TClipboard on another system, or in the case of Unix, start it under another userid. Be sure that the "id" is the same on each instance of TClipboard if you want to share the clipboard. It is not recommended to start 2 instances of TClipboard on the same system because they will fight over ownership of the single System clipboard and give confusing results.

To do a copy/paste from an application of one system to another application on another system, do the following:

• System_A: Cut/copy (Ctrl-C) some String of data from any application.
• System_A: Verify that it shows up in the System Clipboard window of TClipboard
• System_A: Copy the data into Buffer 1 (using the Publish button)
• System_B: Verify that the data appears in Buffer 1 on System_B's TClipboard
• System_B: Copy the data from Buffer 1 to the System clipboard using the Read button.
• System_B: Paste(Cntrl-V) the data into any application on System_B
Or you can select the AutoRead and AutoPublish options on each system and whatever you copy or cut on one system will automatically appear in the system clipboard of the other system. Now you can iconify the java applications and enjoy your new Global clipboard facility.

URLCopy

This is an example of how to use TSpaces to copy the data that is pointed to by a URL along with a Tuple. The URLCopy object has been provided as special TSpaces aware object that represents a URL or File object that can be cpopied between TSpaces clients via TSpaces services.

To invoke the example, issue the following command:


bin\urlcopy [-D] [-h tsserver]  url 

  -D           -  display debugging msgs
  -h tsserver  - specify TSpaces server. Default is "localhost"
  url          - Valid URL or filename.  Default is "file:/c:/test.txt"

To run this example you must first turn on the FileStore facility in the server by specifing the directory where copied files will be stored. This is specified in the tspaces.cfg file. Restart the server after making this change.

Rhonda

This is an example of the use of the Rhonda operator in TSpaces. The rhonda operator takes a tuple as an argument and atomically swaps two matching tuples. That is, if process 1 and process 2 perform rhondas with Tuples that have the same templates, the tuple that is returned to them is the other processes tuple. This is useful for atomic synchronization.

The sample RockPaperScissors example starts two Java TSpaces applications each talking to the same TSpaces server. These two applications then play the Rock PaperScissors game. by issuing a "Rhonda" command with a template that contains their name and their choice of "R","P", or "S". They then look at the tuple that is returned from the other player to determine if they won, lost or tied.

To invoke it issue the following commands:


bin\rhonda

In case you are not familiar with the game RockPaperScissors (also know as RoShamBo), each player at the count of three, puts out their hand with a fist(Rock), a flat palm(Paper) or two fingers(Scissors). The winner is determined by the following rules:

• Rock breaks Scissors
• Scissors cut Paper
• Paper covers Rock

Simple

In contrast to the previous examples which had limited but useful functions, the Simple set of examples are only there to demonstrate how one would might write some simple TSpaces client code. By keeping the examples, very small and simple, it is hoped that it will be easy to learn by example.

To run all of the Simple examples, issue the following command:


bin\simple

This will run the examples that are described below and the examples that are described in the Programmer's Guide.

Description of Simple Examples

• Simple1
  This example writes a couple of tuples (an ordered set of fields) to the TSpaces server and then reads the tuples back using 2 different methods.

• SubclassExample1
  This example is similar to Simple1 but instead of directly creating and querying the Tuple directly, an object is created that extends SubclassableTuple and hides all of the ugly Tuple manipulation inside the object.

• SuperHeros
  This example was inspired by a published paper on TSpaces. It shows the use of "named fields" in a Tuple and the query operations that are available with a TSpaces server that implements the TSpaces Main Memory database.

  One of the differentiating features of TSpaces is that it builds an index on each named field in a tuple. This enables clients to request tuples based solely on values in fields with a given name, regardless of the structure of the rest of the tuple (or even the position of the named field within the tuple). For example, an index query of the form ("foo",8) will select all tuples (of any format) containing a field named "foo" with the integer value 8. It is also possible to specify a range of values to be found in the index.

  The current implementation of TSpaces provides four types of queries: Match, Index, And and Or queries. A Match query performs structural or object compatibility matching (depending on its argument), while an Index query performs a named-field query. And and Or queries can be used to combine these and build complex query trees. The SuperHeros example shows an example of each of these queries.

Worker

This class implements a TupleSpace worker that will take a Runnable object from a space and run it.

This class is inspired by the book MirrorWorld by David Gelernter. This implements his idea of clients that will grab tuples that contain eval() functions, run the procedure indicated by the eval() and then return the answer to the tuplespace. This does not, however, work the same as the eval operator in the Linda system.

In our case, the eval() function is represented by a Tuple that has a Field containing a Java Object that has an Eval interface. The Eval interface extends Runnable and Serializble. Eval defines one method, getResult() that returns a Serializable Object.

A client that has work that can be processed by other randon processors will write a Tuple to the Worker space that has the following format:

  Field 0   String  "Worker"   (WORKER_KEY)
  Field 1   String  type       Any type string that the user wants to assign
  Field 2   String  uniqueid   Any Id that is unique.  We use this to 
                               reflect back the result.
  Field 3   Eval    object     Any Object that contains a run() method that 
                               can be started.

There can be one or more Worker clients on many machines in the network, all of which are waiting for work Tuples in the above format. When it get one of these Tuples, it will start a thread that will invoke the run() method for the Eval object. When the run method ends, it will regain control, use the getResult method to get the result and write the the following Tuple back into the space.

  Field 0   String  "WorkerResult"   (WORKER_RESULT)
  Field 1   String  type       Copied from input Tuple
  Field 2   String  uniqueid   Copied from input Tuple
  Field 3   Serializable result  Object that contains the result 
            

The program that is creating the work to be done will do the following: Assume that WorkerTest is a class whose run method does the work to be shared

   TupleSpace work = new TupleSpace(Worker._TSNAME,tsHost);
   
   WorkerTest wt = new WorkerTest(param1,param2);
   Tuple workTuple = new Tuple(Worker.WORKER_KEY,"WorkerTest","id1",wt);
   work.write(workTuple);
   Tuple template = new Tuple(Worker.WORKER_RESULT,"WorkerTest","id1",new Field(Serializable.class));
   Tuple result = work.waitToTake(template);

The constructor for WorkerTest would store any parameters needed by the run method as instance variables.

When the Worker client takes one of the above Tuples from the space, it starts a new thread with the following code:

       Eval task = (Eval)workTuple.getField(3).getValue();
       String type = (String)workTuple.getField(1).getValue();
       String id = (String)workTuple.getField(2.getValue();
       Thread t = new Thread(task,type+"-"+id);
       t.start();
       t.join();

When the run() method completes, we get back control at the join() and we will write back a Tuple that contains the result

Note that your application could also use the Eval interface above to implement your own Tuples that could share processing. For example, you could have a client that passes the input data and run method that produces a chart instead of passing the formated chart.

The intent is that one would start a worker thread on each of the machines in a network and allow anyone that needed extra compute power, to use Eval objects to spread the work to other machines.

If you start a Worker thread to share your CPU processor, you would want to be assured that the Eval threads run in a Java sandbox that it has restrictions similar to applets that run in a browser. With JDK 1.2, This is relatively easy to do. The distributed worker.bat file can be modified to specify the following (on a single line):

java -Djava.security.manager 
     -Djava.security.policy=file:/c:/.java.policy 
      com.ibm.tspaces.services.Worker %1 %2 %3 %

The file "c:/.java.policy" should have the following contents:

grant {
  // allows anyone to connect  on un-privileged ports
  permission java.net.SocketPermission "*:1024-", "listen, connect, resolve";
};

The above combination will tell Java to run with a Security manager and only grant permission to connect to un-privileged ports on any machine. One could modify the above to restrict the machines or perhaps grant other permissions.

An example of the use of Worker is in SortMerge2.java which uses the Merger.java object to do the merge/sort using Worker threads. This code can be found in the examples/sortmerge directory.

TupleSpaceUI

TupleSpaceUI is a simple little command line tool that allows you to dynamically read and write Tuples to an space.

To invoke the TupleSpaceUI, type:

cd /tspaces
set classpath=.\classes;.\lib\tspaces.jar
java com.ibm.tspaces.examples.tsui.TupleSpaceUI

This will bring up a prompt, at which you can type various commands, (type h for help), if you are familiar with the tuplespace commands, these enable you to manually enter a tuple and issue one of the commands with it (read, write, scan, take). After choosing one of these commands, you will be prompted to create a tuple. This is done one field at a time, first by entering the type of the field (only a few primitive types are supported: int, string, boolean, double, tuple), and then the value. If you enter a tuple as the type of the field, the program will automatically descend into that new tuple and prompt you for fields in there. For further help, type 'h', you can add and change fields, but removal of fields is not yet supported. After you have the desired fields, type 'x' to perform the selected action on the tuple. If the action is a read, take or scan, then the returned tuple(s) will be displayed. You can also write XML documents and perform basic XQL queries, by choosing wxml or qxml from the main menu. They prompt you for a file name where the XML/XQL can be found or you can type it in if you desire. You will need the xml4j.jar file in your classpath however.

X10 Support

X-10 is a technology that communicates to devices in the home by sending and receiving signals over the home power line wiring. A typical system has multiple Modules that have lights or appliances connected to them. Also plugged into the home wiring are one or more controllers that have the abiltiy to send commands to modules. One of the controllers is a computer interface that plugs into the home wiring and has a connection to the serial port on a computer. Another typical controller is a tranceiver that will pick up radio frequency (RF) commands from devices like motion detectors and handheld remote controls. For more information see the www.x10.com site.

We have written a Java monitor application that will connect to the serial port and both watch for X10 events and when instructed send a X10 command to a module. The X10 events are reflected to a TSpaces server where it will then maintain the status of a module (The light is on or off). Comamnds for an X10 device can be written to TSpaces and the monitor will pick up the command and issue it to the device via the computer interface.

As a result, one can write very simple java programs to interface to X10 without having to learn the complex serial port interface and the devices can be monitored and controlled from any site in the network.

To make this clearer, I will describe the demo setup that I have implemented. The source for this is in tspaces/examples/x10. In my home office, I have a motion detector that can sense when I am in the office and a light that is plugged into an X10 Module. I run the TSX10 application on my office computer that has a X10 PC interface. When the motion detector detects motion it sends "A3 On", the TSX10 application sees the event and updates a tuple to < "X10Status", "A3", "ON" >. When the motion detector detects that there is no motion, it sends "A3 off" and TSX10 changes the tuple to < "X10Status", "A3", "OFF" > I also have an applet that can run on any browser. It will connect to the same TSpaces server and issue Read <"X10Status","A3",*> and get back the current status and display whether I am in the office.

The same demo applet also has Lamp On and Off buttons. When the user presses the ON button, a tuple <"X10Cmd","A2","On"> is written to the space. X10Monitor is waiting for "X10Cmd" tuples and when one appears in the space it will be read and in this case, the lamp with device address "A2" will be turned on.

This test setup does not do anything really useful, but it is easy to see how one might be able to use this technology. Some examples:

• If you tend to leave work at very different hours, just before you leave your office you could turn on your heating system using the X-10 thermostat module.
• With the Palm Pilot PDA support for TSpaces, you could use your Pilot to control all of the lights in your house or use it as an expensive garage door opener.
• If someone walks up to your front door, you could trigger a camera to take a picture, store it and based on whether you were in your home office, notify you on your desktop or using the TSpaces pager support, send you a page.
• Since the basic X10 kit comes with a multipurpose remote control that can control traditional devices like a TV and also will issue X10 commands. So you could define address "A5" as a virtual devices. Then "A5" is turned on by the remote control, it would write a Tuple to TSpaces. You could have another TSpaces client running anywhere on the network that would be watching for an "A5 on" event and when found it would take some action. So while you are watching TV, using the remote, you could have a TSpaces client check your mail and if any present, flash a light in your living room.
• Getting X10 running with TSpaces
  
  • Download the Java Communication API product and install it as instructed.
  • Modify the bin\x10.bat file to specify comm.jar in the classpath.
  • Invoke bin\x10.bat

---

Contributed TSpaces Applications

The tspaces/contrib directory contains applications that have been contributed by people outside of IBM. Please contact the author directly if you have comments or problems with the contributed code.
• ITC Client/Server

  This is a chatroom facility that uses TSpaces instead of IRC.

  Written by Kevin Eustice kevin@cs.hmc.edu

---

[ TSpaces home page ]