IBM TSpaces Version 3

Client Programming Interface Specification

Introduction

Although we have JavaDoc, the purpose of this specification is to put in one spot all of the possible commands that one might call from a TSpaces client. Also, where possible, we've included examples to make the call and it's use as clear as possible. This is a companion to the main Client Programmer's Guide.



NOTES:

  1. This specification applies to TSpaces Version 3.1.*
  2. Static methods shown in Blue.
  3. Deprecated methods shown in Red.



TSpaces Methods

Here is a (mostly) complete listing of the TSpaces methods. Many of the TSpaces methods have multiple forms, as we allow default settings to be use for the more obscure parameters. We list the methods in alphabetical order, for convenience.


addFactory()

Explanation: Add a new factory to this tuple space as the topmost (most powerful) factory.

Definition: public void addFactory(String factoryclass)

Parameters: String factoryclass: the new class to be installed. factoryclass is the name of the class needed to implement the factory. This class must be in the classpath for the server.

Return:

Exception: Throws TupleSpaceException if there were problems invoking the command.

Usage:

      Example:
      

addHandler()

Explanation: 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.

Definition: public void addHandler(String name, String className)

Parameters: name: The command name to be handled. className: The class used to implement the handler.

Return: none.

Exception: Throws TupleSpaceException if there were problems invoking the command.

Usage:

      Example:
      

checkpoint()

Explanation: Manually instruct the Checkpoint Manager to checkpoint the space.

Definition: void checkpoint()

Exception: Throws TupleSpaceException when there are problems invoking the command

Usage:

     Example:
       TupleSpace ts = new TupleSpace( ... );
       ts.checkpoint();
     

appletEnvironment()

Explanation: 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.

