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
The parameters are:
- -D: Display debugging msgs
- -h tsserver: Specify TSpaces server. Default is "localhost"
- url: Valid URL or filename. Default is "file:/c:/test.txt"
Note: 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.
|
X-10 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
|
|
|
