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.
Additional information on starting the server and the available options
can be found in the
Programmer's Guide.
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.
If you are already viewing this page by using the
HTTP server
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
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.
http://localname:8201/html/examples.html#whiteboard
where "localname" is the name of the system that is running
the TSpaces server.
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.
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 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:
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.
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:
To run all of the Simple examples, issue the following command:
bin\simpleThis will run the examples that are described below and the examples that are described in the Programmer's Guide.
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 resultThe 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.
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.
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:
This is a chatroom facility that uses TSpaces instead of IRC.
Written by Kevin Eustice kevin@cs.hmc.edu