Definition: public static void appletEnvironment(boolean setting) {

Parameters: boolean setting: true if we want to run in an Applet environment

Return:

Exception: Throws TupleSpaceException if there were problems invoking the command.

Usage:

      Example:
      

cleanup() (Static Method)

Explanation: The cleanup() method is used to close connections to the servers being used by this JVM. The method closes down the streams connecting the client to the server. This way the server can tell that this is a normal termination. The different cleanup() methods have slighly different results:

Definitions:

      static void cleanup()
      static void cleanup( String serverName, int serverPort )
      static void cleanup( TupleSpace ts )
      static void cleanup( TSCmd tsCmd )
    

Parameters:

      String serverName: Name of the TS Host (default is localhost).
      int serverPort: Number of the port (default is 8200).
      TupleSpace ts: Handle for a specific connection.
      TSCmd tsCmd: The specific connection (internal use only)
      

Return: void

Exception: TupleSpaceException if there were errors.

Usage:

      TupleSpace.cleanup();  // close ALL TS connections in this JVM.
      TupleSpace.cleanup( server, port );  // close connections to this server
      TupleSpace.cleanup( ts );  // close connection for this TS instance
      TupleSpace.cleanup( tscmd );  // close connection for this TS instance
    

Notes:


count()

Explanation: 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.

Definition: Tuple count( SuperTuple template )

Parameters: template: A template Tuple (one with at least one formal field) that is used to match a tuple in the space.

Return: Return A Tuple with a single Field of type Integer that holds the number of Tuples that matched the template Tuple.

Exception: throws TupleSpaceException

Usage:

     Example:
       Tuple template = new Tuple( ... );
       TupleSpace ts = new TupleSpace( ... );
       Tuple resultTuple = ts.count( template );
     

countAll()

Explanation: Count all tuples and SubclasaableTuples from the space. CountAll is non-blocking -- it will read the current state of the tuplespace and return.

Definition: int count( SuperTuple template )

Parameters: none.

Return: CountAll returns an int that is the total number of tuples and SubclassableTuples.

Exception: throws TupleSpaceException

Usage:

     Example:
       TupleSpace ts = new TupleSpace( ... );
       int resultCount = ts.countAll( );
     

countN()

Explanation: 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 in the query template, as they match anything (this allows us to count the entire space). This is a convenience method for the method "count", as it returns an int instead of a tuple with an Integer.

Definition: int count( SuperTuple template )

Parameters: template: A template Tuple (one with at least one formal field) that is used to match a tuple in the space.

Return: Return an int that is the number of Tuples that matched the template Tuple.

Exception: Throws TupleSpaceException in the event of errors.

Usage:

     Example:
       Tuple template = new Tuple( ... );
       TupleSpace ts = new TupleSpace( ... );
       int resultCount = ts.countN( template );
     

createSpace() (Static Method)

Explanation: Create a new TupleSpace. Space creation can be done implicitly by opening up a new TupleSpace connection (calling the TupleSpace constructor) or it can be done explicitly by a createSpace() call. If the space already exists, then this will throw an Exception. If the space does not already exist, it will be created and a reference to the created TupleSpace will be returned. Server can be specified as name:nnn where name is the severname and nnn is the port number. If :nnn is not present then the Default port is used.

The parameters are described in more detail in the TupleSpace constructor below

Definition: static public TupleSpace createSpace( String name, String tsServer, int tsPort, ConfigTuple configuration, SuperTuple accessPermissions, String userName, String password )

Parameters:

Return: the TupleSpace Object.

Exception:

Usage:

      Example:
      

delete()

Explanation: Delete all tuples that match this template.

Definition: int delete( SuperTuple template )

Parameters: SuperTuple template: query template

Parameters: SuperTuple template: this is used to match tuples in the space.

Return: An int that is the number of Tuples that were deleted

Exceptions: Throws TupleSpaceException when there are problems invoking the command

Usage:

     Example:
       TupleSpace ts = new TupleSpace( ... );
       int numDeleted = ts.delete();
     

deleteAll()

Explanation: Delete all Tuple objects and SubclassableTuple objects in a space.

Definition: int deleteAll( )

Return: Return an int that is the number of SuperTuples that were deleted.

Exception: Throws TupleSpaceException if there were problems invoking the command. throws TupleSpaceException in case of error.

Usage:

     Example:
       TupleSpace ts = new TupleSpace( ... );
       int numDeleted = ts.deleteAll();
     

deleteTupleById()

Explanation: 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

Definition: void deleteTupleById( TupleID tupleID )

Parameters: tupleID: the identifier of the tuple to be deleted

Exceptions:

Usage:

     Example:
       TupleID id = tuple.getTupleID();
       ts.deleteTupleById(id);
     

destroy()

Explanation: Destroy the TupleSpace. This command removes the space and the server reference (i.e. it removes the space tuple from the galaxy).

Definition: public void destroy()

Parameters:

Return: none.

Exception: Throws TupleSpaceException if there were problems invoking the command.

Usage:

      Example:
      

eventRegister()

Explanation: eventRegister() allows the client to register for WRITE or DELETE events on the server.

Definitions:

Parameters:

Return: the sequence number for this registration.

Exception: Throws TupleSpaceException if there were problems invoking the command.

Usage:

Notes::


eventDeRegister()

Explanation: Basically the opposite of eventRegister(); remove the registration event.

Definition: void eventDeRegister ( int seqNum)

Parameters: int seq: the sequence number returned by the eventRegister() call.

Return: void.

Exception: Throws TupleSpaceException if there were problems invoking the command.

Usage:

     Example:
       TupleSpace ts = new TupleSpace( ... );
       int seq = eventRegister(TupleSpace.WRITE, template, this, true) ;
       ...
       ts.evenDeRegister( seq );
     

exists() (Static Method)

Explanation: Static class method to check if a specific tuple space exists.

Because this is a (static) class method, you must specify all of the information that is needed to locate the space, the same as in a TupleSpace constructor.

Definitions:

Parameters:

Return: true if the indicated space exists at the server.

Exception: Throws TupleSpaceException if there were problems invoking the command.

Usage:

      Example:
      

getCommandWaitTime()

Explanation: The Command Wait Time is the amount of time (in milliseconds) to wait for a response to a command. If the command does not respond in this interval, then it will throw a TupleSpaceException("TimeOut"). If the Default value (-1) is used, then there is no timeout and it will (potentially) wait forever. This method returns that value.

Definition: final public int getCommandWaitTime()

Parameters: (none)

Return: the time (in ms) to wait for a network response to any command.

Exception: Throws TupleSpaceException if there were problems invoking the command.

Usage:

      Example:
      

getConnectionTries (Static Method)

Explanation: Simple accessor method to get the connectionTries value for a connection. 0 signifies infinity --- try again and again.

Definitions:

Parameters:

Return: @return the number of times to try connecting to the server before failing

Exception: Throws TupleSpaceException if there were problems invoking the command.

Usage:

      Example:
      

getConnectionWaitTime() (Static Method)

Explanation: Simple accessor method to get the connection wait time. A value of ZERO signifies infinite wait time.

Definition: public static int getConnectionWaitTime() {

Parameters:

Return: the time (in seconds) to wait for a connection to the server before failing.

Exception: Throws TupleSpaceException if there were problems invoking the command.

Usage:

      Example:
      

getName()

Explanation: Return the space name corresponding to this TupleSpace connection. Notice that this should have been called "getSpaceName()".

Definition: final public String getName()

Return: the space name.

Exception: Throws TupleSpaceException if there were problems invoking the command.

Usage:

      Example:
      

getPort()

Explanation: Return the port number associated with this TupleSpace connection.

Definition: final public int getPort()

Return: Return the port number.

Exception: Throws TupleSpaceException if there were problems invoking the command.

Usage:

      Example:
      

getServer()

Explanation: Return the name of the TSpaces server in the form hostname:port.

Definition: final public String getServer()

Return: Return the server name.

Exception: Throws TupleSpaceException if there were problems invoking the command.

Usage:

      Example:
      

getUserName()

Explanation: Get the user name that corresponds to this server connection.

Definition: final public String getUserName()

Return: the user name.

Exception: Throws TupleSpaceException if there were problems invoking the command.

Usage:

      Example:
       TupleSpace ts = new TupleSpace( ... );
       String name = ts.getUserName();
      

getVersion()

Explanation: Class Method to Return the TSpaces Client Code Version number. This Version number is in the form: V.L.M

     Where "V" is the Version (and is currently 3)
           "L" is the Level number
           "M" is the Modification number.
     
For example: 3.1.6 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.

Definition: static String getVersion() {

Parameters: none.

Return: String - Version.Level.Modificatio

Exception: Throws TupleSpaceException if there were problems invoking the command.

Usage:

      Example:
      

indexCreate()

Explanation: 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.

Definition: Tuple indexCreate(String name, Class classtype, ConfigTuple config, boolean rebuild )

Parameters:

Return: A Tuple that describes the resulting index status.

Exception: Throws TupleSpaceException if there were problems invoking the command.

Usage:

      Example:
      

indexDestroy()

Explanation: Destroy an index. Matching FieldNames will no longer be indexed.

Definition: public void indexDestroy(String name)

Parameters: String name: Field name that is being indexed

Return:

Exception: Throws TupleSpaceException if there were problems invoking the command.

Usage:

      Example:
      

indexStatus()

Explanation: Get the status of an index. It comes in the form of a tuple.

Definition: public Tuple indexStatus(String name)

Parameters: String name: Field name that is being indexed.

Return: Tuple containing the answer.

Exception: Throws TupleSpaceException if there were problems invoking the command.

Usage:

      Example:
      

isActive() (Static Method)

Explanation: Check if a specific server is running/reachable. IF the client cannot connect to the server or has IO problems talking to the server the server is deemed NotRunning and this will return false.

Definition: static public boolean isActive ( String tsServer )

Parameters: String tsServer: the server to check for the tuple space in the form of hostname:port

Return: true if the server is reachable and false if it is not reachable

Exception: Throws TupleSpaceException if there were problems invoking the command.

Usage:

      Example:
      

isValidTSName()

Explanation: Verify that the TupleSpace name follows the syntacical rules. It must consist of alphamumeric characters or _ (underscore)

Definition: static public final boolean isValidTSName( String name )

Parameters: String name: The space name to be checked.

Return: @return true if this string contains only alpha-numeric characters or '_'

Exception: Throws TupleSpaceException if there were problems invoking the command.

Usage:

      Example:
      

multiRead()

Explanation: Retrieve all Tuples from the space that match a Tuple template. multiRead() is non-blocking -- it will read the current state of the tuple space and return. For multiRead, NULL tuples are allowed as a template, they match anything (this allows us to scan the entire space).

multiRead() has many forms, mainly for convenience. The most direct form passes a queryTemplate tuple in as a parameter, and multiRead() returns a "multiTuple" (a tuple of tuples) containing all of the tuples that matched the query template. The other forms are convenience methods that allow one to create a query template tuple "on the fly" with the supplied field(s). Unlike the Tuple constructor (which allows 7 fields), this allows up to only three fields.

Definition:

Parameters:

Return: multiRead() returns a "Tuple of Tuples". Each Field in the answer Tuple is a Tuple that matched the template Tuple.

Exception: Throws TupleSpaceException when there are problems invoking the command

Usage:

     Example:
       TupleSpace ts = new TupleSpace( ... );
       ts.multiRead( template );
     

multiTake()

Explanation: Retrieve all Tuples from the space that match a Tuple template. multiTake is non-blocking -- it will read the current state of the tuple space and return. For multiTake, NULL tuples are allowed as a template, they match anything (this allows us to scan the entire space).

multiTake() has many forms, mainly for convenience. The most direct form passes a queryTemplate tuple in as a parameter, and multiRead() returns a "multiTuple" (a tuple of tuples) containing all of the tuples that matched the query template. The other forms are convenience methods that allow one to create a query template tuple "on the fly" with the supplied field(s). Unlike the Tuple constructor (which allows 7 fields), this allows up to only three fields.

Definition:

  • Tuple multiTake( SuperTuple template )
  • Tuple multiTake( Serializable obj1 )
  • Tuple multiTake( Serializable obj1, Serializable obj2 )
  • Tuple multiTake( Serializable obj1, Serializable obj2, Serializable obj3 )

    Parameters:

    Return: multiRead() returns a "Tuple of Tuples". Each Field in the answer Tuple is a Tuple that matched the template Tuple.

    Exception: Throws TupleSpaceException when there are problems invoking the command

    Usage:

         Example:
           TupleSpace ts = new TupleSpace( ... );
           ts.multiRead( template );
         

    multiUpdate()

    Explanation: In a single transaction scope, update the set of tuples (encased in the "multiTuple" passed in) with the new values. Return an array of the tuple ids that were updated. ZERO or more tuples may be updated. Since this is done as a transaction (either stand-alone or in a larger context), either all of the updates at the server occur, or none of them do.

    Note: Each tuple in the "multiTuple" should be a SuperTuple.

    Definition: TupleID[] multiUpdate( Tuple multiTuple )

    Parameters: Tuple multiTuple: a tuple of tuples each of which is to be written to the space.

    Return: Return an array containing the TupleIDs for the tuples that were written.

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

         Example:
           TupleSpace ts = new TupleSpace( ... );
           Tuple multiTuple = new Tuple( sTuple1, sTuple2, ... sTuple6);
           TupleID[] tids = ts.multiUpdate( multiTuple );
         

    multiWrite()

    Explanation: In a single transaction scope, write the set of tuples (encased in the multiTuple passed in) to the space. Return an array of the tuple ids that were written. ZERO or more tuples may be written. Since this is done as a transaction (either stand-alone or in a larger context), either all of the writes at the server occur, or none of them do.

    Note: Each tuple in the "multiTuple" should be a SuperTuple.

    Definition: TupleID[] multiWrite( Tuple tuple ) throws TupleSpaceException {

    Parameters: Tuple multiTuple a tuple of tuples each of which is to be written to the space.

    Return: Return an array containing the TupleIDs for the tuples that were written.

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

         Example:
           TupleSpace ts = new TupleSpace( ... );
           Tuple multiTuple = new Tuple( sTuple1, sTuple2, ... sTuple6);
           TupleID[] tids = ts.multiWrite( multiTuple );
         

    ping()

    Explanation: The ping command is used to measure the responsiveness of the client/server connection and can be used to test that the connection is active.

    NOTE: This is intended to be more of a development tool then a user API command, but it does come in handy to check server responsiveness.

    Definition: public Tuple ping( )

    Parameters:

    Return: Tuple containing timestamps.

           Field 0 - Time sent. 
           Field 1 - Time arrived at server.
           Field 2 - Time response at client.
        

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

          Example:
          

    read()

    Explanation: Retrieve a Tuple from the space that matches the Tuple template, but do NOT remove it from the space. read() is non-blocking. For READ, NULL tuples are allowed, as they match anything.

    Multiple forms of read() exist. The most general takes a superTuple template and returns a superTuple. There are also forms that take a tuple (and return a tuple), or a subclassible tuple (and return the same). There are some convenience forms that allow the user to create a query tuple "on the fly", by including it directly in the call (e.g. take("field1", "field2", "field3"); ).

    The last form of read() allows a user to create their own Query object and pass it directly in the read() routine.

    Definitions:

    Parameters:

    Return: The SuperTuple that matches the template SuperTuple.

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

        Example1: (regular SuperTuple case)
          TupleSpace ts = new TupleSpace( ... );
          SuperTuple answer = ts.read( template );
        
        Example 2: (exotic Query Object case)
          String indexName = "Studentname";  // Name of the indexed field.
          Object searchValue = "John Thomas"; // Regular Value
          TupleSpace ts = new TupleSpace( ... );
          Query iq = new IndexQuery( indexName, searchValue );
          SuperTuple answer = ts.read( iq );
        
        Example 3: (more exotic Query Object case with range)
          String indexName = "StudentID";  // Name of the indexed field.
          Range range = new Range( new Long(555), new Long(777) );
          TupleSpace ts = new TupleSpace( ... );
          Query iq = new IndexQuery( indexName, range );
          SuperTuple answer = ts.read( iq );
        

    readAll()

    Explanation: Read all Tuple objects and SubclassableTuple objects in a space. This is basically a shortcut for read( nullSuperTuple ), which should match all tuples of any type.

    Definition: public Tuple readAll( )

    Parameters: none.

    Return: the answer "multi-Tuple", which has a field for each SuperTuple returned.

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

          Example:
          

    readClass()

    Explanation: Read a ClassTuple object from the current space.

    Definition: public ClassTuple readClass( String className )

    Parameters: String className: The name of the class.

    Return: ClassTuple object that contains the byte code for the class.

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

          Example:
          

    readTupleById()

    Explanation: 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.

    Definition: SuperTuple readTupleById( TupleID id )

    Parameters: TupleID id: The id of the tuple to be returned.

    Return: Return the specified tuple, assuming the TupleID is valid (null otherwise)

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

        Example:
          TupleSpace ts = new TupleSpace( ... );
          TupleID id = ts.write(tuple);
          ts.readTupleById(id);
        

    reconnect()

    Explanation: After a line drop, a client can issue a reconnect() call to re-establish the connection. It is expected that all active transactions are closed. Any active transaction will trigger an exception.

    Definition: public TSCmd reconnect()

    Parameters: none.

    Return: the TSCmd communication line implementation.

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

          Example:
          

    setCallbackThreads() (Static Method)

    Explanation: 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 synchronization problems that you must be careful to handle.

    Definition: public static void setCallbackThreads(boolean callbackThreads) {

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

    Return: void.

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

          Example:
          

    setCommandWaitTime()

    Explanation: The Command Wait Time is the amount of time (in milliseconds) to wait for a response to a command. If the command does not respond in this interval, then it will throw a TupleSpaceException("TimeOut"). If the Default value (-1) is used, then there is no timeout and it will (potentially) wait forever. This method sets that value.

    Definition: public void setCommandWaitTime(int commandWaitTime)

    Parameters: int commandWaitTime: wait this long (in milliseconds)

    Return: none

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

          Example:
          

    setConnectionTries (Static Method)

    Explanation: Simple setter method to set the connectionTries to a new value. 0 signifies infinity --- try again and again.

    Definitions:

    1. public static int getConnectionTries()
    2. public static void setConnectionTries(int connectionTries)

    Parameters: int connectionTries: the number of times to try connecting to the server before failing

    Return:

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

          Example:
          

    setConnectionWaitTime() (Static Method)

    Explanation: Simple setter method to set the connection wait time to a new value. Class method to set the connectionWaitTime to a new value. 0 signifies no wait - wait forever.

    Definition: public static void setConnectionWaitTime(int connectionWaitTime)

    Parameters: int connectionWaitTime: the time in seconds to wait for a connection

    Return:

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

          Example:
          

    setNewServerConnection (Static Method)

    Explanation: Set the switch that controls if a new Server connection will be setup for each TupleSpace instance.

    Definition: public static void setNewServerConnection(boolean setting)

    Parameters: boolean setting: true when we want to set up a new connection.

    Return: void.

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

          Example:
          

    setPassword()

    Explanation: Set default password to be used for access control for all spaces See comments on setUserName()

    Definition: public static void setPassword( String pass ) {

    Parameters: String pass: The new password

    Return:

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

          Example:
          

    setProxy() (Static Method)

    Explanation: Set a host:port that defines the Proxy that is used to access the TSpaces Server.

    Can be specified as hostname:port If ":port" is not specified, it defaults to :8080

    If set to "null" (the default value) then no proxy is used. Note that the host and port for the actual TSpaces server is defined on the constructor.

    Definition: public static void setProxy( String proxy )

    Parameters: String proxy: The Proxy hostname:port used for the proxy.

    Return: none.

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

          Example:
          

    setTSClassPath()

    Explanation: Tell the server where to look for client defined Class objects that are not found in the normal classpath.

    Definition: public void setTSClassPath( String spaceName )

    Parameters: String spaceName The name of the space to be used to resolve client application objects.

    Return: none.

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

          Example:
          

    setUserName()

    Explanation: 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.

    Definition: public static void setUserName( String name ) {

    Parameters: String name: The new username

    Return: none.

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

          Example:
          

    shutdown() (Static Method)

    Explanation: Send a shutdown request to the server. (Static Method)

    Definition: static Tuple shutdown( String tsServer, int tsPort , String user, String password)

    Parameters:

    Return: return the OK tuple if no exception

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

         Example:
           TupleSpace.shutdown( server, port, user, password);
         

    status() (Static Method)

    Explanation: Check if a specific server is running/reachable. IF the client cannot connect to the server or has IO problems talking to the server the server is deemed NotRunning.

    Server can be specified as name:nnn where name is the severname and nnn is the port number. If :nnn is not present then the Default port is used.

    Definition:

    Parameters:

    Return: Return the status tuple for now this is either:
    Tuple( "Running", ServerInfo)
    Tuple("NotRunning", TupleSpaceException)
    the server version number is a string.

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

         Example1: TupleSpace.status( tsServer );
         Example2: TupleSpace.status( tsServer, tsPort );
         Example3:
            Tuple active = TupleSpace.status(host,TupleSpace.DEFAULT_PORT); 
            if ( active.getField(0).getValue().equals(TupleSpace.NOT_RUNNING)) {
              System.out.println("Server not running on " +   host );
              System.out.println("Reason: "+active.getField(1).getValue());
              return;
            }  else  {
              ServerInfo info = (ServerInfo)active.getField(1).getValue(); 
              System.out.println("TSpaces Server: Version = "+ info.getVersion() );
            }
          

    See Also:


    take()

    Explanation: Performs an associative search for a tuple that matches the template. When found, the tuple is removed from the space and returned. If none is found, returns null.

    Multiple forms of take() exist. The most general takes a superTuple template and returns a superTuple. There are also forms that take a tuple (and return a tuple), or a subclassible tuple (and return the same). There are some convenience forms that allow the user to create a query tuple "on the fly", by including it directly in the call (e.g. take("field1", "field2", "field3"); ).

    Definition:

    Parameters:

    Return:

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

         Example:
           TupleSpace ts = new TupleSpace( ... );
           SuperTuple template = new SuperTuple( ... );
           SuperTuple sTuple = ts.take( template );
          

    The last form of read() allows a user to create their own Query object and pass it directly in the read() routine.

    Definitions:

    Parameters:

    Return: The SuperTuple that matches the template SuperTuple.

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

        Example1: (regular SuperTuple case)
          TupleSpace ts = new TupleSpace( ... );
          SuperTuple answer = ts.read( template );
        
        Example 2: (exotic Query Object case)
          String indexName = "Studentname";  // Name of the indexed field.
          Object searchValue = "John Thomas"; // Regular Value
          TupleSpace ts = new TupleSpace( ... );
          Query iq = new IndexQuery( indexName, searchValue );
          SuperTuple answer = ts.read( iq );
        
        Example 3: (more exotic Query Object case with range)
          String indexName = "StudentID";  // Name of the indexed field.
          Range range = new Range( new Long(555), new Long(777) );
          TupleSpace ts = new TupleSpace( ... );
          Query iq = new IndexQuery( indexName, range );
          SuperTuple answer = ts.read( iq );
        

    takeAll()

    Explanation: Read and delete all Tuple objects and SubclassableTuple objects in a space. This is basically a shortcut for take( nullSuperTuple ), which should match all tuples of any type.

    Definition: public Tuple takeAll( )

    Parameters: none.

    Return: the answer "multi-Tuple", which has a field for each SuperTuple returned.

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

          Example:
          

    takeClass()

    Explanation: Read a ClassTuple object from the current space.

    Definition: public ClassTuple takeClass( String className )

    Parameters: className: The name of the class.

    Return: ClassTuple object that contains the byte code for the class.

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

          Example:
          

    takeTupleById()

    Explanation: 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.

    Definition: SuperTuple takeTupleById( TupleID id )

    Parameters: TupleID id: the identifier of the tuple to be deleted

    Return: The specified tuple.

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

         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
        
         

    update()

    Explanation: Update the tuple in the space that matches the supplied template (or replacer tuple). If update() is matching just a replacer tuple, it is assumed that the replacer tuple 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.

    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. Note that the template and replacer need not have the same signature.

    Definitions:

    Parameters: SuperTuple replacer: the tuple to be updated

    Return: Return the TupleID of the replacement tuple.

    Exceptions:

    Usage:


    waitToRead()

    Explanation: 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. If a timeout value (in milliseconds) is given, then block until a matching tuple is available or the timeout interval is exceeded.

    waitToRead() has many forms, mainly for convenience. The most general form supplies a SuperTuple as the query template and returns a SuperTuple. For this form, it is up to the user to know what type of tuple is being returned and to cast the result to the proper type. 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. Note: a "standard" tuple template returns only standard tuples (not subclassible tuples), and a subclassible template returns only subclassible tuples, not standard tuples.

    The other forms are convenience methods that allow one to create a query template tuple "on the fly" with the supplied field(s). Unlike the Tuple constructor (which allows 7 fields), this allows up to only three fields.

    Definitions:

    Parameters:

    Return: The SuperTuple that matches the template SuperTuple or null if no match.

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

        Example1: (regular SuperTuple case)
          TupleSpace ts = new TupleSpace( ... );
          SuperTuple answer = ts.waitToRead( template );
        
        Example 2: (exotic Query Object case)
          String indexName = "Studentname";  // Name of the indexed field.
          Object searchValue = "John Thomas"; // Regular Value
          TupleSpace ts = new TupleSpace( ... );
          Query iq = new IndexQuery( indexName, searchValue );
          SuperTuple answer = ts.waitToRead( iq );
        
        Example 3: (more exotic Query Object case with range)
          String indexName = "StudentID";  // Name of the indexed field.
          Range range = new Range( new Long(555), new Long(777) );
          TupleSpace ts = new TupleSpace( ... );
          Query iq = new IndexQuery( indexName, range );
          SuperTuple answer = ts.waitToRead( iq );
        

    waitToTake()

    Explanation: Remove a Tuple from the space that matches the Tuple template. Block until matching Tuple is available. For waitToTake(), NULL tuples are allowed, as they match anything. If a timeout value (in milliseconds) is given, then block until a matching tuple is available or the timeout interval is exceeded.

    waitToTake() has many forms, mainly for convenience. The most general form supplies a SuperTuple as the query template and returns a SuperTuple. For this form, it is up to the user to know what type of tuple is being returned and to cast the result to the proper type. 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. Note: a "standard" tuple template returns only standard tuples (not subclassible tuples), and a subclassible template returns only subclassible tuples, not standard tuples.

    The other forms are convenience methods that allow one to create a query template tuple "on the fly" with the supplied field(s). Unlike the Tuple constructor (which allows 7 fields), this allows up to only three fields.

    Definitions:

    Parameters:

    Return: The SuperTuple that matches the template SuperTuple or null if no match.

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

        Example1: (regular SuperTuple case)
          Tuple template = new Tuple( ... );
          long timeout = 2 * 1000;  // wait no more than two seconds.
          TupleSpace ts = new TupleSpace( ... );
          SuperTuple answer = ts.waitToTake( template );
        

    write()

    Explanation: Add the newTuple to the Tuple Space. The Tuple must have at least one Field.

    Definitions:

    Parameters:

    Return: the TupleID of the newly written tuple.

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

          Example:
            TupleSpace ts = new TupleSpace( ... );
            TupleID tid = ts.write( "Hello World" );
          

    writeClass()

    Explanation: Add a ClassTuple to the Tuple Space that contains a class object that may be used in subsequent Tuples. The bytes that represent the class will be taken from the client classpath.

    Definitions:

    Parameters:

    Return: TupleID for the tuple that was written.

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

          Example:
          

    Other Classes available to the TSpaces Programmer

    There are several classes visible to the programmer, but the main one is the TupleSpace class.


    TupleSpace() The TupleSpace Constructor

    Explanation: The TupleSpace() constructor is used to create or access a named Tuple Space. There are many different permutations of constructores, mostly for convenience, but they all call the "main" one internally.

    An instance of TSCmd will be obtained by calling getCmdImpl(). The TSCmd implementation will handle all of the details of sending commands to the server and receiving responses.

    The constructor issues a TSCreate command to the server and passes whatever parameters were passed into the constructor such ass username, password, configuration and access permissions.

    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.

    A configuration tuple looks like:

        
            ConfigTuple config = new ConfigTuple();
            config.setOption(ConfigTuple.PERSISTENCE, BOOLEAN.FALSE );
            config.setOption(ConfigTuple.TSDBTYPE,TupleSpace._DBTYPE_MMDB);  
        
         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);
           Tuple access = new Tuple(myacl);
         
    The accessPermision Tuple is only used when the space is initially created.

    Definition:

    1. public TupleSpace( String spaceName, String tsServer, int tsPort, ConfigTuple configuration, SuperTuple accessPermissions, String userName, String password ): Connect to, or create a TupleSpace with all of the parameters specified.
    2. public TupleSpace(String name,TSCmd tsCmd, SuperTuple configuration, SuperTuple accessPermissions): Connect to, or create a TupleSpace when we already have a TSCmd object.
    3. public TupleSpace(): Connect to, or create a TupleSpace using the Default Space Name, LocalHost and Default port.
    4. public TupleSpace(ConfigTuple configuration): Use all of the default settings and this config Tuple.
    5. public TupleSpace( String spaceName ): Use this Space name and all of the other default settings.
    6. public TupleSpace( String spaceName, String userName, String password ): Use the supplied spaceName, UserName, PassWord and all of the other default settings.
    7. public TupleSpace( String spaceName, ConfigTuple configuration )
    8. public TupleSpace( String spaceName, ConfigTuple configuration, String userName, String password )
    9. public TupleSpace( String spaceName, String tsServer )
    10. public TupleSpace( String spaceName, String tsServer, String userName, String password )
    11. public TupleSpace( String spaceName, String tsServer, ConfigTuple configuration )
    12. public TupleSpace( String spaceName, String tsServer, ConfigTuple configuration, String userName, String password )
    13. public TupleSpace( String spaceName, String tsServer, int tsPort )
    14. public TupleSpace( String spaceName, String tsServer, int tsPort, String userName, String password )
    15. public TupleSpace( String spaceName, String tsServer, int tsPort, ConfigTuple configuration)
    16. public TupleSpace( String spaceName, String tsServer, int tsPort, ConfigTuple configuration, String userName, String password )
    17. public TupleSpace( String spaceName, String tsServer, int tsPort, ConfigTuple configuration, Tuple accessPermissions )

    Parameters:

    Exception: 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.

    Usage:

          Example:
          TupleSpace ts = new TupleSpace( "FooSpace", localhost );
          

    Deprecated Commands

    These commands have gone out of style. These include the original Linda commands (in, out) and our poor choice of the scan() and consumingScan() method names -- multiRead() and multiTake() were the obvious name choices and we just missed that.


    scan() (Deprecated)

    Explanation: 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.
    NOTE: scan() is deprecated. Use multiRead() instead.

    Definitions:

    Parameters:

    Return: A Tuple of Tuples. Each Field in the Tuple is a Tuple that matched the template Tuple.

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

          Example:
          

    consumingScan() (Deprecated)

    Explanation: 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.
    NOTE: consumingScan() is deprecated. Use multiTake() instead.

    Definitions:

    Parameters:

    Return: A Tuple of Tuples. Each Field in the Tuple is a Tuple that matched the template Tuple.

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

          Example:
          

    out() (Deprecated)

    Explanation: Add the Tuple to the Tuple Space.
    NOTE: out() is deprecated. Use write() instead.

    Definitions:

    Parameters:

    Return:

    Exception:

    Usage:

          Example:   ts.out( new Tuple("foo", "bar"));
          

    in() (Deprecated)

    Explanation: 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 waitToTake()), we will require that tuples have content (no NULL tuples).
    NOTE: in() is deprecated. Use waitToTake() instead.

    Definitions:

    Parameters:

    Return: the tuple that matched the query template.

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

          Example:
          

    inp() (Deprecated)

    Explanation: Retrieve a tuple from the space that matches a Tuple template. DO NOT BLOCK. Remove the Tuple from the space. For inp() (aka take() ), we will require that tuples have content (no NULL tuples).
    NOTE: inp() is deprecated. Use take() instead.

    Definitions:

    Parameters:

    Return: the tuple that matched the query template.

    Exception: Throws TupleSpaceException if there were problems invoking the command.

    Usage:

          Example:
          

    Other Topics

    There are several other topics we need to cover:

    1. Using The Config File -- what to do with the various options
    2. Running Multiple Servers on the same machine. Warning: Because of the use of static vars in the server, it is not possible to run multiple servers in the SAME JVM. However, it is possible to run multiple servers on the same machine, just in different JVMs. We will expand this section with more detail, but there are at least two points to make:
      1. You must set up different config files. You will notice that in the config files there are settings for checkpoint and logging locations, etc. Each server must have a different set of files or else there will be weird and random confusion, followed by a muffled explosion when one or more servers blow up.
      2. You must have the servers use different ports (not the default 8200).