com.ibm.tspaces
Class TupleSpace

java.lang.Object
  |
  +--com.ibm.tspaces.TupleSpace

public class TupleSpace
extends java.lang.Object

A TupleSpace is a shared named collection (bag) of Tuples. The basic operations supported by the collection are to add a Tuple to the space (write), and to remove one from the space (take).

The collection is stored and administered across a network on one or more "Tuple Space Servers". Several threads on the same or different machines can be accessing the space simultaneously. Some will be adding tuples to the space and some removing them.

A client thread accesses the collection/space using the methods of an instance of this class. For each different Tuple Space a client wishes to access, it requires a separate instance of this class, even if they are managed by the same server. The details of how the operations are completed are hidden from the user. All they need is the name of the space, and the name of a server that manages that space.

Some of the primitive operations supported by the space are:


  We have created some conventions for using Tuples:
  (*) Top level Tuples are always sent from client to server with the following format:
     (*) Field 0: A unique client side sequence number: used to identify which request
 		 a response corresponds to.
     (*) Field 1: A command tuple which is the actual request and looks like:
		
 	     (*) Field 0: TupleSpace name (string)
	     (*) Field 1: Command (string)
 	     (*) Field 2: Data Tuple
     (*) Field 2: A unique id for the client and is the String 
                  clientHostName + clientThreadIDName

  (*) Top level Tuples are always sent from server to client with the following format:
  	(*) Field 0: Status (string) can be TupleSpace.OK or TupleSpace.EXCEPTION
      (*) Field 1: Sequence Number (integer)
	(*) Field 2: returnValue (supertuple) the returned tuple if all went ok else a Tuple with an exception message inside

      The data tuple is interpreted according to the command:
      (*) WRITE:  The client is submitting a tuple to be added to the space.
               The datatuple is that new tuple.
      (*) TAKE: The client is submitting a tuple to be used to query
               the space.  The datatuple is that query tuple.
      (*) READ:The client is submitting a tuple to be used to query
               the space.  The datatuple is that query tuple.
      (*) COUNT:The client is submitting a tuple to be used to query
               the space.  The datatuple is that query tuple.
      (*) SCAN:The client is submitting a tuple to be used to query
               the space (scan it, actually).  The datatuple is that query tuple.
      (*) IN_REPLY: The Server is replying on the status of the IN command
              sent by the client.  The datatuple is the status report.
      (*) OUT_REPLY: The Server is replying to the OUT command sent by
              the client.  The data tuple is the output tuple that is the
              result of the query.  The data tuple should not be NULL.
      (*) READ_REPLY:  The Server is replying to the READ command sent by
              the client.  The data tuple is the output tuple that is the
              result of the query.  The data tuple may be NULL if the
              results of the read are empty.
      (*) WRITE_REPLY: The Server is replying to the WRITE command sent by
              the client.    The data tuple contains a single value
              (TupleID), which is the uniqueId of the Tuple within the space.
      (*) COUNT_REPLY: The Server is replying to the COUNT command sent by
              the client.  The data tuple is the output tuple that is the
              result of the count query.  The data tuple contains a single
              number, which is the result of the count.  The count may be
              ZERO, but it will not be NULL.
      (*) SCAN_REPLY: The Server is replying to the SCAN command sent by
              the client.  The data tuple is the output tuple that is the
              result of the scan query.  The data tuple contains a set of
              tuples that satisfy the scan query.  The data tuple will
              contain an "empty" tuple if the scan results are empty, but
              the data tuple itself will not be NULL.
      (*) ERROR_REPLY: The Server is replying to one of the client messages,
              with an error.  The data tuple contains an error message.
              (There is room for growth here, when we get into unknown
              class messages, and so on.)

 (*) The communication protocol:

 The communication between the client and server is handled by 
 an implementation of TSCmd.  
 TSCmd is an interface that has the following methods defined. 
   command(cmdnmae, argTuple, tsname, transactionid)
 The Implementation of TSCmd must have a constructor that takes 
 the following arguments:
   String - Host name
   int    - Host port
   String - Username 
   String - Password

Author:
Daniel Ford, Toby Lehman, Peter Wyckoff, Stephen McLaughry, John Thomas
See Also:
Field, Tuple

Field Summary
static java.lang.String _ADMIN_TSNAME
          the name of the admin tuple space.
protected  java.util.Vector _currTransactions
          A list of the currently active transactions.
static java.lang.String _DBTYPE_MMDB
           
static java.lang.String _DBTYPE_SMALLDB
           
static java.lang.String _DEFAULT_DBTYPE
           
static int _DEFAULT_INDEX_FIELD
           
static java.lang.String _DEFAULT_PASSWORD
           
static boolean _DEFAULT_PERSISTENCE
          Whether a tuple space is persistent by default and its index -1 indicates no index and what type
static java.lang.String _DEFAULT_USER
          This is what is used if no user/password is specified
protected static java.lang.String _defaultPassword
          The password for this space.
protected static java.lang.String _defaultUserName
          The Userid used for TupleSpace operations.
static int _FIRST_CMD
          Indicates that the command being sent is the first one in a long transaction At the server side, the command will be preceded by a beginTrans
static java.lang.String _GALAXY_TSNAME
          the galaxy tuple space name.
protected  boolean _isPersistent
          is this tuple space persistent?
static int _NORMAL_CMD
          Indicates that the command being sent is part of a larger transaction.
protected  java.lang.String _password
          The password for this space.
static int _STAND_ALONE_CMD
          Indicates that the command being sent is not part of any bigger transaction At the server side, the command will be preceded by a beginTrans and succeeded by a commitTrans
static java.lang.String _TOP_GROUP
          the default top group that everyone is a part of.
protected  java.lang.String _tsName
          The name of the tuple space.
protected  int _tsPort
          The port for this space's server.
protected  java.lang.String _tsServer
          The name of the machine running the TupleSpace server
protected  java.lang.String _userName
          The username for this space.
protected  boolean _userNameAlreadyUsed
          A flag to make sure we don't change the username after the connection has been verified.
static java.lang.String _VERSION
          Code Version.Level.Modification Change this when a new level of code is to be released
static java.lang.String ABORT
          The string used to signal an abort operation.
static java.lang.String ABORTTRANS
           
static java.lang.String ADDFACTORY
           
static java.lang.String ADDHANDLER
           
static java.lang.String BEGINTRANS
           
static java.lang.String CHECKPOINT
           
static int CLI_ID
           
static java.lang.String CLOSE
           
static int CMD_FLAG
           
static int CMD_TUP
           
static java.lang.String COMMITTRANS
           
static java.lang.String CONSUMINGSCAN
           
static java.lang.String COUNT
           
protected static int DEFAULTCONNECTTRIES
          the number of times to try to connect to the server before raising an exception to the caller.
static java.lang.String DEFAULTHOST
          The default name of the machine running the TupleSpace server.
static java.lang.String DEFAULTNAME
          The default name of a TupleSpace if one isn't specified.
static int DEFAULTPORT
          The default port number used to connect to the TupleSpace server if a port number isn't specified (the usual case).
static java.lang.String DELETE
           
static java.lang.String DELETEALL
           
static java.lang.String DELETETUPLEBYID
           
static int EVENT_ACTION_FLD
           
static int EVENT_COMMAND_FLD
          the fields of an event tuple, keep with the making of the event templates until things stabilize pw.
static java.lang.String EVENT_DEREGISTER
           
static int EVENT_EAT_FLD
           
static java.lang.String EVENT_REGISTER
           
static int EVENT_SEQ_FLD
           
static int EVENT_TUPLE_FLD
           
static java.lang.String EXCEPTION
          The string used between the server and tspace library to signal a problem.
static java.lang.String INDEXCREATE
           
static java.lang.String INDEXDESTROY
           
static java.lang.String INDEXFIELD
           
static java.lang.String INDEXSTATUS
           
static java.lang.String MULTIUPDATE
           
static java.lang.String MULTIWRITE
           
static java.lang.String OK
          The string used between the server to signal good the operation completely normally.
static java.lang.String PERSISTENCE
          configuration field names.
static java.lang.String PURGEWAIT
           
static java.lang.String READ
           
static java.lang.String READTUPLEBYID
           
static java.lang.String RHONDA
           
static java.lang.String SCAN
           
static java.lang.String SCANALL
           
static int SEQ_NUM
          The top level tuple sent to the server has four fields ( Seq #, CmdTuple, clientID, Flag)
static java.lang.String SHUTDOWN
           
static java.lang.String STATUS
           
static java.lang.String TAKE
           
static java.lang.String TAKETUPLEBYID
           
static int TS_ARG
           
static int TS_CMD
           
static int TS_NAME
           
static int TS_RETURN_VALUE
           
static int TS_STATUS_CODE
           
static java.lang.String TSACCESS
           
static java.lang.String TSCMD_LOCAL_IMPL
           
static java.lang.String TSCMD_SOCKET_IMPL
           
static java.lang.String TSCREATE
           
static java.lang.String TSDBTYPE
           
static java.lang.String TSDESTROY
           
static java.lang.String TSEXISTS
           
static java.lang.String UPDATE
           
static java.lang.String WAITTOREAD
           
static java.lang.String WAITTOTAKE
           
static java.lang.String WRITE
           
 
Constructor Summary
TupleSpace()
          Create a default tuple space.
TupleSpace(java.lang.String name_)
          Create a named Tuple Space.
TupleSpace(java.lang.String name_, java.lang.String tsServer_)
          Create a named Tuple Space to be stored and managed by a specified Tuple Space Server.
TupleSpace(java.lang.String name_, java.lang.String tsServer_, int tsPort_)
          Create a named Tuple Space to be stored and managed by a specified Tuple Space Server.
TupleSpace(java.lang.String name_, java.lang.String tsServer_, int tsPort_, java.lang.String userName_, java.lang.String password_)
          Create a named Tuple Space to be stored and managed by a specified Tuple Space Server.
TupleSpace(java.lang.String name_, java.lang.String tsServer_, int tsPort_, SuperTuple configuration_)
          Create a named Tuple Space to be stored and managed by a specified Tuple Space Server.
TupleSpace(java.lang.String name_, java.lang.String tsServer_, int tsPort_, SuperTuple configuration_, java.lang.String userName_, java.lang.String password_)
          Create a named Tuple Space to be stored and managed by a specified Tuple Space Server.
TupleSpace(java.lang.String name_, java.lang.String tsServer_, int tsPort_, SuperTuple configuration_, SuperTuple accessPermissions_, java.lang.String userName_, java.lang.String password_)
           Actual constructor used to create or access a named Tuple Space.
TupleSpace(java.lang.String name_, java.lang.String tsServer_, int tsPort_, SuperTuple configuration_, Tuple accessPermissions_)
          Create a named Tuple Space to be stored and managed by a specified Tuple Space Server.
TupleSpace(java.lang.String name_, java.lang.String userName_, java.lang.String password_)
          Create or access a named Tuple Space with the specified user and password .
TupleSpace(java.lang.String name_, java.lang.String tsServer_, java.lang.String userName_, java.lang.String password_)
          Create a named Tuple Space to be stored and managed by a specified Tuple Space Server.
TupleSpace(java.lang.String name_, java.lang.String tsServer_, SuperTuple configuration_)
          Create a named Tuple Space with the specified configuration to be stored and managed by a specified Tuple Space Server.
TupleSpace(java.lang.String name_, java.lang.String tsServer_, SuperTuple configuration_, java.lang.String userName_, java.lang.String password_)
          Create a named Tuple Space to be stored and managed by a specified Tuple Space Server.
TupleSpace(java.lang.String name_, SuperTuple configuration_)
          Create a named Tuple Space with the specified configuration.
TupleSpace(java.lang.String name_, SuperTuple configuration_, java.lang.String userName_, java.lang.String password_)
          Create a named Tuple Space with the specified configuration, username and password.
TupleSpace(Tuple configuration_)
          Create a default tuple space.
 
Method Summary
 void addFactory(java.lang.Class[] classes)
          add a new factory to this tuple space as the topmost (most powerful) factory.
 void addHandler(java.lang.String name, java.lang.Class[] classes)
          Add a new handler to this tuple space.
static void appletEnvironment(boolean setting)
          Class method to set the connection environemt so that it it will follow the Applet sandbox rules.
 void checkpoint()
          Tells CheckpointManager to checkpoint the space.
static void cleanup()
          this method is used to close the current connections to the server.
static void cleanup(java.lang.String server_, int port_)
          this method is used to close the current connections to the specified server.
 SuperTuple command(java.lang.String cmdString_, SuperTuple argTuple_)
          Issue a command to the TupleSpace and pass along a Tuple as an argument.
 SuperTuple command(java.lang.String cmdString_, SuperTuple argTuple_, long timeout_)
          Issue a command to the TupleSpace and pass along a Tuple as an argument.
static void connectionTries(int connectionTries_)
          Deprecated. Use setConnectionTries
static void connectionWaitTime(int connectionWaitTime_)
          Deprecated. Use setConnectionTries
 Tuple consumingScan(java.io.Serializable obj)
          Retrieve and delete all Tuples from the space that match a Tuple template.
 Tuple consumingScan(java.io.Serializable obj1, java.io.Serializable obj2)
          Retrieve and delete all Tuples from the space that match a Tuple template.
 Tuple consumingScan(java.io.Serializable obj1, java.io.Serializable obj2, java.io.Serializable obj3)
          Retrieve and delete all Tuples from the space that match a Tuple template.
 Tuple consumingScan(SuperTuple template)
          Retrieve and delete all Tuples from the space that match a Tuple template.
 Tuple count(SuperTuple template)
          Count all tuples from the space that match a Tuple template.
 int countN(SuperTuple template)
          Count all tuples from the space that match a Tuple template.
 int delete(SuperTuple template)
          Delete all tuples that match this template.
 int deleteAll()
          Delete all tuples in a space.
 void deleteTupleById(TupleID id_)
          delete a specific tuple from the space.
 void destroy()
           
 void eventDeRegister(int seqNum)
          DeRegister for some event on the server.
 int eventRegister(java.lang.String commandName_, SuperTuple argTuple_, Callback callback_)
          Register for an event on the server.
 int eventRegister(java.lang.String commandName_, SuperTuple argTuple_, Callback callback_, boolean callbackThreads_)
          Register for an event on the server.
static boolean exists(java.lang.String tsName_, java.lang.String tsServer_)
           
static boolean exists(java.lang.String tsName_, java.lang.String tsServer_, int tsPort_)
           
static int getCommandWaitTime()
          Class method to get the commandWaitTime value.
static int getConnectionTries()
          Class method to get the connectionTries value.
static int getConnectionWaitTime()
          Class method to get the connectionWaitTime value.
 Tuple getFactoryStack()
          Return a scan of all the factory names for this tuple space and their level numbers --- level 0 is the highest --- most recently added --- factory.
 Tuple getHandlerCommandNames(java.lang.String factoryName_)
          Return a scan of all the handler names for this factory --- this feature is *NOT* supported for the built in commands --- TSFSmallTS handlers.
 java.lang.String getName()
          Return the space name.
protected static java.lang.String getPassword()
          get the password
 int getPort()
          Return the number of the port.
 java.lang.String getServer()
          Return the name of the server.
protected static java.lang.String getUserName()
          gets the user name
static java.lang.String getVersion()
          Class Method to Return the TSpaces Code Version number.
 Tuple in(Tuple template)
          Deprecated. Use waitToTake() instead.
 Tuple indexCreate(java.lang.String name, java.lang.Class classtype, ConfigTuple config, boolean rebuild)
          Create an index and specify Index Configuration.
 void indexDestroy(java.lang.String name)
          Destroy an index.
 Tuple indexStatus(java.lang.String name)
          Get back the status of a Field index.
 SuperTuple inp(SuperTuple template)
          Deprecated. Use take() instead.
static boolean isValidTSName(java.lang.String s)
           
static void main(java.lang.String[] argv)
          Test routine.
 byte[] makeJarFile(java.lang.Class[] classes_)
          For all the classes, if the class is in a jar file, grab the entire jar file otherwise for plain .class classes ship them in their own .jar file.
 TupleID[] multiUpdate(Tuple tuple)
          Each field of the tuple should be a SuperTuple and is to be written to the space.
 TupleID[] multiWrite(Tuple tuple)
          Each field of the tuple should be a SuperTuple and is to be written to the space.
 void out(Tuple tuple)
          Deprecated. Use write() instead
static java.lang.Object parseConfigTuple(java.lang.String fieldName_, SuperTuple configTuple_)
           
 Tuple read(java.io.Serializable obj)
          Retrieve a Tuple from the space that matches the Tuple template.
 Tuple read(java.io.Serializable obj1, java.io.Serializable obj2)
          Retrieve a Tuple from the space that matches the Tuple template.
 Tuple read(java.io.Serializable obj1, java.io.Serializable obj2, java.io.Serializable obj3)
          Retrieve a Tuple from the space that matches the Tuple template.
 SubclassableTuple read(SubclassableTuple template)
          Retrieve a Tuple from the space that matches the Tuple template.
 SuperTuple read(SuperTuple template)
          Retrieve a Tuple from the space that matches the Tuple template.
 Tuple read(Tuple template)
          Retrieve a Tuple from the space that matches the Tuple template.
 SuperTuple readTupleById(TupleID id_)
          read a specific tuple from the space.
 Tuple rhonda(Tuple tuple)
          The rendevous primitive.
 Tuple scan(java.io.Serializable obj)
          Retrieve all Tuples from the space that match a Tuple template.
 Tuple scan(java.io.Serializable obj1, java.io.Serializable obj2)
          Retrieve all Tuples from the space that match a Tuple template.
 Tuple scan(java.io.Serializable obj1, java.io.Serializable obj2, java.io.Serializable obj3)
          Retrieve all Tuples from the space that match a Tuple template.
 Tuple scan(SuperTuple template)
          Retrieve all Tuples from the space that match a Tuple template.
static void setCallbackThreads(boolean callbackThreads_)
          Class method to set the default for specification of whether a new Thread will be used for Event Register callbacks.
static void setClosingDownByForcingFinalizers(boolean val_)
          Deprecated. No longer does anything - Use appletEnvoronment(true)
static void setCommandWaitTime(int commandWaitTime_)
          Class method to set the WaitTime for a command response to a new value.
static void setConnectionTries(int connectionTries_)
          Class method to set the connectionTries to a new value.
static void setConnectionWaitTime(int connectionWaitTime_)
          Class method to set the connectionWaitTime to a new value.
static void setDebug(boolean status)
          This static class method will cause debugging information to be displayed on on STDOUT.
static void setPassword(java.lang.String pass_)
          Set default password to be used for access control for all spaces See comments on setUserName()
static void setTSCmdImpl(java.lang.String className_)
          Set default the class name for the TSCmdImpl that will be used for this Virtual Machine.
static void setUserName(java.lang.String name_)
          Set default username to be used for access control for all spaces in this virtual mmachine It will be used in the TupleSpace Constructor if not specified as a parameter and it will also be used for static commands issued prior to the constructor which setup a server connection (i.e.
 void setUserName(java.lang.String name_, java.lang.String password_)
          Deprecated. There are new static setUser and setPassword methods
static Tuple shutdown(java.lang.String tsServer_, int tsPort_, java.lang.String user_, java.lang.String password_)
           
static Tuple status(java.lang.String tsServer_)
           
static Tuple status(java.lang.String tsServer_, int tsPort_)
           
 Tuple take(java.io.Serializable obj1)
          Retrieve a Tuple from the space that has one Field matching the Serializables.
 Tuple take(java.io.Serializable obj1, java.io.Serializable obj2)
          Retrieve a tuple from the space that has two Fields matching specified Serializables.
 Tuple take(java.io.Serializable obj1, java.io.Serializable obj2, java.io.Serializable obj3)
          Retrieve a tuple from the space that has three Fields matching specified Serializables.
 SubclassableTuple take(SubclassableTuple template)
          Retrieve a tuple from the space that matches a Tuple template.
 SuperTuple take(SuperTuple template)
          Retrieve a tuple from the space that matches a Tuple template.
 Tuple take(Tuple template)
          Retrieve a tuple from the space that matches a Tuple template.
 SuperTuple takeTupleById(TupleID id_)
          take a specific tuple from the space.
 TupleID update(SuperTuple replacer)
          Update the tuple in the space that matches the supplied Tuple It is assumed that the Tuple supplied has been retrieved from the space and contains a valid TupleID.
 TupleID update(SuperTuple template, SuperTuple replacer)
          Update the tuple in the space that matches the supplied tuple by replacing it with the replacer tuple.
 TupleID update(TupleID uniqueId, SuperTuple replacer)
          Update the tuple in the space that matches the supplied uniqueId by replacing it with the replacer tuple.
 Tuple waitToRead(java.io.Serializable obj)
          Retrieve a Tuple from the space that matches the Tuple template.
 Tuple waitToRead(java.io.Serializable obj1, java.io.Serializable obj2)
          Retrieve a Tuple from the space that matches the Tuple template.
 Tuple waitToRead(java.io.Serializable obj1, java.io.Serializable obj2, java.io.Serializable obj3)
          Retrieve a Tuple from the space that matches the Tuple template.
 SubclassableTuple waitToRead(SubclassableTuple template)
          Retrieve a Tuple from the space that matches the Tuple template.
 SubclassableTuple waitToRead(SubclassableTuple template, long timeout)
          Retrieve a Tuple from the space that matches the Tuple template.
 SuperTuple waitToRead(SuperTuple template)
          Retrieve a Tuple from the space that matches the Tuple template.
 SuperTuple waitToRead(SuperTuple template, long timeout)
          Retrieve a Tuple from the space that matches the Tuple template.
 Tuple waitToRead(Tuple template)
          Retrieve a Tuple from the space that matches the Tuple template.
 Tuple waitToRead(Tuple template, long timeout)
          Retrieve a Tuple from the space that matches the Tuple template.
 Tuple waitToTake(java.io.Serializable obj1)
          Retrieve a tuple from the space that has one Field matching the Serializables.
 Tuple waitToTake(java.io.Serializable obj1, java.io.Serializable obj2)
          Retrieve a tuple from the space that has two Fields matching specified Serializables.
 Tuple waitToTake(java.io.Serializable obj1, java.io.Serializable obj2, java.io.Serializable obj3)
          Retrieve a tuple from the space that has three Fields matching specified Serializables.
 SubclassableTuple waitToTake(SubclassableTuple template)
          Retrieve a tuple from the space that matches a Tuple template.
 SubclassableTuple waitToTake(SubclassableTuple template, long timeout)
          Retrieve a Tuple from the space that matches the Tuple template.
 SuperTuple waitToTake(SuperTuple template)
          Retrieve a tuple from the space that matches a Tuple template.
 SuperTuple waitToTake(SuperTuple template, long timeout)
          Retrieve a Tuple from the space that matches the Tuple template.
 Tuple waitToTake(Tuple template)
          Retrieve a tuple from the space that matches a Tuple template.
 Tuple waitToTake(Tuple template, long timeout)
          Retrieve a Tuple from the space that matches the Tuple template.
 TupleID write(java.io.Serializable obj)
          Add a Tuple to the Tuple Space that has a single field equal to the Object.
 TupleID write(java.io.Serializable obj1, java.io.Serializable obj2)
          Add a Tuple to the Tuple Space that has two fields equal to the Objects passed in.
 TupleID write(java.io.Serializable obj1, java.io.Serializable obj2, java.io.Serializable obj3)
          Add a Tuple to the Tuple Space that has two fields equal to the Serializables passed in.
 TupleID write(SuperTuple tuple)
          Add the Tuple to the Tuple Space.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

_VERSION

public static final java.lang.String _VERSION
Code Version.Level.Modification Change this when a new level of code is to be released

_DEFAULT_PERSISTENCE

public static final boolean _DEFAULT_PERSISTENCE
Whether a tuple space is persistent by default and its index -1 indicates no index and what type

_DEFAULT_INDEX_FIELD

public static final int _DEFAULT_INDEX_FIELD

_DEFAULT_DBTYPE

public static final java.lang.String _DEFAULT_DBTYPE

_DBTYPE_MMDB

public static final java.lang.String _DBTYPE_MMDB

_DBTYPE_SMALLDB

public static final java.lang.String _DBTYPE_SMALLDB

DEFAULTNAME

public static final java.lang.String DEFAULTNAME
The default name of a TupleSpace if one isn't specified.

DEFAULTPORT

public static final int DEFAULTPORT
The default port number used to connect to the TupleSpace server if a port number isn't specified (the usual case).

DEFAULTHOST

public static final java.lang.String DEFAULTHOST
The default name of the machine running the TupleSpace server.

EXCEPTION

public static final java.lang.String EXCEPTION
The string used between the server and tspace library to signal a problem. Not normally referenced by a user.

OK

public static final java.lang.String OK
The string used between the server to signal good the operation completely normally. Not normally referenced by a user.

PERSISTENCE

public static final java.lang.String PERSISTENCE
configuration field names. Persitence can be true or false IndexField is for TSSmallDB, -1 indicates no index and is the default. TSDbType can be TSSmallDB.SMALL_DB or TSMMDB.MM_DB.

INDEXFIELD

public static final java.lang.String INDEXFIELD

TSDBTYPE

public static final java.lang.String TSDBTYPE

_GALAXY_TSNAME

public static final java.lang.String _GALAXY_TSNAME
the galaxy tuple space name. This used to be in TSServer, but it is here now as the client may want to make operations on the galaxy ts so need to know it here, but don't want to have any dependence on the Server code from the client. Maybe later can make some common file Also, don't want users to use this. Only the system should be using it!!!!

_ADMIN_TSNAME

public static final java.lang.String _ADMIN_TSNAME
the name of the admin tuple space. Here for the same reasons as the Galaxy name. users please don't use it.

WRITE

public static final java.lang.String WRITE

TAKE

public static final java.lang.String TAKE

READ

public static final java.lang.String READ

WAITTOTAKE

public static final java.lang.String WAITTOTAKE

WAITTOREAD

public static final java.lang.String WAITTOREAD

UPDATE

public static final java.lang.String UPDATE

DELETETUPLEBYID

public static final java.lang.String DELETETUPLEBYID

READTUPLEBYID

public static final java.lang.String READTUPLEBYID

TAKETUPLEBYID

public static final java.lang.String TAKETUPLEBYID

MULTIWRITE

public static final java.lang.String MULTIWRITE

MULTIUPDATE

public static final java.lang.String MULTIUPDATE

SCAN

public static final java.lang.String SCAN

CONSUMINGSCAN

public static final java.lang.String CONSUMINGSCAN

SCANALL

public static final java.lang.String SCANALL

COUNT

public static final java.lang.String COUNT

DELETE

public static final java.lang.String DELETE

DELETEALL

public static final java.lang.String DELETEALL

TSEXISTS

public static final java.lang.String TSEXISTS

EVENT_REGISTER

public static final java.lang.String EVENT_REGISTER

EVENT_DEREGISTER

public static final java.lang.String EVENT_DEREGISTER

STATUS

public static final java.lang.String STATUS

ADDFACTORY

public static final java.lang.String ADDFACTORY

ADDHANDLER

public static final java.lang.String ADDHANDLER

TSCREATE

public static final java.lang.String TSCREATE

TSACCESS

public static final java.lang.String TSACCESS

TSDESTROY

public static final java.lang.String TSDESTROY

BEGINTRANS

public static final java.lang.String BEGINTRANS

ABORTTRANS

public static final java.lang.String ABORTTRANS

COMMITTRANS

public static final java.lang.String COMMITTRANS

SHUTDOWN

public static final java.lang.String SHUTDOWN

PURGEWAIT

public static final java.lang.String PURGEWAIT

INDEXCREATE

public static final java.lang.String INDEXCREATE

INDEXDESTROY

public static final java.lang.String INDEXDESTROY

INDEXSTATUS

public static final java.lang.String INDEXSTATUS

CHECKPOINT

public static final java.lang.String CHECKPOINT

CLOSE

public static final java.lang.String CLOSE

ABORT

public static final java.lang.String ABORT
The string used to signal an abort operation. For now only the server should be doing an abort as each operation is a transaction, but the server will not stop the client from using abort to reinsert a TAKE or WAITTOTAKE tuple back into tuple space.

RHONDA

public static final java.lang.String RHONDA

SEQ_NUM

public static final int SEQ_NUM
The top level tuple sent to the server has four fields ( Seq #, CmdTuple, clientID, Flag)

CMD_TUP

public static final int CMD_TUP

CLI_ID

public static final int CLI_ID

CMD_FLAG

public static final int CMD_FLAG

EVENT_COMMAND_FLD

public static final int EVENT_COMMAND_FLD
the fields of an event tuple, keep with the making of the event templates until things stabilize pw. The 0th field is TupleSpace.ANEVENT

EVENT_TUPLE_FLD

public static final int EVENT_TUPLE_FLD

EVENT_SEQ_FLD

public static final int EVENT_SEQ_FLD

EVENT_ACTION_FLD

public static final int EVENT_ACTION_FLD

EVENT_EAT_FLD

public static final int EVENT_EAT_FLD

_DEFAULT_USER

public static final java.lang.String _DEFAULT_USER
This is what is used if no user/password is specified

_DEFAULT_PASSWORD

public static final java.lang.String _DEFAULT_PASSWORD

TS_NAME

public static final int TS_NAME

TS_CMD

public static final int TS_CMD

TS_ARG

public static final int TS_ARG

TS_STATUS_CODE

public static final int TS_STATUS_CODE

TS_RETURN_VALUE

public static final int TS_RETURN_VALUE

DEFAULTCONNECTTRIES

protected static final int DEFAULTCONNECTTRIES
the number of times to try to connect to the server before raising an exception to the caller. Would probably be nice in the future if this was an instance variable rather than static.

_TOP_GROUP

public static final java.lang.String _TOP_GROUP
the default top group that everyone is a part of. Useful for basic ops which everyone should be able to do, like reading access permissions.

_defaultUserName

protected static java.lang.String _defaultUserName
The Userid used for TupleSpace operations. Changed by the setUserName() method. Can be overriden in the TupleSpace constructor.

_defaultPassword

protected static java.lang.String _defaultPassword
The password for this space.

_STAND_ALONE_CMD

public static int _STAND_ALONE_CMD
Indicates that the command being sent is not part of any bigger transaction At the server side, the command will be preceded by a beginTrans and succeeded by a commitTrans

_FIRST_CMD

public static int _FIRST_CMD
Indicates that the command being sent is the first one in a long transaction At the server side, the command will be preceded by a beginTrans

_NORMAL_CMD

public static int _NORMAL_CMD
Indicates that the command being sent is part of a larger transaction. BeginTrans for that transaction has been already executed as a result of some earlier command of this transaction

TSCMD_LOCAL_IMPL

public static final java.lang.String TSCMD_LOCAL_IMPL

TSCMD_SOCKET_IMPL

public static final java.lang.String TSCMD_SOCKET_IMPL

_isPersistent

protected boolean _isPersistent
is this tuple space persistent?

_tsName

protected java.lang.String _tsName
The name of the tuple space.

_tsServer

protected java.lang.String _tsServer
The name of the machine running the TupleSpace server

_tsPort

protected int _tsPort
The port for this space's server.

_userName

protected java.lang.String _userName
The username for this space.

_password

protected java.lang.String _password
The password for this space.

_userNameAlreadyUsed

protected boolean _userNameAlreadyUsed
A flag to make sure we don't change the username after the connection has been verified.

_currTransactions

protected java.util.Vector _currTransactions
A list of the currently active transactions. If there are nested transactions, this will not work
Constructor Detail

TupleSpace

public TupleSpace(java.lang.String name_,
                  java.lang.String tsServer_,
                  int tsPort_,
                  SuperTuple configuration_,
                  SuperTuple accessPermissions_,
                  java.lang.String userName_,
                  java.lang.String password_)
           throws TupleSpaceException
Actual constructor used to create or access a named Tuple Space.

If it is a new space, then the space will be created on the specified server with the specified name. The specified configuration and access permissions will be assigned to the new space. The User and password will be used to authorized the abilty to create new spaces.

If a space with the specified name (at the host:port) already exists, then the configuration and access tuples will be ignored and the User and password will be used to determine the access permissions for the space.

Parameters:
name_ - A string that identifies the TupleSpace on the specified TupleSpaceServer.
tsServer_ - A string that identifies the TupleSpaceServer that manages the TupleSpace. May be of form host:port
tsPort_ - The specific port that the TupleSpaceServer uses to listen for connections from TupleSpace clients. This parameter will be ignored if the port is specified as part of the tsServer_ parameter.
configuration_ - the configuration tuple for this space
accessPermissions_ - the permissions Tuple for this space
userName_ - the user's tspaces name
password_ - the user's tspaces password A configuration tuple looks like:
 Tuple(new Field(TupleSpace.PERSISTENCE, new Boolean( true)), 
       new Field(TupleSpace.INDEXFIELD, new Integer(-1)),
       new Field(TupleSpace.TSDBTYPE, new String(DBTYPE_SMALLDB or DBTYPE_MMDB)))
 Any of the fields can be left out and ordering doesn't matter. For fields that
 are left out, the defaults --- true, -1, DBTYPE_MMDB --- apply.
 The configuration tuple is only used when the space is initially created.
 

The accessPermision Tuple contains a single Field that contains an Acl object, as defined in java.security.acl. One can construct an Acl with code like the following.

   Permissions[] p1 = {P_READ,P_WRITE};
   Principal owner = ACLFactory.createPrincipal("Jim");
   Principal grp = ACLFactory.createPrincipal("Jim");
   Acl myacl = AclFactory("MyAcl",owner);
   myacl.addEntry(owner,AclFactory.createAclEntry(owner,p1);
   myacl.addEntry(owner,AclFactory.createAclEntry(grp,p1);
 
The accessPermision Tuple is only used when the space is initially created.

Throws:
TupleSpaceException - If there is a problem creating the space on the server or communicating with the server or there is a problem with the TupleSpaceName.
See Also:
Acl, AclFactory

TupleSpace

public TupleSpace()
           throws TupleSpaceException
Create a default tuple space. The server is assumed to be on the same host (localhost) and the name of the space is the deafult name ("DefaultTS"). Connections to the server will be made on the default port (8200).
Throws:
TupleSpaceException - If there is a problem creating the space on the server or communicating with the server or there is a problem with the TupleSpaceName.

TupleSpace

public TupleSpace(Tuple configuration_)
           throws TupleSpaceException
Create a default tuple space. The server is assumed to be on the same host (localhost) and the name of the space is the deafult name ("foo"). Connections to the server will be made on the default port (8200). create it with the specified configuration.
Parameters:
name_ - A string that identifies the TupleSpace.
tsServer_ - A string that identifies the TupleSpaceServer
tsPort_ - The specific port that will be used to contact the server
configuration_ - the configuration tuple for this space
accessPermissions_ - the permissions Tuple for this space
userName_ - the user's tspaces name
password_ - the user's tspaces password
Throws:
TupleSpaceException - if there is a problem setting up the configuration

The parameters are described in more detail above


TupleSpace

public TupleSpace(java.lang.String name_)
           throws TupleSpaceException
Create a named Tuple Space. The server is assumed to be on the same host (localhost). Connections to the server will be made on the default port (8200).
Parameters:
name_ - A string that identifies the TupleSpace.
Throws:
TupleSpaceException - if there is a problem setting up the configuration

The parameters are described in more detail above


TupleSpace

public TupleSpace(java.lang.String name_,
                  java.lang.String userName_,
                  java.lang.String password_)
           throws TupleSpaceException
Create or access a named Tuple Space with the specified user and password . The server is assumed to be on the same host (localhost). Connections to the server will be made on the default port (8200).
Parameters:
name_ - A string that identifies the TupleSpace.
userName_ - the user's tspaces name
password_ - the user's tspaces password
Throws:
TupleSpaceException - if there is a problem setting up the configuration

The parameters are described in more detail above


TupleSpace

public TupleSpace(java.lang.String name_,
                  SuperTuple configuration_)
           throws TupleSpaceException
Create a named Tuple Space with the specified configuration. The server is assumed to be on the same host (localhost). Connections to the server will be made on the default port (8200).
Parameters:
name_ - A string that identifies the TupleSpace.
configuration_ - the configuration tuple for this space
Throws:
TupleSpaceException - if there is a problem setting up the configuration

The parameters are described in more detail above


TupleSpace

public TupleSpace(java.lang.String name_,
                  SuperTuple configuration_,
                  java.lang.String userName_,
                  java.lang.String password_)
           throws TupleSpaceException
Create a named Tuple Space with the specified configuration, username and password. The server is assumed to be on the same host (localhost). Connections to the server will be made on the default port (8200).
Parameters:
name_ - A character string that identifies the TupleSpace on the default TupleSpaceServer.
configuration_ - the configuration tuple
userName_ - the name of the user for this space
password_ - the password of the user
Throws:
TupleSpaceException - If there is a problem creating the space on the server or communicating with the server or there is a problem with the TupleSpaceName. **

The parameters are described in more detail above


TupleSpace

public TupleSpace(java.lang.String name_,
                  java.lang.String tsServer_)
           throws TupleSpaceException
Create a named Tuple Space to be stored and managed by a specified Tuple Space Server. Connections to the server will be made on the default port (8200).
Parameters:
name_ - A string that identifies the TupleSpace.
tsServer_ - A string that identifies the TupleSpaceServer
Throws:
TupleSpaceException - if there is a problem setting up the configuration

The parameters are described in more detail above


TupleSpace

public TupleSpace(java.lang.String name_,
                  java.lang.String tsServer_,
                  java.lang.String userName_,
                  java.lang.String password_)
           throws TupleSpaceException
Create a named Tuple Space to be stored and managed by a specified Tuple Space Server. Specifies the username and password. Connections to the server will be made on the default port (8200).
Parameters:
name_ - A string that identifies the TupleSpace.
tsServer_ - A string that identifies the TupleSpaceServer
userName_ - the user's tspaces name
password_ - the user's tspaces password
Throws:
TupleSpaceException - if there is a problem setting up the configuration

The parameters are described in more detail above


TupleSpace

public TupleSpace(java.lang.String name_,
                  java.lang.String tsServer_,
                  SuperTuple configuration_)
           throws TupleSpaceException
Create a named Tuple Space with the specified configuration to be stored and managed by a specified Tuple Space Server. Connections to the server will be made on the default port (8200).
Parameters:
name_ - A string that identifies the TupleSpace.
tsServer_ - A string that identifies the TupleSpaceServer
configuration_ - the configuration tuple for this space
Throws:
TupleSpaceException - if there is a problem setting up the configuration

The parameters are described in more detail above


TupleSpace

public TupleSpace(java.lang.String name_,
                  java.lang.String tsServer_,
                  SuperTuple configuration_,
                  java.lang.String userName_,
                  java.lang.String password_)
           throws TupleSpaceException
Create a named Tuple Space to be stored and managed by a specified Tuple Space Server. Connections to the server will be made on the default port (8200).
Parameters:
name_ - A string that identifies the TupleSpace.
tsServer_ - A string that identifies the TupleSpaceServer
configuration_ - the configuration tuple for this space
userName_ - the user's tspaces name
password_ - the user's tspaces password
Throws:
TupleSpaceException - if there is a problem setting up the configuration

The parameters are described in more detail above


TupleSpace

public TupleSpace(java.lang.String name_,
                  java.lang.String tsServer_,
                  int tsPort_)
           throws TupleSpaceException
Create a named Tuple Space to be stored and managed by a specified Tuple Space Server. Connections to the server will be made on a specified port.
Parameters:
name_ - A string that identifies the TupleSpace.
tsServer_ - A string that identifies the TupleSpaceServer
tsPort_ - The specific port that will be used to contact the server
Throws:
TupleSpaceException - if there is a problem setting up the configuration

The parameters are described in more detail above


TupleSpace

public TupleSpace(java.lang.String name_,
                  java.lang.String tsServer_,
                  int tsPort_,
                  java.lang.String userName_,
                  java.lang.String password_)
           throws TupleSpaceException
Create a named Tuple Space to be stored and managed by a specified Tuple Space Server. Connections to the server will be made on a specified port.
Parameters:
name_ - A string that identifies the TupleSpace.
tsServer_ - A string that identifies the TupleSpaceServer
tsPort_ - The specific port that will be used to contact the server
userName_ - the user's tspaces name
password_ - the user's tspaces password
Throws:
TupleSpaceException - if there is a problem setting up the configuration

The parameters are described in more detail above


TupleSpace

public TupleSpace(java.lang.String name_,
                  java.lang.String tsServer_,
                  int tsPort_,
                  SuperTuple configuration_)
           throws TupleSpaceException
Create a named Tuple Space to be stored and managed by a specified Tuple Space Server. Connections to the server will be made on a specified port.
Parameters:
name_ - A string that identifies the TupleSpace.
tsServer_ - A string that identifies the TupleSpaceServer
tsPort_ - The specific port that will be used to contact the server
configuration_ - the configuration tuple for this space
Throws:
TupleSpaceException - if there is a problem setting up the configuration

The parameters are described in more detail above


TupleSpace

public TupleSpace(java.lang.String name_,
                  java.lang.String tsServer_,
                  int tsPort_,
                  SuperTuple configuration_,
                  java.lang.String userName_,
                  java.lang.String password_)
           throws TupleSpaceException
Create a named Tuple Space to be stored and managed by a specified Tuple Space Server. Connections to the server will be made on a specified port.
Parameters:
name_ - A string that identifies the TupleSpace.
tsServer_ - A string that identifies the TupleSpaceServer
tsPort_ - The specific port that will be used to contact the server
configuration_ - the configuration tuple for this space
userName_ - the user's tspaces name
password_ - the user's tspaces password
Throws:
TupleSpaceException - if there is a problem setting up the configuration

The parameters are described in more detail above


TupleSpace

public TupleSpace(java.lang.String name_,
                  java.lang.String tsServer_,
                  int tsPort_,
                  SuperTuple configuration_,
                  Tuple accessPermissions_)
           throws TupleSpaceException
Create a named Tuple Space to be stored and managed by a specified Tuple Space Server.
Parameters:
name_ - A string that identifies the TupleSpace.
tsServer_ - A string that identifies the TupleSpaceServer
tsPort_ - The specific port that will be used to contact the server
configuration_ - the configuration tuple for this space
accessPermissions_ - the permissions Tuple for this space
Throws:
TupleSpaceException - if there is a problem setting up the configuration

The parameters are described in more detail above

Method Detail

setTSCmdImpl

public static void setTSCmdImpl(java.lang.String className_)
Set default the class name for the TSCmdImpl that will be used for this Virtual Machine.

Note that this impl will then be used in any subsequent TupleSpace constructors. It can be changed in midstream without messing up any previously allocated Spaces. However, be careful about static commands that dynamically obtain a TSCmd implementation (exists(), status())

Parameters:
className_ - The class name for the TSCmd implementation

setUserName

public static void setUserName(java.lang.String name_)
Set default username to be used for access control for all spaces in this virtual mmachine It will be used in the TupleSpace Constructor if not specified as a parameter and it will also be used for static commands issued prior to the constructor which setup a server connection (i.e. exists() The userid and password are checked when the server connection is setup so it is important to call the setUserName(user) and setPassword(pass) methods prior to calling the exists, status() or the TupleSpace constructor.
Parameters:
name_ - The new username

setPassword

public static void setPassword(java.lang.String pass_)
Set default password to be used for access control for all spaces See comments on setUserName()
Parameters:
name_ - The new password

getUserName

protected static java.lang.String getUserName()
gets the user name
Returns:
the user name

getPassword

protected static java.lang.String getPassword()
get the password
Returns:
a string of the password

setUserName

public void setUserName(java.lang.String name_,
                        java.lang.String password_)
                 throws TupleSpaceException
Deprecated. There are new static setUser and setPassword methods

Set username and password to be used for access control on this tuplespace
Parameters:
name_ - The new username
password_ - The new password

isValidTSName

public static final boolean isValidTSName(java.lang.String s)
Returns:
true if this string contains only alpha-numeric characters or '_'

setClosingDownByForcingFinalizers

public static void setClosingDownByForcingFinalizers(boolean val_)
Deprecated. No longer does anything - Use appletEnvoronment(true)

Static class method that will determine if the TupleSpace force finalizers to be run on exit? this method has some security checking on it, so when running as an applet, this should be set to false. When it is set to false though, the tuple space system will need to have the TupleSpace.cleanup method called so that it can close its connections to the servers normally. Note that the cleanup method is static so just call it once and all space connections will be cleaned up.
Parameters:
val_ - if true then force them on shutdown, if false do not

appletEnvironment

public static void appletEnvironment(boolean setting)
Class method to set the connection environemt so that it it will follow the Applet sandbox rules. This is added initially as a way to test what is needed to make TSpaces work better in an applet environment. Longterm, we may want to have better approach. So if you have a better idea you can remove this method and any associated logic that uses the appletEnvironment boolean.
Parameters:
setting - true if we want to run in an Applet environment

connectionTries

public static void connectionTries(int connectionTries_)
Deprecated. Use setConnectionTries

Class method to set the connectionTries to a new value. 0 signifies infinity --- try again and again.
Parameters:
connectionTries_ - the number of times to try connecting to the server before failing

setConnectionTries

public static void setConnectionTries(int connectionTries_)
Class method to set the connectionTries to a new value. 0 signifies infinity --- try again and again.
Parameters:
connectionTries_ - the number of times to try connecting to the server before failing

getConnectionTries

public static int getConnectionTries()
Class method to get the connectionTries value. 0 signifies infinity --- try again and again.
Returns:
the number of times to try connecting to the server before failing

connectionWaitTime

public static void connectionWaitTime(int connectionWaitTime_)
Deprecated. Use setConnectionTries

Static class method to set the connectionWaitTime to a new value.
Parameters:
connectionWaitTime_ - the wait time in seconds between times to try and talk to the server

setConnectionWaitTime

public static void setConnectionWaitTime(int connectionWaitTime_)
Class method to set the connectionWaitTime to a new value. 0 signifies no wait - wait forever.
Parameters:
connectionWaitTime_ - the time in seconds to wait for a connection

getConnectionWaitTime

public static int getConnectionWaitTime()
Class method to get the connectionWaitTime value. 0 signifies infinity --- try again and again.
Returns:
the time (in seconds) to wait for a connection to the server before failing.

setCommandWaitTime

public static void setCommandWaitTime(int commandWaitTime_)
Class method to set the WaitTime for a command response to a new value. Default of 0 signifies that there is no timeout, it will wait forever. This should be used to timeout from stalls due to network timeouts. It is not intended to replace the timeouts parameters for blocking read or take operations.
Parameters:
commandWaitTime_ - the time (ms) to wait for a command response

getCommandWaitTime

public static int getCommandWaitTime()
Class method to get the commandWaitTime value.
Returns:
the time (in ms) to wait for a network response to any network operation.

setCallbackThreads

public static void setCallbackThreads(boolean callbackThreads_)
Class method to set the default for specification of whether a new Thread will be used for Event Register callbacks. "true" indicates that a new Thread will be created for all EventRegister callbacks.

Note: The default setting of false will mean that there is only a single thread that all TupleSpace events and therefore it is important to not do anything in a callback that will block all future TupleSpace calls. This means that you must not issue new TupleSpace operations

Setting it to true on the otherhand, creates a new Thread for every callback, which is expensive. It can also introduce new Thread sysnronization problems that you must be careful to handle.

Parameters:
callbackThreads_ - boolean value to control whether new threads are started for EventRegister callbacks.

update

public TupleID update(SuperTuple replacer)
               throws TupleSpaceException
Update the tuple in the space that matches the supplied Tuple It is assumed that the Tuple supplied has been retrieved from the space and contains a valid TupleID. It will return the TupleID of the new replacement tuple which should be the same value. It will generate a dummy Tuple with the TupleID set to the specified value and then calls the default update(method) Note that this command is non-blocking. (( If no match for the TupleID of the supplied Tuple is found, an exception is thrown and the replacer is not written to the space.
Parameters:
replacer - the tuple to be updated
Returns:
The TupleID of the replacement tuple or null if no match occurred and therefore the update was not done.
Throws:
TupleSpaceCommunicationException - There are problems connecting to the TupleSpace Server
TupleSpaceServerException - There was a problem executing the command on the server.
TupleSpaceClientException - There were problems preparing the command to be sent to the server.

update

public TupleID update(TupleID uniqueId,
                      SuperTuple replacer)
               throws TupleSpaceException
Update the tuple in the space that matches the supplied uniqueId by replacing it with the replacer tuple. It will return the TupleID of the new replacement tuple. It will generate a dummy Tuple with the TupleID set to the specified value and then calls the default update(method) Note that this command is non-blocking. If no match for the TupleID is found, an exception is thrown and the replacer is not written to the space.
Parameters:
uniqueID - The TupleID of the tuple to be replaced
replacer - the replacement tuple
Returns:
The TupleID of the replacement tuple or null if no match occurred and therefore the update was not done.
Throws:
TupleSpaceCommunicationException - There are problems connecting to the TupleSpace Server
TupleSpaceServerException - There was a problem executing the command on the server.
TupleSpaceClientException - There were problems preparing the command to be sent to the server.

update

public TupleID update(SuperTuple template,
                      SuperTuple replacer)
               throws TupleSpaceException
Update the tuple in the space that matches the supplied tuple by replacing it with the replacer tuple. The supplied Tuple can either be a template that will be used to get the first matching tuple or it can be an actual tuple that was retrieved from the space, in which case the TupleID will be used to select the tuple to be replaced.

Note that this command is non-blocking. If no match for the template is found, an exception is thrown and the replacer is not written to the space. Note that the template and replacer need not have the same signature.

Parameters:
template - a template or actual tuple to be removed
replacer - the replacement tuple
Returns:
TupleID of the replacement Tuple.
Throws:
TupleSpaceCommunicationException - There are problems connecting to the TupleSpace Server
TupleSpaceServerException - There was a problem executing the command on the server.
TupleSpaceClientException - There were problems preparing the command to be sent to the server.

multiWrite

public TupleID[] multiWrite(Tuple tuple)
                     throws TupleSpaceException
Each field of the tuple should be a SuperTuple and is to be written to the space. There may be 0 or more SuperTuples. Since this is done as a single transaction, either all of the writes at the server occur or none of them do.
Parameters:
tuple - a tuple of tuples each of which is to be written to the space.
Returns:
An array contains the TupleID s for the tuples that were written.
Throws:
TupleSpaceException - There were problems preparing the command to be sent to the server.

multiUpdate

public TupleID[] multiUpdate(Tuple tuple)
                      throws TupleSpaceException
Each field of the tuple should be a SuperTuple and is to be written to the space. There may be 0 or more SuperTuples. Since this is done as a single transaction, either all of the updates at the server occur or none of them do.
Parameters:
tuple - a tuple of tuples each of which is to be written to the space.
Returns:
An array contains the TupleID s for the tuples that were written.
Throws:
TupleSpaceException - There were problems preparing the command to be sent to the server.

deleteTupleById

public void deleteTupleById(TupleID id_)
                     throws TupleSpaceException
delete a specific tuple from the space. It is expected that the tuple exists; if not, an exception is thrown. A tuple's id can be obtained by calling SuperTuple.getTupleID() Ids are unique on each tuple space even across server failures. Currently they are never reassigned. Typically the id will be gotten from a tuple that was read and is now to be deleted. The TupleID is also returned from the write and multiWrite operations. For events, the event gives back the entire tuple so the id can be obtained using getTupleID
 Example:
   TupleID id = _tuple.getTupleID();  
   ts.deleteTupleById(id);  
 
Also see the readTupleById() method.
Parameters:
id_ - the identifier of the tuple to be deleted
Throws:
TupleSpaceCommunicationException - There are problems connecting to the TupleSpace Server
TupleSpaceServerException - There was a problem executing the command on the server.
TupleSpaceClientException - There were problems preparing the command to be sent to the server.

readTupleById

public SuperTuple readTupleById(TupleID id_)
                         throws TupleSpaceException
read a specific tuple from the space. It is expected that the tuple exists; if not, an exception is thrown. A tuple's id can be obtained from the return value from a write() or by calling SuperTuple.getTupleID() on an existing Tuple. This command is provided to assist applications that want to use TupleID values to navigate thru the space.
 Example:
   TupleID id = ts.write(tuple);  
   ts.readTupleById(id);  

 What is passed to the server is a null Tuple that contains only the 
 the TupleID to be returned. Here is the code from readTupleById()
 
  readTupleById(TupleID id_) {
    Tuple tuple = new Tuple();
    tuple.setTupleID(id_);
    return command(READTUPLEBYID, tuple);

 
Parameters:
id_ - the identifier of the tuple to be deleted
Returns:
The specified Tuple
Throws:
TupleSpaceException - There are problems invoking the command

takeTupleById

public SuperTuple takeTupleById(TupleID id_)
                         throws TupleSpaceException
take a specific tuple from the space. It is expected that the tuple exists; if not, an exception is thrown. A tuple's id can be obtained from the return value from a write() or by calling SuperTuple.getTupleID() on an existing Tuple. This command is provided to assist applications that want to use TupleID values to navigate thru the space or have received the Tuple in a callback and they want to establish ownership of the Tuple so that no one else can read, delete or take the Tuple.
 Example:
   eventRegister(TupleSpace.WRITE, template, this, true) ;
   ...
   call(String type,String ts,int seq,SuperTuple tuple,boolean ex) {
     ...
     SuperTuple t;  
     try {
       TupleID id = tuple.getTupleID()
       t = ts.takeTupleById(id);
     } catch (TupleSpaceExeption tse) {
     }  
     if ( t != null) {
       //proceed to use tuple t.  
       // Note: it may have been updated

 
Parameters:
id_ - the identifier of the tuple to be deleted
Returns:
The specified Tuple
Throws:
TupleSpaceException - There are problems invoking the command

write

public TupleID write(SuperTuple tuple)
              throws TupleSpaceException
Add the Tuple to the Tuple Space. The Tuple must have at least one Field.
Parameters:
tuple - The Tuple to be added to the space.
Returns:
TupleID for the tuple that was written.
Throws:
TupleSpaceException - If a formal (template) tuple is passed, or the Tuple has no Fields.

write

public TupleID write(java.io.Serializable obj)
              throws TupleSpaceException
Add a Tuple to the Tuple Space that has a single field equal to the Object.
Parameters:
obj - The Serializable for the Field.
Returns:
TupleID for the tuple that was written.
Throws:
TupleSpaceException - There are problems invoking the command

write

public TupleID write(java.io.Serializable obj1,
                     java.io.Serializable obj2)
              throws TupleSpaceException
Add a Tuple to the Tuple Space that has two fields equal to the Objects passed in.
Parameters:
obj1 - The Serializable for the first Field.
obj2 - The Serializable for the second Field.
Returns:
TupleID for the tuple that was written.
Throws:
TupleSpaceException - There are problems invoking the command

write

public TupleID write(java.io.Serializable obj1,
                     java.io.Serializable obj2,
                     java.io.Serializable obj3)
              throws TupleSpaceException
Add a Tuple to the Tuple Space that has two fields equal to the Serializables passed in.
Parameters:
obj1 - The Serializable for the first Field.
obj2 - The Serializable for the second Field.
obj3 - The Serializable for the third Field.
Returns:
TupleID for the tuple that was written.
Throws:
TupleSpaceException - There are problems invoking the command

waitToTake

public SuperTuple waitToTake(SuperTuple template)
                      throws TupleSpaceException
Retrieve a tuple from the space that matches a Tuple template. Block until a match is found. Remove the Tuple from the space. This version of this method name is the most general one -- ie it is for SuperTuples -- you supply a SuperTuple and get a SuperTuple back. You probably have to cast the result to a Tuple or SubclassableTuple depending on which template was used.
Parameters:
template - A template SuperTuple that is used to match a tuple in the space.
Returns:
The SuperTuple that matches the template SuperTuple.
Throws:
TupleSpaceException - There are problems invoking the command

waitToTake

public SuperTuple waitToTake(SuperTuple template,
                             long timeout)
                      throws TupleSpaceException
Retrieve a Tuple from the space that matches the Tuple template. Block until matching Tuple is available or timeout interval is exceeded. If Tuple was found then remove the Tuple from the space.

See the waitToTake(SuperTuple template) for additional comments.

Parameters:
template - A template SuperTuple (one with at least one formal field) that is used to match a tuple in the space.
timeout - (ms) Time interval that the command will wait before aborting the request and returning null.
Returns:
The SuperTuple that matches the template SuperTuple. If a timeout occurs, null will be returned.
Throws:
TupleSpaceException - There are problems invoking the command

waitToTake

public Tuple waitToTake(Tuple template)
                 throws TupleSpaceException
Retrieve a tuple from the space that matches a Tuple template. Block until a match is found. Remove the Tuple from the space. This version of this method name is for Tuples only -- you supply a Tuple and get one back.
Parameters:
template - A template Tuple (one with at least one formal field) that is used to match a tuple in the space.
Returns:
The Tuple that matches the template Tuple.
Throws:
TupleSpaceException - There are problems invoking the command

waitToTake

public Tuple waitToTake(Tuple template,
                        long timeout)
                 throws TupleSpaceException
Retrieve a Tuple from the space that matches the Tuple template. Block until matching Tuple is available or timeout interval is exceeded. If Tuple was found then remove the Tuple from the space.

See the waitToTake(Tuple template) for additional comments.

Parameters:
template - A template SuperTuple (one with at least one formal field) that is used to match a tuple in the space.
timeout - (ms) Time interval that the command will wait before aborting the request and returning null.
Returns:
The SuperTuple that matches the template SuperTuple. If a timeout occurs, null will be returned.
Throws:
TupleSpaceException - There are problems invoking the command

waitToTake

public SubclassableTuple waitToTake(SubclassableTuple template)
                             throws TupleSpaceException
Retrieve a tuple from the space that matches a Tuple template. Block until a match is found. Remove the Tuple from the space. This version of this method name is for SubclassableTuples --- you supply a subclassable tuple and get the same back.
Parameters:
template - A template SubclassableTuple (one with at least one formal field) that is used to match a tuple in the space.
Returns:
The SubclassableTuple that matches the template SubclassableTuple.
Throws:
TupleSpaceException - There are problems invoking the command

waitToTake

public SubclassableTuple waitToTake(SubclassableTuple template,
                                    long timeout)
                             throws TupleSpaceException
Retrieve a Tuple from the space that matches the Tuple template. Block until matching Tuple is available or timeout interval is exceeded. If SubclassableTuple was found then remove the it from the space.

See the waitToTake(SubclassableTuple template) for additional comments.

Parameters:
template - A template SuperTuple (one with at least one formal field) that is used to match a tuple in the space.
timeout - (ms) Time interval that the command will wait before aborting the request and returning null.
Returns:
The SuperTuple that matches the template SuperTuple. If a timeout occurs, null will be returned.
Throws:
TupleSpaceException - There are problems invoking the command

waitToTake

public Tuple waitToTake(java.io.Serializable obj1)
                 throws TupleSpaceException
Retrieve a tuple from the space that has one Field matching the Serializables. Block until a match is found. Remove the Tuple from the space. The value and type of the Serializables (e.g., String) will be used to create the fields of the template tuple. If the Serializable is of type Field, then it will be used instead of being the value of the Field.
Parameters:
obj1 - An Serializable to match the first Field against.
Returns:
The Tuple that matches the template Tuple.
Throws:
TupleSpaceException - There are problems invoking the command

waitToTake

public Tuple waitToTake(java.io.Serializable obj1,
                        java.io.Serializable obj2)
                 throws TupleSpaceException
Retrieve a tuple from the space that has two Fields matching specified Serializables. Block until a match is found. Remove the Tuple from the space. The value and type of the Serializables (e.g., String) will be used to create the fields of the template tuple. If the Serializable is of type Field, then it will be used instead of being the value of the Field.
Parameters:
obj1 - An Serializable to match the first Field against.
obj2 - An Serializable to match the second Field against.
Returns:
The Tuple that matches the template Tuple.
Throws:
TupleSpaceException - There are problems invoking the command

waitToTake

public Tuple waitToTake(java.io.Serializable obj1,
                        java.io.Serializable obj2,
                        java.io.Serializable obj3)
                 throws TupleSpaceException
Retrieve a tuple from the space that has three Fields matching specified Serializables. Block until a match is found. Remove the Tuple from the space. The value and type of the Serializables (e.g., String) will be used to create the fields of the template tuple. If the Serializable is of type Field, then it will be used instead of being the value of the Field.
Parameters:
obj1 - An Serializable to match the first Field against.
obj2 - An Serializable to match the second Field against.
obj3 - An Serializable to match the second Field against.
Returns:
The Tuple that matches the template Tuple.
Throws:
TupleSpaceException - There are problems invoking the command

take

public SuperTuple take(SuperTuple template)
                throws TupleSpaceException
Retrieve a tuple from the space that matches a Tuple template. Do not block. Remove the Tuple from the space. For TAKE (aka CONSUME), we will require that tuples have content (no NULL tuples). After discussion with Dan and Toby, none of us can remember why we can't take an empty (wildcard) tuple, so I'm eliminating the restriction. (swm 9/22/97)
Parameters:
template - A template SuperTuple (one with at least one formal field) that is used to match a tuple in the space. This version of take has a SuperTuple template param and thus is the most general and returns a SuperTuple return tuple.
Returns:
The SuperTuple that matches the template SuperTuple. null if no match .
Throws:
TupleSpaceException - There are problems invoking the command

take

public Tuple take(Tuple template)
           throws TupleSpaceException
Retrieve a tuple from the space that matches a Tuple template. Do not block. Remove the Tuple from the space. For TAKE (aka CONSUME), we will require that tuples have content (no NULL tuples). After discussion with Dan and Toby, none of us can remember why we can't take an empty (wildcard) tuple, so I'm eliminating the restriction. (swm 9/22/97) This version of take has a Tuple param and thus returns a Tuple return value.
Parameters:
template - A template Tuple (one with at least one formal field) that is used to match a tuple in the space.
Returns:
The Tuple that matches the template Tuple. null if no match
Throws:
TupleSpaceException - There are problems invoking the command

take

public SubclassableTuple take(SubclassableTuple template)
                       throws TupleSpaceException
Retrieve a tuple from the space that matches a Tuple template. Do not block. Remove the Tuple from the space. For TAKE (aka CONSUME), we will require that tuples have content (no NULL tuples). After discussion with Dan and Toby, none of us can remember why we can't take an empty (wildcard) tuple, so I'm eliminating the restriction. (swm 9/22/97) This version of take has a SubclassableTuple template as a param and thus returns a SubclassableTuple.
Parameters:
template - A template SubclassableTuple (one with at least one formal field) that is used to match a tuple in the space.
Returns:
The SubclassableTuple that matches the template SubclassableTuple. null if no match
Throws:
TupleSpaceException - There are problems invoking the command

take

public Tuple take(java.io.Serializable obj1)
           throws TupleSpaceException
Retrieve a Tuple from the space that has one Field matching the Serializables. Do not block. Remove the Tuple from the space. The value and type of the Serializables (e.g., String) will be used to create the fields of the template tuple. If the Serializable is of type Field, then it will be used instead of being the value of the Field.
Parameters:
obj1 - An Serializable to match the first Field against.
Returns:
The Tuple that matches the template Tuple.
Throws:
TupleSpaceException - There are problems invoking the command

take

public Tuple take(java.io.Serializable obj1,
                  java.io.Serializable obj2)
           throws TupleSpaceException
Retrieve a tuple from the space that has two Fields matching specified Serializables. Do not block. Remove the Tuple from the space. The value and type of the Serializables (e.g., String) will be used to create the fields of the template tuple. If the Serializable is of type Field, then it will be used instead of being the value of the Field.
Parameters:
obj1 - An Serializable to match the first Field against.
obj2 - An Serializable to match the second Field against.
Returns:
The Tuple that matches the template Tuple.
Throws:
TupleSpaceException - There are problems invoking the command

take

public Tuple take(java.io.Serializable obj1,
                  java.io.Serializable obj2,
                  java.io.Serializable obj3)
           throws TupleSpaceException
Retrieve a tuple from the space that has three Fields matching specified Serializables. Do not block. Remove the Tuple from the space. The value and type of the Serializables (e.g., String) will be used to create the fields of the template tuple. If the Serializable is of type Field, then it will be used instead of being the value of the Field.
Parameters:
obj1 - An Serializable to match the first Field against.
obj2 - An Serializable to match the second Field against.
obj3 - An Serializable to match the second Field against.
Returns:
The Tuple that matches the template Tuple.
Throws:
TupleSpaceException - There are problems invoking the command

waitToRead

public SuperTuple waitToRead(SuperTuple template)
                      throws TupleSpaceException
Retrieve a Tuple from the space that matches the Tuple template. Block until matching Tuple is available. But do NOT remove it from the tuple space. For WAITTOREAD, NULL tuples are allowed, as they match anything. This is the general waitToRead method. A SuperTuple is supplied and a SuperTuple is returned. If the template is known to be of type Tuple or subclassableTuple, the more specific waitToReads could be used to avoid having to cast the result to one of those types.
Parameters:
template - A template SuperTuple (one with at least one formal field) that is used to match a tuple in the space.
Returns:
The SuperTuple that matches the template SuperTuple.
Throws:
TupleSpaceException - There are problems invoking the command

waitToRead

public SuperTuple waitToRead(SuperTuple template,
                             long timeout)
                      throws TupleSpaceException
Retrieve a Tuple from the space that matches the Tuple template. Block until matching Tuple is available or timeout interval is exceeded.

See the waitToRead(SuperTuple template) for additional comments.

Parameters:
template - A template SuperTuple (one with at least one formal field) that is used to match a tuple in the space.
timeout - (ms) Time interval that the command will wait before aborting the request and returning null.
Returns:
The SuperTuple that matches the template SuperTuple. If a timeout occurs, null will be returned.
Throws:
TupleSpaceException - There are problems invoking the command

waitToRead

public Tuple waitToRead(Tuple template)
                 throws TupleSpaceException
Retrieve a Tuple from the space that matches the Tuple template. Block until matching Tuple is available. But do NOT remove it from the tuple space. For WAITTOREAD, NULL tuples are allowed, as they match anything. This version of wait to read takes a Tuple param and returns a Tuple. Since a Tuple will only match against another Tuple this is the only possible return value.
Parameters:
template - A template Tuple (one with at least one formal field) that is used to match a tuple in the space.
Returns:
The Tuple that matches the template Tuple.
Throws:
TupleSpaceException - There are problems invoking the command

waitToRead

public Tuple waitToRead(Tuple template,
                        long timeout)
                 throws TupleSpaceException
Retrieve a Tuple from the space that matches the Tuple template. Block until matching Tuple is available or timeout interval is exceeded.

See the waitToRead(SuperTuple template) for additional comments.

Parameters:
template - A template SuperTuple (one with at least one formal field) that is used to match a tuple in the space.
timeout - (ms) Time interval that the command will wait before aborting the request and returning null.
Returns:
The SuperTuple that matches the template SuperTuple. If a timeout occurs, null will be returned.
Throws:
TupleSpaceException - There are problems invoking the command

waitToRead

public SubclassableTuple waitToRead(SubclassableTuple template)
                             throws TupleSpaceException
Retrieve a Tuple from the space that matches the Tuple template. Block until matching Tuple is available. But do NOT remove it from the tuple space. For WAITTOREAD, NULL tuples are allowed, as they match anything. This version of waitToRead is for SubclassableTuples -- you supply a subclassable tuple and it returns the same --- which is actually the only thing possible since a subclassable tuple will never match a Tuple.
Parameters:
template - A template Tuple (one with at least one formal field) that is used to match a tuple in the space.
Returns:
The SubclassableTuple that matches the template SubclassableTuple.
Throws:
TupleSpaceException - There are problems invoking the command

waitToRead

public SubclassableTuple waitToRead(SubclassableTuple template,
                                    long timeout)
                             throws TupleSpaceException
Retrieve a Tuple from the space that matches the Tuple template. Block until matching Tuple is available or timeout interval is exceeded.

See the waitToRead(Tuple template) for additional comments.

Parameters:
template - A template SubclassableTuple (one with at least one formal field) that is used to match a tuple in the space.
timeout - (ms) Time interval that the command will wait before aborting the request and returning null.
Returns:
The SuperTuple that matches the template SuperTuple. If a timeout occurs, null will be returned.
Throws:
TupleSpaceException - There are problems invoking the command

waitToRead

public Tuple waitToRead(java.io.Serializable obj)
                 throws TupleSpaceException
Retrieve a Tuple from the space that matches the Tuple template. Block until matching Tuple is available. But do NOT remove if from the tuple space. For WAITTOREAD, NULL tuples are allowed, as they match anything.
Parameters:
obj - The Field of a tuple to match one in the space to be returned.
Returns:
The Tuple that matches the template Tuple constructed from the Serializable.
Throws:
TupleSpaceException - There are problems invoking the command

waitToRead

public Tuple waitToRead(java.io.Serializable obj1,
                        java.io.Serializable obj2)
                 throws TupleSpaceException
Retrieve a Tuple from the space that matches the Tuple template. Block until matching Tuple is available. But do NOT remove if from the tuple space. For WAITTOREAD, NULL tuples are allowed, as they match anything.
Parameters:
obj1 - The Field of a tuple to match one in the space to be returned.
obj2 - The Field of a tuple to match one in the space to be returned.
Returns:
The Tuple that matches the template Tuple constructed from the Serializable.
Throws:
TupleSpaceException - There are problems invoking the command

waitToRead

public Tuple waitToRead(java.io.Serializable obj1,
                        java.io.Serializable obj2,
                        java.io.Serializable obj3)
                 throws TupleSpaceException
Retrieve a Tuple from the space that matches the Tuple template. Block until matching Tuple is available. But do NOT remove it from the tuple space. For WAITTOREAD, NULL tuples are allowed, as they match anything.
Parameters:
obj1 - The Field of a tuple to match one in the space to be returned.
obj2 - The Field of a tuple to match one in the space to be returned.
obj3 - The Field of a tuple to match one in the space to be returned.
Returns:
The Tuple that matches the template Tuple constructed from the Serializable.
Throws:
TupleSpaceException - There are problems invoking the command

read

public SuperTuple read(SuperTuple template)
                throws TupleSpaceException
Retrieve a Tuple from the space that matches the Tuple template. Non-blocking. But do NOT remove it from the tuple space. For READ, NULL tuples are allowed, as they match anything. The most general read since the most general Tuple type, SuperTuple, is taken as the param which of course leads to a SuperTuple being returned.
Parameters:
template - A template SuperTuple (one with at least one formal field) that is used to match a tuple in the space.
Returns:
The SuperTuple that matches the template SuperTuple.
Throws:
TupleSpaceException - There are problems invoking the command

read

public Tuple read(Tuple template)
           throws TupleSpaceException
Retrieve a Tuple from the space that matches the Tuple template. Non-blocking. But do NOT remove it from the tuple space. For READ, NULL tuples are allowed, as they match anything. read will always return a Tuple when the template is a tuple since a tuple only matches a tuple.
Parameters:
template - A template Tuple (one with at least one formal field) that is used to match a tuple in the space.
Returns:
The Tuple that matches the template Tuple.
Throws:
TupleSpaceException - There are problems invoking the command

read

public SubclassableTuple read(SubclassableTuple template)
                       throws TupleSpaceException
Retrieve a Tuple from the space that matches the Tuple template. Non-blocking. But do NOT remove it from the tuple space. For READ, NULL tuples are allowed, as they match anything. A SubclassableTuple only matches another Subclassabletuple so this method returns a SubclassableTuple.
Parameters:
template - A template SubclassableTuple (one with at least one formal field) that is used to match a tuple in the space.
Returns:
The SubclassableTuple that matches the template SubclassableTuple.
Throws:
TupleSpaceException - There are problems invoking the command

read

public Tuple read(java.io.Serializable obj)
           throws TupleSpaceException
Retrieve a Tuple from the space that matches the Tuple template. Non-blocking. But do NOT remove if from the tuple space. For READ, NULL tuples are allowed, as they match anything.
Parameters:
obj - The Field of a tuple to match one in the space to be returned.
Returns:
The Tuple that matches the template Tuple constructed from the Serializable.
Throws:
TupleSpaceException - There are problems invoking the command

read

public Tuple read(java.io.Serializable obj1,
                  java.io.Serializable obj2)
           throws TupleSpaceException
Retrieve a Tuple from the space that matches the Tuple template. Non-blocking. But do NOT remove if from the tuple space. For READ, NULL tuples are allowed, as they match anything.
Parameters:
obj1 - The Field of a tuple to match one in the space to be returned.
obj2 - The Field of a tuple to match one in the space to be returned.
Returns:
The Tuple that matches the template Tuple constructed from the object.
Throws:
TupleSpaceException - There are problems invoking the command

read

public Tuple read(java.io.Serializable obj1,
                  java.io.Serializable obj2,
                  java.io.Serializable obj3)
           throws TupleSpaceException
Retrieve a Tuple from the space that matches the Tuple template. Non-blocking. But do NOT remove it from the tuple space. For READ, NULL tuples are allowed, as they match anything.
Parameters:
obj1 - The Field of a tuple to match one in the space to be returned.
obj2 - The Field of a tuple to match one in the space to be returned.
obj3 - The Field of a tuple to match one in the space to be returned.
Returns:
The Tuple that matches the template Tuple constructed from the object.
Throws:
TupleSpaceException - There are problems invoking the command

scan

public Tuple scan(SuperTuple template)
           throws TupleSpaceException
Retrieve all Tuples from the space that match a Tuple template. Scan is non-blocking -- it will read the current state of the tuple space and return. For SCAN, NULL tuples are allowed as a template, they match anything (this allows us to scan the entire space). Scan returns a Tuple that holds a set of tuples. Each Field is a Tuple that matched the template.
Parameters:
template - A template Tuple (one with at least one formal field) that is used to match a tuple in the space.
Returns:
A Tuple of Tuples. Each Field in the Tuple is a Tuple that matched the template Tuple.
Throws:
TupleSpaceException - There are problems invoking the command
See Also:
Field.formal()

scan

public Tuple scan(java.io.Serializable obj1,
                  java.io.Serializable obj2,
                  java.io.Serializable obj3)
           throws TupleSpaceException
Retrieve all Tuples from the space that match a Tuple template. Scan is non-blocking -- it will read the current state of the tuple space and return. For SCAN, NULL tuples are allowed as a template, they match anything (this allows us to scan the entire space). Scan returns a Tuple that holds a set of tuples. Each Field is a Tuple that matched the template.
Parameters:
obj1 - An object to match the first Field against.
obj2 - An object to match the second Field against.
obj3 - An Serializable to match the second Field against.
Returns:
A Tuple of Tuples. Each Field in the Tuple is a Tuple that matched the template Tuple.
Throws:
TupleSpaceException - There are problems invoking the command
See Also:
Field.formal()

scan

public Tuple scan(java.io.Serializable obj1,
                  java.io.Serializable obj2)
           throws TupleSpaceException
Retrieve all Tuples from the space that match a Tuple template. Scan is non-blocking -- it will read the current state of the tuple space and return. For SCAN, NULL tuples are allowed as a template, they match anything (this allows us to scan the entire space). Scan returns a Tuple that holds a set of tuples. Each Field is a Tuple that matched the template.
Parameters:
obj1 - An Serializable to match the first Field against.
obj2 - An Serializable to match the second Field against.
Returns:
A Tuple of Tuples. Each Field in the Tuple is a Tuple that matched the template Tuple.
Throws:
TupleSpaceException - There are problems invoking the command
See Also:
Field.formal()

scan

public Tuple scan(java.io.Serializable obj)
           throws TupleSpaceException
Retrieve all Tuples from the space that match a Tuple template. Scan is non-blocking -- it will read the current state of the tuple space and return. For SCAN, NULL tuples are allowed as a template, they match anything (this allows us to scan the entire space). Scan returns a Tuple that holds a set of tuples. Each Field is a Tuple that matched the template.
Parameters:
obj - An Serializable to match the first Field against.
Returns:
A Tuple of Tuples. Each Field in the Tuple is a Tuple that matched the template Tuple.
Throws:
TupleSpaceException - There are problems invoking the command

consumingScan

public Tuple consumingScan(SuperTuple template)
                    throws TupleSpaceException
Retrieve and delete all Tuples from the space that match a Tuple template. ConsumingScan is non-blocking -- it will read the current state of the tuple space and return. For CONSUMINGSCAN, NULL tuples are allowed as a template, they match anything (this allows us to scan the entire space). ConsumingScan returns a Tuple that holds a set of tuples. Each Field is a Tuple that matched the template.
Parameters:
template - A template Tuple (one with at least one formal field) that is used to match a tuple in the space.
Returns:
A Tuple of Tuples. Each Field in the Tuple is a Tuple that matched the template Tuple.
Throws:
TupleSpaceException - There are problems invoking the command

consumingScan

public Tuple consumingScan(java.io.Serializable obj1,
                           java.io.Serializable obj2,
                           java.io.Serializable obj3)
                    throws TupleSpaceException
Retrieve and delete all Tuples from the space that match a Tuple template. ConsumingScan is non-blocking -- it will read the current state of the tuple space and return. For CONSUMINGSCAN, NULL tuples are allowed as a template, they match anything (this allows us to consumingScan the entire space). ConsumingScan returns a Tuple that holds a set of tuples. Each Field is a Tuple that matched the template.
Parameters:
obj1 - An Serializable to match the first Field against.
obj2 - An Serializable to match the second Field against.
obj3 - An Serializable to match the second Field against.
Returns:
A Tuple of Tuples. Each Field in the Tuple is a Tuple that matched the template Tuple.
Throws:
TupleSpaceException - There are problems invoking the command

consumingScan

public Tuple consumingScan(java.io.Serializable obj1,
                           java.io.Serializable obj2)
                    throws TupleSpaceException
Retrieve and delete all Tuples from the space that match a Tuple template. ConsumingScan is non-blocking -- it will read the current state of the tuple space and return. For CONSUMINGSCAN, NULL tuples are allowed as a template, they match anything (this allows us to consumingScan the entire space). ConsumingScan returns a Tuple that holds a set of tuples. Each Field is a Tuple that matched the template.
Parameters:
obj1 - An Serializable to match the first Field against.
obj2 - An Serializable to match the second Field against.
Returns:
A Tuple of Tuples. Each Field in the Tuple is a Tuple that matched the template Tuple.
Throws:
TupleSpaceException - There are problems invoking the command

consumingScan

public Tuple consumingScan(java.io.Serializable obj)
                    throws TupleSpaceException
Retrieve and delete all Tuples from the space that match a Tuple template. ConsumingScan is non-blocking -- it will read the current state of the tuple space and return. For CONSUMINGSCAN, NULL tuples are allowed as a template, they match anything (this allows us to consumingScan the entire space). ConsumingScan returns a Tuple that holds a set of tuples. Each Field is a Tuple that matched the template.
Parameters:
obj - An Serializable to match the first Field against.
Returns:
A Tuple of Tuples. Each Field in the Tuple is a Tuple that matched the template Tuple.
Throws:
TupleSpaceException - There are problems invoking the command

count

public Tuple count(SuperTuple template)
            throws TupleSpaceException
Count all tuples from the space that match a Tuple template. Count is non-blocking -- it will read the current state of the tuplespace and return. For Count, NULL tuples are allowed, as they match anything (this allows us to count the entire space). Count returns a tuple that holds a single Integer value. Use countN if you want an "int" returned directly.
Parameters:
template - A template Tuple (one with at least one formal field) that is used to match a tuple in the space.
Returns:
A Tuple with a single Field of type Integer that holds the number of Tuples that matched the template Tuple.

countN

public int countN(SuperTuple template)
           throws TupleSpaceException
Count all tuples from the space that match a Tuple template. Count is non-blocking -- it will read the current state of the tuplespace and return. For Count, NULL tuples are allowed, as they match anything (this allows us to count the entire space). This is the same as the method "count", but it returns an int instead of a tuple with an Integer. Count returns a tuple that holds a single integer value.
Parameters:
template - A template Tuple (one with at least one formal field) that is used to match a tuple in the space.
Returns:
An int that is the number of Tuples that matched the template Tuple.
Throws:
TupleSpaceException - There are problems invoking the command

delete

public int delete(SuperTuple template)
           throws TupleSpaceException
Delete all tuples that match this template.
Parameters:
template - A template Tuple that is used to match tuples in the space.
Returns:
An int that is the number of Tuples that were deleted
Throws:
TupleSpaceException - There are problems invoking the command

deleteAll

public int deleteAll()
              throws TupleSpaceException
Delete all tuples in a space.
Returns:
An int that is the number of Tuples that were deleted
Throws:
TupleSpaceException - There are problems invoking the command

indexCreate

public Tuple indexCreate(java.lang.String name,
                         java.lang.Class classtype,
                         ConfigTuple config,
                         boolean rebuild)
                  throws TupleSpaceException
Create an index and specify Index Configuration. This will setup an index for the Field name and class specified. The resulting index will use the parameters specified in the ConfigTuple. The rebuild parameter will determine what happens if the TupleSpace already has Tuples stored in them. If rebuild is true, then any existing index will be destoyed, a new index will be built and the Tuples will be reindexed. if rebuild is false, then an exception will be thrown if a matching index already exists. If there is no matching index, then the index will be build and will be used for all subsequent Tuples written to the space.
Parameters:
name - Field name that is being indexed
class - Class of Objects that are contained in this index
config - Instance of ConfigTuple that describes Index attributes.
rebuild - true if Index should be rebuilt. false if it should not be rebuilt.
Returns:
A Tuple that describes the resulting index status **
Throws:
TupleSpaceException - There were problems preparing the command to be sent to the server.
See Also:
Field, ConfigTuple

indexStatus

public Tuple indexStatus(java.lang.String name)
                  throws TupleSpaceException
Get back the status of a Field index.
Parameters:
name - Field name that is being indexed
config - Instance of ConfigTuple that describes Index attributes.
Returns:
A Tuple that describes the resulting index status
Throws:
TupleSpaceException - There are problems invoking the command

indexDestroy

public void indexDestroy(java.lang.String name)
                  throws TupleSpaceException
Destroy an index. Matching FieldNames will no longer be indexed
Parameters:
name - Field name that is being indexed
Returns:
none
Throws:
TupleSpaceException - There are problems invoking the command

checkpoint

public void checkpoint()
                throws TupleSpaceException
Tells CheckpointManager to checkpoint the space.
Returns:
none
Throws:
TupleSpaceException - There are problems invoking the command

rhonda

public Tuple rhonda(Tuple tuple)
             throws TupleSpaceException
The rendevous primitive. The rhonda operator takes a tuple as an argument and atomically swaps with another matching rhonda tuple. That is, if process 1 and process 2 perform rhondas on Tuples that have matching templates, the tuple that is returned to them is the other processes tuple. This is useful for atomic synchronization
 For example:
   // Issue Rhonda operator For Rock Paper Sissors
   //   pass a Tuple template with my Id and choice of R, P, or S
    //   It will return any existing rhonda matching template or wait until
    //   one appears.
    Tuple myTuple = new Tuple(new Field(Id),new Field(RPS));
    Tuple otherTuple = ts.rhonda(myTuple)       

    String opponent = (String)otherTuple.getField(0).getValue();
    String answer = (String)otherTuple.getField(1).getValue();

Parameters:
tuple - The data tuple (to "out")
Returns:
Tuple for the matching rhonda operation.

makeJarFile

public byte[] makeJarFile(java.lang.Class[] classes_)
                   throws java.io.IOException,
                          TupleSpaceClientException
For all the classes, if the class is in a jar file, grab the entire jar file otherwise for plain .class classes ship them in their own .jar file. This leads to the possibility of returning multiple byte arrays for different .jar files (for now actually only make one jar file, don't do what is stated wait till class loaders in place to see best way to do this) BUG Alert.
Parameters:
classes_ - the classes to make it from
Returns:
the byte arrays which correspond to the jar files
Throws:
java.io.IOException - if there is a problem creating the jar file
TupleSpaceClientException - if there is a problem getting the byte code for one of the classes

addHandler

public void addHandler(java.lang.String name,
                       java.lang.Class[] classes)
                throws TupleSpaceException
Add a new handler to this tuple space. The handler is added to the top factory --- the one most recently added. Note though that a lower level add handler command may be used to accomplish this. We probably need to add more synchronization commands and a stronger API for handler/factory maintenance. Right now, the client can check for SystemTuples that contain info on which handlers belong to which factories and what levels in the chain each factory is at.
Parameters:
classes - the classes for the handler the handler should be the last one
Throws:
TupleSpaceClientException - if all the classes are not there

getFactoryStack

public Tuple getFactoryStack()
                      throws TupleSpaceException
Return a scan of all the factory names for this tuple space and their level numbers --- level 0 is the highest --- most recently added --- factory.
Throws:
TupleSpaceCommunicationException - There are problems connecting to the TupleSpace Server
TupleSpaceServerException - There was a problem executing the command on the server.
TupleSpaceClientException - There were problems preparing the command to be sent to the server.
See Also:
TSFactory#updateFactoryInfo

getHandlerCommandNames

public Tuple getHandlerCommandNames(java.lang.String factoryName_)
                             throws TupleSpaceException,
                                    TupleSpaceClientException,
                                    TupleSpaceServerException
Return a scan of all the handler names for this factory --- this feature is *NOT* supported for the built in commands --- TSFSmallTS handlers. Well, it is supported but will just return an empty scan tuple. Also note that the functionality is not general purpose in that it only tells us the commands that are supported but not what type of tuples the command operates on or whatever other criteria there is for a handler to decide if it wants to act on a tuple.
Parameters:
factoryName_ - the name of the factory we are interested in.
Throws:
TupleSpaceException - There were problems preparing the command to be sent to the server.
See Also:
TSFactory#addHandler

addFactory

public void addFactory(java.lang.Class[] classes)
                throws TupleSpaceException
add a new factory to this tuple space as the topmost (most powerful) factory.
Parameters:
classes - the classes_ all the classes needed to implement the factory that aren't part of the TupleSpace library with the factory itself being the first one. The factory itself is the class that is derived in some fashion from TSFactory that the user wants to be the implementation of the new factory.
Throws:
TupleSpaceClientException - if all the classes are not there

destroy

public void destroy()
             throws TupleSpaceException

parseConfigTuple

public static java.lang.Object parseConfigTuple(java.lang.String fieldName_,
                                                SuperTuple configTuple_)
                                         throws TupleSpaceException

exists

public static boolean exists(java.lang.String tsName_,
                             java.lang.String tsServer_)
                      throws TupleSpaceException

exists

public static boolean exists(java.lang.String tsName_,
                             java.lang.String tsServer_,
                             int tsPort_)
                      throws TupleSpaceException

status

public static Tuple status(java.lang.String tsServer_)
                    throws TupleSpaceException

status

public static Tuple status(java.lang.String tsServer_,
                           int tsPort_)
                    throws TupleSpaceException

shutdown

public static Tuple shutdown(java.lang.String tsServer_,
                             int tsPort_,
                             java.lang.String user_,
                             java.lang.String password_)
                      throws TupleSpaceException

eventRegister

public int eventRegister(java.lang.String commandName_,
                         SuperTuple argTuple_,
                         Callback callback_)
                  throws TupleSpaceException
Register for an event on the server.

This is a convenience method that will call the real method with the "newThread" value set to the default. The default can be changed using the setCallbackThreads method.

Parameters:
commandName_ - the operation "WRITE" or "DELETE" to be on the watch for!
argTuple_ - the tuple to be on the look at for happening on the above commandName
callback_ - what class object contains the call() method that will be called when the event happens.
Returns:
the sequence number for this registration.

eventRegister

public int eventRegister(java.lang.String commandName_,
                         SuperTuple argTuple_,
                         Callback callback_,
                         boolean callbackThreads_)
                  throws TupleSpaceException
Register for an event on the server.

An event is the exection of a "WRITE" or "DELETE" on some tuple. The selection of which tuples you are interested in is via a template tuple

You must have a class that implements Callback. The Callback interface defines a call() method tht is given control when the event occurs. The call() method should returns false for deregistering after a call is executed

If you have the newThread parameter set to false, then MAKE SURE you don't do much in your callback handler, the thread that handles communication to the tuple space server(s) for this VM will be calling you personally and you don't want to tie that guy up. If you issue another TupleSpace command in the callback without having created a new thread, then it will hang. On the otherhand, it is expensive to create a new Thread so if you don't need to do much, then it is better to use the existing global callbackThread. Also, multiple Threads can cause sysncronization problems that you must be prepared to handle.

This code will first call the TSCmd instance to warn it to expect event to arrive and then will send the Register command to the server.

Parameters:
commandName_ - the operation "WRITE" or "DELETE" to be on the watch for!
argTuple_ - the tuple to be on the look at for happening on the above commandName
callback_ - what class object contains the call() method that will be called when the event happens.
callbackThreads - If true, a new Thread will be created to handle the callback.
Returns:
the sequence number for this registration.

eventDeRegister

public void eventDeRegister(int seqNum)
                     throws TupleSpaceException
DeRegister for some event on the server. An event is the exection of some command on some tuple. It will call the EventDeregister command at the server and then it will call the TSCmd interface to tell it to not expect anymore events.
Parameters:
seqNum - the sequence number of the event to be deregisterd.

cleanup

public static void cleanup()
this method is used to close the current connections to the server. The method closes down the streams connecting the client to the server. This way the server can tell that this is a normal termination. Notice that this is a static class method and closes down all TSpace connections not just the ones to specified space or server. Note that this command makes very little attempt to cleanup safely. If there are other threads that are actively using the connections, the results are unpredicable. The user should implement a method for telling the other threads to stop if that is an issue.

cleanup

public static void cleanup(java.lang.String server_,
                           int port_)
this method is used to close the current connections to the specified server. The method closes down the streams connecting the client to the server. This way the server can tell that this is a normal termination. Notice that this is a static class method and closes down all TSpace connections to the specified server. Note that this command makes very little attempt to cleanup safely. If there are other threads that are actively using the connections, the results are unpredicable. The user should implement a method for telling the other threads to stop if that is an issue.

command

public SuperTuple command(java.lang.String cmdString_,
                          SuperTuple argTuple_)
                   throws TupleSpaceException
Issue a command to the TupleSpace and pass along a Tuple as an argument. The command is a text string that is recongized by the TupleSpace. The results of the command, if any, are returned as a Tuple.
Parameters:
cmdString_ - The String that names the command.
argTuple_ - The argument Tuple, can be null.
Returns:
A result Tuple, the format of which depends upon the command.
Throws:
TupleSpaceException - There are problems invoking the command
See Also:
TupleSpaceHandler

command

public SuperTuple command(java.lang.String cmdString_,
                          SuperTuple argTuple_,
                          long timeout_)
                   throws TupleSpaceException
Issue a command to the TupleSpace and pass along a Tuple as an argument. The command is a text string that is recongized by the TupleSpace. The results of the command, if any, are returned as a Tuple. A timeout value is also supplied to cause the command to be aborted if the command has not returned in answer.
Parameters:
cmdString_ - The String that names the command.
argTuple_ - The argument Tuple, can be null.
timeout_ - Timeout value (ms)
Returns:
A result Tuple, the format of which depends upon the command.
Throws:
TupleSpaceException - There are problems invoking the command
See Also:
TupleSpaceHandler

getName

public java.lang.String getName()
Return the space name. Cool for debugging.
Returns:
String - the name of the space

getServer

public java.lang.String getServer()
Return the name of the server. Cool for debugging.
Returns:
String - the name of the server

getPort

public int getPort()
Return the number of the port. Cool for debugging.
Returns:
int - the number of the port

getVersion

public static java.lang.String getVersion()
Class Method to Return the TSpaces Code Version number. This Version number is in the form: V.L.M Where "V" is the Version and is currently 1. "L" is the Level number "M" is the Modification number. For example: 1.0.1 The intent is that the "V" version number will change only for a very major change. The "L" Level number will change when new major new features are added and/or incompatible changes are made. The "M" Modification number will change when a new level of code is distributed to fix problems and posibly add minor new compatible function.
Returns:
String - Version.Level.Modificatio

out

public void out(Tuple tuple)
         throws TupleSpaceException,
                TupleSpaceCommunicationException,
                TupleSpaceClientException,
                TupleSpaceServerException
Deprecated. Use write() instead

Add the Tuple to the Tuple Space.
Parameters:
tuple - The Tuple to be added to the space.
Throws:
TupleSpaceException - If a formal (template) tuple is passed, or the Tuple has no Fields.
TupleSpaceCommunicationException - There are problems connecting to the TupleSpace Server
TupleSpaceServerException - There was a problem executing the command on the server.
TupleSpaceClientException - There were problems preparing the command to be sent to the server.

in

public Tuple in(Tuple template)
         throws TupleSpaceException,
                TupleSpaceCommunicationException,
                TupleSpaceClientException,
                TupleSpaceServerException
Deprecated. Use waitToTake() instead.

Retrieve a tuple from the space that matches a Tuple template. Block until a match is found. Remove the Tuple from the space. For IN (aka CONSUME), we will require that tuples have content (no NULL tuples).
Parameters:
template - A template Tuple (one with at least one formal field) that is used to match a tuple in the space.
Returns:
The Tuple that matches the template Tuple.
Throws:
TupleSpaceException - If the Tuple has no Fields.
TupleSpaceCommunicationException - There are problems connecting to the TupleSpace Server
TupleSpaceServerException - There was a problem executing the command on the server.
TupleSpaceClientException - There were problems preparing the command to be sent to the server.

inp

public SuperTuple inp(SuperTuple template)
               throws TupleSpaceException,
                      TupleSpaceCommunicationException,
                      TupleSpaceClientException,
                      TupleSpaceServerException
Deprecated. Use take() instead.

Retrieve a tuple from the space that matches a Tuple template. Do not block. Remove the Tuple from the space. For IN (aka CONSUME), we will require that tuples have content (no NULL tuples).
Parameters:
template - A template Tuple (one with at least one formal field) that is used to match a tuple in the space.
Returns:
The Tuple that matches the template Tuple. null if no match
Throws:
TupleSpaceException - If the Tuple has no Fields.
TupleSpaceCommunicationException - There are problems connecting to the TupleSpace Server
TupleSpaceServerException - There was a problem executing the command on the server.
TupleSpaceClientException - There were problems preparing the command to be sent to the server.

setDebug

public static void setDebug(boolean status)
This static class method will cause debugging information to be displayed on on STDOUT.
Parameters:
status - is true to turn on the debug output

main

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