com.ibm.tspaces
Class SuperTuple

java.lang.Object
  |
  +--com.ibm.tspaces.SuperTuple
Direct Known Subclasses:
SubclassableTuple, Tuple

public abstract class SuperTuple
extends java.lang.Object
implements java.io.Serializable, java.lang.Cloneable

A SuperTuple is an ordered sequence of Fields. Since it's abstract, any SuperTuple is actually either a Tuple or a SubclassableTuple.

Refer to the SuperTuple.matches() method for the matching algorithm for Tuples

Template Tuples:
Normally Tuples contain "Actual Fields that contain data and these Tuples are written to and taken from TupleSpaces.

But we also have Template Tuples that are used for matching Tuples to be retrieved. These Template Tuples have zero or more "Formal" Fields that contains only the class of the value that is to be matched.

 For Example:
    Tuple template = new Tuple("Key1",new Field(String.class));
 
The above would match any Tuple that contained "Key1" in the 1st Field and any String value in the 2nd and final Field.

We have defined a "Null Tuple" as a wildcard that matches all Tuples. A "Null Tuple" is a SuperTuple with no fields, not a null reference to a SuperTuple.
For Example: Tuple nullTuple = new Tuple();
Since Formal Fields match the class and any subclass, new Field(Serializable.class) can act as a wildcard for any one of the fields.

Another Example:

       TupleSpace ts = new TupleSpace("test");
       Tuple tuple = new Tuple("Key1","Data1");
       ts.write(tuple);
  
       Tuple template = new Tuple("Key1",new Field(String.class));
       Tuple result = ts.take(template);
       String data = rusult.getField(1).getValue();
 

Author:
Daniel Ford, Tobin Lehman, Stephen McLaughry, Peter Wyckoff, Ben Y. Zhao
See Also:
Tuple, SubclassableTuple, Field, TupleSpace, Serialized Form

Constructor Summary
SuperTuple()
          The default SuperTuple constructor.
SuperTuple(java.io.Serializable obj)
          Make a Tuple whose Field is the type and value of an Object.
SuperTuple(java.io.Serializable obj1, java.io.Serializable obj2)
          Make a SuperTuple whose Fields are the type and value of Objects.
SuperTuple(java.io.Serializable obj1, java.io.Serializable obj2, java.io.Serializable obj3)
          Make a SuperTuple whose Fields are the type and value of Objects.
SuperTuple(java.io.Serializable obj1, java.io.Serializable obj2, java.io.Serializable obj3, java.io.Serializable obj4)
          Make a SuperTuple whose Fields are the type and value of Objects.
SuperTuple(java.io.Serializable obj1, java.io.Serializable obj2, java.io.Serializable obj3, java.io.Serializable obj4, java.io.Serializable obj5)
          Make a SuperTuple whose Fields are the type and value of Objects.
SuperTuple(java.io.Serializable obj1, java.io.Serializable obj2, java.io.Serializable obj3, java.io.Serializable obj4, java.io.Serializable obj5, java.io.Serializable obj6)
          Make a SuperTuple whose Fields are the type and value of Objects.
SuperTuple(java.io.Serializable obj1, java.io.Serializable obj2, java.io.Serializable obj3, java.io.Serializable obj4, java.io.Serializable obj5, java.io.Serializable obj6, java.io.Serializable obj7)
          Make a SuperTuple whose Fields are the type and value of Objects.
 
Method Summary
 void add(java.lang.Class class_)
          Add a Field with the Class as its type (this is a "Formal" Field).
 void add(double d_)
          Add a Field for the integral type "double" by wrapping it as a Double.
 void add(Field f_)
          Add a Field to the SuperTuple.
 void add(float f_)
          Add a Field for the integral type "float" by wrapping it as a Float.
 void add(int i_)
          Add a Field for the integral type "int" by wrapping it as an Integer.
 void add(long l_)
          Add a Field for the integral type "long" by wrapping it as an Long.
 void add(java.io.Serializable obj_)
          Add a Field with the Object as its value.
 void add(java.lang.String value_)
          Add a String Field to the Tuple.
 void add(java.lang.String name, java.lang.Class t)
          Add a named Field with the Class as its type (this is a "Formal" Field).
 void add(java.lang.String name, double d_)
          Add a named Field for the integral type "double" by wrapping it as a Double.
 void add(java.lang.String name, float f_)
          Add a named Field for the integral type "float" by wrapping it as a Float.
 void add(java.lang.String name, int i_)
          Add a named Field for the integral type "int" by wrapping it as an Integer.
 void add(java.lang.String name, long l_)
          Add a Field for the integral type "long" by wrapping it as an Long.
 void add(java.lang.String name, java.io.Serializable obj_)
          Add a named Field with the Object as its value.
 void add(java.lang.String name, java.lang.String value_)
          Add a named String Field Tuple
 void addFieldType(int orValue)
           
 void changeName(java.lang.String oldName, java.lang.String newName)
          Change the name of the named field.
 java.lang.Object clone()
          Return a clone of the this SuperTuple.
 boolean equals(java.lang.Object t_)
          Return true if the specified Tuple is equal to this Tuple.
 boolean fieldExists(java.lang.String name)
          Return true if the named Field exists in the Tuple.
 java.util.Enumeration fields()
          Return an enumeration of the Fields in the Tuple.
 long getExpire()
          Get the Expire time interval (ms) of the Tuple
 Field getField(int i)
          Return the i'th Field in the Tuple.
 Field getField(java.lang.String name)
          Return a named Field in the Tuple.
 int getFieldType()
           
 long getTimeStamp()
          Get the timeStamp of when the Tuple was written into the TupleSpace on the server.
 TupleID getTupleID()
          The UniqueId for a SuperTuple
 boolean isExpired()
          Return true if the current time is greater than the Tuple (_timeStamp + _expire) Normally this should only be done by the server since the _timestamp is set by the server and the client and server clocks may not be in sync.
 boolean matches(SuperTuple t_)
          Return true if the specified Tuple matches this Tuple.
 int numberOfFields()
          Return the number of fields in the Tuple.
 void putField(int i, Field f)
          Insert the specified Field at the indicated position i.
 void setExpire(long time)
          Set the _expire value.
 void setField(int i, Field f)
          replace the specified Field at the indicated position i.
protected  void setFields(java.util.Vector fields)
          Reset the Vector that contains the Fields Used to clone the SuperTuple Since clients should not be aware of this Vector this must be a protected field.
 void setFormal(int i)
          Deprecated. Use the form setFormal(i,true)
 void setFormal(int i, boolean setting)
          Set the indexed Field to the specified formal setting
 void setFormal(java.lang.String name)
          Deprecated. Use the form setFormal(name,true)
 void setFormal(java.lang.String name, boolean setting)
          Set the named Field to the specified formal setting
 void setName(int i, java.lang.String name)
          Set the name of the indexed Field.
 void setTimeStamp(long time)
          Set the TimeStamp value.
 void setTupleID(TupleID id)
          Assign to the unique id.
 void setType(int i, java.lang.Class t)
          Set the type of a indexed field to the specified Class.
 void setType(java.lang.String name, java.lang.Class t)
          Set the type of a named field to the Specified Class.
 void setValue(int i, java.io.Serializable v)
          Set the value of a field to the Object passed.
 void setValue(java.lang.String name, java.io.Serializable v)
          Set the value of a named field to the Object passed.
 java.lang.String structureName()
          Return a string representation of the Tuple's structure.
 boolean template()
          Deprecated. Since we no longer differentiate between "formal" and "actual" tuples, this is no longer useful.
 java.lang.String toString()
          Return a string representation of the Tuple.
 
Methods inherited from class java.lang.Object
finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

SuperTuple

public SuperTuple()
The default SuperTuple constructor. Constructs a NULL SuperTuple, one with no Fields. Subsequent Fields can be added with the "add" method.
See Also:
add(com.ibm.tspaces.Field)

SuperTuple

public SuperTuple(java.io.Serializable obj)
           throws TupleSpaceException
Make a Tuple whose Field is the type and value of an Object. If the object itself is a Field, then it will be used as the Field and not as the Field's value.
Parameters:
obj - the value of the first Field of the Tuple.

SuperTuple

public SuperTuple(java.io.Serializable obj1,
                  java.io.Serializable obj2)
           throws TupleSpaceException
Make a SuperTuple whose Fields are the type and value of Objects. If any object itself is a Field, then it will be used as the Field and not as the Field's value.
Parameters:
obj1 - the value of the first field of the SuperTuple.
obj2 - the value of the second field of the SuperTuple.

SuperTuple

public SuperTuple(java.io.Serializable obj1,
                  java.io.Serializable obj2,
                  java.io.Serializable obj3)
           throws TupleSpaceException
Make a SuperTuple whose Fields are the type and value of Objects. If any object itself is a Field, then it will be used as the Field and not as the Field's value.
Parameters:
obj1 - the value of the first field of the SuperTuple.
obj2 - the value of the second field of the SuperTuple.
obj3 - the value of the third field of the SuperTuple.

SuperTuple

public SuperTuple(java.io.Serializable obj1,
                  java.io.Serializable obj2,
                  java.io.Serializable obj3,
                  java.io.Serializable obj4)
           throws TupleSpaceException
Make a SuperTuple whose Fields are the type and value of Objects. If any object itself is a Field, then it will be used as the Field and not as the Field's value.
Parameters:
obj1 - the value of the first field of the SuperTuple.
obj2 - the value of the second field of the SuperTuple.
obj3 - the value of the third field of the SuperTuple.
obj4 - the value of the fourth field of the SuperTuple.

SuperTuple

public SuperTuple(java.io.Serializable obj1,
                  java.io.Serializable obj2,
                  java.io.Serializable obj3,
                  java.io.Serializable obj4,
                  java.io.Serializable obj5)
           throws TupleSpaceException
Make a SuperTuple whose Fields are the type and value of Objects. If any object itself is a Field, then it will be used as the Field and not as the Field's value.
Parameters:
obj1 - the value of the first field of the SuperTuple.
obj2 - the value of the second field of the SuperTuple.
obj3 - the value of the third field of the SuperTuple.
obj4 - the value of the fourth field of the SuperTuple.
obj5 - the value of the fifth field of the SuperTuple.

SuperTuple

public SuperTuple(java.io.Serializable obj1,
                  java.io.Serializable obj2,
                  java.io.Serializable obj3,
                  java.io.Serializable obj4,
                  java.io.Serializable obj5,
                  java.io.Serializable obj6)
           throws TupleSpaceException
Make a SuperTuple whose Fields are the type and value of Objects. If any object itself is a Field, then it will be used as the Field and not as the Field's value.
Parameters:
obj1 - the value of the first field of the SuperTuple.
obj2 - the value of the second field of the SuperTuple.
obj3 - the value of the third field of the SuperTuple.
obj4 - the value of the fourth field of the SuperTuple.
obj5 - the value of the fifth field of the SuperTuple.
obj6 - the value of the sixth field of the SuperTuple.

SuperTuple

public SuperTuple(java.io.Serializable obj1,
                  java.io.Serializable obj2,
                  java.io.Serializable obj3,
                  java.io.Serializable obj4,
                  java.io.Serializable obj5,
                  java.io.Serializable obj6,
                  java.io.Serializable obj7)
           throws TupleSpaceException
Make a SuperTuple whose Fields are the type and value of Objects. If any object itself is a Field, then it will be used as the Field and not as the Field's value.
Parameters:
obj1 - the value of the first field of the SuperTuple.
obj2 - the value of the second field of the SuperTuple.
obj3 - the value of the third field of the SuperTuple.
obj4 - the value of the fourth field of the SuperTuple.
obj5 - the value of the fifth field of the SuperTuple.
obj6 - the value of the sixth field of the SuperTuple.
obj7 - the value of the seventh field of the SuperTuple.
Method Detail

addFieldType

public void addFieldType(int orValue)

getFieldType

public int getFieldType()

add

public void add(Field f_)
Add a Field to the SuperTuple. It is added to the "end" of the collection of the other Fields.
Parameters:
f_ - The Field to be added to the SuperTuple.

add

public void add(java.lang.Class class_)
         throws TupleSpaceException
Add a Field with the Class as its type (this is a "Formal" Field).
Parameters:
class_ - The type of the Field.
See Also:
Field, Field.formal(), Class

add

public void add(java.lang.String name,
                java.lang.Class t)
         throws TupleSpaceException
Add a named Field with the Class as its type (this is a "Formal" Field).
Parameters:
name - The name of the Field.
t - The type of the Field.
See Also:
Field, Field.formal(), Class

add

public void add(java.io.Serializable obj_)
         throws TupleSpaceException
Add a Field with the Object as its value. The type of the Field will be the Class of the Object.
Parameters:
obj_ - The Object that is value of the new Field.
See Also:
Field

add

public void add(java.lang.String name,
                java.io.Serializable obj_)
         throws TupleSpaceException
Add a named Field with the Object as its value. The type of the Field will be the Class of the Object.
Parameters:
name - The name of the Field.
obj_ - The Object that is value of the new Field.
See Also:
Field

add

public void add(java.lang.String value_)
         throws TupleSpaceException
Add a String Field to the Tuple.
Parameters:
value_ - A String that will be the value of the first Field of the Tuple.

add

public void add(java.lang.String name,
                java.lang.String value_)
         throws TupleSpaceException
Add a named String Field Tuple
Parameters:
name - The name of the Field.
value_ - A String that will be the value of the first Field of the Tuple.

add

public void add(int i_)
         throws TupleSpaceException
Add a Field for the integral type "int" by wrapping it as an Integer.
Parameters:
i_ - The integer that is the value of the value of the Field in
See Also:
Field, Integer

add

public void add(java.lang.String name,
                int i_)
         throws TupleSpaceException
Add a named Field for the integral type "int" by wrapping it as an Integer.
Parameters:
name - The name of the Field.
i_ - The integer that is the value of the value of the Field in
See Also:
Field, Integer

add

public void add(long l_)
         throws TupleSpaceException
Add a Field for the integral type "long" by wrapping it as an Long.
Parameters:
l_ - The long that is the value of of the new Field in the Tuple.
Throws:
TupleSpaceException - if there is a problem creating the fields
See Also:
Field, Long

add

public void add(java.lang.String name,
                long l_)
         throws TupleSpaceException
Add a Field for the integral type "long" by wrapping it as an Long.
Parameters:
name - The name of the Field.
l_ - The long that is the value of of the new Field in the Tuple.
Throws:
TupleSpaceException - if there is a problem creating the fields
See Also:
Field, Long

add

public void add(double d_)
         throws TupleSpaceException
Add a Field for the integral type "double" by wrapping it as a Double.
Parameters:
d_ - The double that is the value of the new Field of the Tuple
Throws:
TupleSpaceException - if there is a problem creating the fields
See Also:
Field, Double

add

public void add(java.lang.String name,
                double d_)
         throws TupleSpaceException
Add a named Field for the integral type "double" by wrapping it as a Double.
Parameters:
name - The name of the Field.
d_ - The double that is the value of the new Field of the Tuple
Throws:
TupleSpaceException - if there is a problem creating the fields
See Also:
Field, Double

add

public void add(float f_)
         throws TupleSpaceException
Add a Field for the integral type "float" by wrapping it as a Float.
Parameters:
f_ - The float that is the value of the new Field of the Tuple.
Throws:
TupleSpaceException - if there is a problem creating the fields
See Also:
Field, Float

add

public void add(java.lang.String name,
                float f_)
         throws TupleSpaceException
Add a named Field for the integral type "float" by wrapping it as a Float.
Parameters:
name - The name of the Field.
f_ - The float that is the value of the new Field of the Tuple.
Throws:
TupleSpaceException - if there is a problem creating the fields
See Also:
Field, Float

setType

public void setType(java.lang.String name,
                    java.lang.Class t)
             throws TupleSpaceException
Set the type of a named field to the Specified Class.
Parameters:
name - The name of the Field.
t - The new type of the field.
Throws:
TupleSpaceException - If no Field in the Tuple exists with the given name.
TupleSpaceException - if there is a problem creating the fields
See Also:
Field

setType

public void setType(int i,
                    java.lang.Class t)
             throws TupleSpaceException
Set the type of a indexed field to the specified Class.
Parameters:
name - The name of the Field.
t - The new type of the field.
Throws:
TupleSpaceException - If no Field in the Tuple exists with the given name.
TupleSpaceException - if there is a problem creating the fields
See Also:
Field

setValue

public void setValue(java.lang.String name,
                     java.io.Serializable v)
              throws TupleSpaceException
Set the value of a named field to the Object passed. The value of the Field is the Class of the Object.
Parameters:
name - The name of the Field.
v - The new value of the field.
Throws:
TupleSpaceException - If no Field in the Tuple exists with the given name.
TupleSpaceException - if there is a problem creating the fields
See Also:
Field

setValue

public void setValue(int i,
                     java.io.Serializable v)
              throws TupleSpaceException
Set the value of a field to the Object passed. The value of the Field is the Class of the Object.
Parameters:
i - The # of the Field.
v - The new value of the field.
Throws:
TupleSpaceException - If no Field in the Tuple exists with the given name.
TupleSpaceException - if there is a problem creating the fields
See Also:
Field

setName

public void setName(int i,
                    java.lang.String name)
             throws TupleSpaceException
Set the name of the indexed Field.
Parameters:
name - The new name of the Field.
i - The index of the field.
Throws:
TupleSpaceException - If no Field at position i of the Tuple..
TupleSpaceException - if there is a problem creating the fields
See Also:
Field

setFormal

public void setFormal(int i,
                      boolean setting)
               throws TupleSpaceException
Set the indexed Field to the specified formal setting
Parameters:
i - The index of the field.
Throws:
TupleSpaceException - If no Field at position i of the Tuple..
TupleSpaceException - if there is a problem creating the fields
See Also:
Field

setFormal

public void setFormal(int i)
               throws TupleSpaceException
Deprecated. Use the form setFormal(i,true)

Set the indexed Field to be formal
Parameters:
i - The index of the field.
Throws:
TupleSpaceException - If no Field at position i of the Tuple..
TupleSpaceException - if there is a problem creating the fields
See Also:
Field

setFormal

public void setFormal(java.lang.String name,
                      boolean setting)
               throws TupleSpaceException
Set the named Field to the specified formal setting
Parameters:
name - The name of the Field.
Throws:
TupleSpaceException - If no Field at position i of the Tuple..
TupleSpaceException - if there is a problem creating the fields
See Also:
Field

setFormal

public void setFormal(java.lang.String name)
               throws TupleSpaceException
Deprecated. Use the form setFormal(name,true)

Set the named Field to be formal
Parameters:
name - The name of the Field.
Throws:
TupleSpaceException - If no Field at position i of the Tuple..
TupleSpaceException - if there is a problem creating the fields
See Also:
Field

changeName

public void changeName(java.lang.String oldName,
                       java.lang.String newName)
                throws TupleSpaceException
Change the name of the named field.
Parameters:
oldName - The old name of the Field.
newName - The new name of the Field.
Throws:
TupleSpaceException - If no Field in the Tuple exists with the given name.
TupleSpaceException - if there is a problem creating the fields
See Also:
Field

setField

public void setField(int i,
                     Field f)
              throws TupleSpaceException
replace the specified Field at the indicated position i.
Parameters:
f - The new Field.
i - The position in the Tuple for the new Field.
Throws:
TupleSpaceException - If no Field at position i of the Tuple..
See Also:
Field

putField

public void putField(int i,
                     Field f)
              throws TupleSpaceException
Insert the specified Field at the indicated position i.
Parameters:
f - The new Field.
i - The position in the Tuple for the new Field.
Throws:
TupleSpaceException - If no Field at position i -1 of the Tuple..
See Also:
Field

getField

public Field getField(int i)
               throws TupleSpaceException
Return the i'th Field in the Tuple.
Parameters:
i - The position of the Field in the Tuple
Returns:
The Field at position i.
Throws:
TupleSpaceException - If no Field at position i of the Tuple.
TupleSpaceException - if there is a problem creating the fields
See Also:
Field

getField

public Field getField(java.lang.String name)
               throws TupleSpaceException
Return a named Field in the Tuple.
Parameters:
name - The name of the Field in the Tuple.
Returns:
The named Field.
Throws:
TupleSpaceException - If no Field in the Tuple exists with the given name.
TupleSpaceException - if there is a problem creating the fields
See Also:
Field

fields

public java.util.Enumeration fields()
Return an enumeration of the Fields in the Tuple.
Returns:
An Enumeration.
See Also:
Field

numberOfFields

public int numberOfFields()
Return the number of fields in the Tuple.
Returns:
The number of Fields in the Tuple.
See Also:
Field

getTupleID

public TupleID getTupleID()
The UniqueId for a SuperTuple
Returns:
the unique id assigned to this tuple by its TSDB

setTupleID

public void setTupleID(TupleID id)
Assign to the unique id. Should only be called by TSDB on an insert

getTimeStamp

public long getTimeStamp()
Get the timeStamp of when the Tuple was written into the TupleSpace on the server. Only Tuples that are returned from the server will contain a Timestamp.
Returns:
long timeStamp

setTimeStamp

public void setTimeStamp(long time)
Set the TimeStamp value. Should only be called by TSDB on an insert. If the client sets this field the results are unpredictable.
Parameters:
time - The current time (from new Date.getTime();)

getExpire

public long getExpire()
Get the Expire time interval (ms) of the Tuple
Returns:
long Expire

setExpire

public void setExpire(long time)
Set the _expire value. Normally the client would set this value if it is desired to expire this Tuple at some point. The default is for _expire to be set to 0 and never expire the Tuple
Parameters:
time - The current time (from new Date.getTime();)

isExpired

public boolean isExpired()
Return true if the current time is greater than the Tuple (_timeStamp + _expire) Normally this should only be done by the server since the _timestamp is set by the server and the client and server clocks may not be in sync.
Returns:
true if currentTime > (_timeStamp + _expire)

matches

public boolean matches(SuperTuple t_)
Return true if the specified Tuple matches this Tuple. It is important to note that when matching a template tuple against the tuples in a TupleSpace, the current Tuple must be the template tuple. I.e. t1.matches(t2); t1 must be the template tuple.
 The match criteria is:
 
 If this class is not an instance of the target class 
   return false
 
 We have defined a template Tuple with no fields as a wildcard that 
 matches everything.  Tuple t0 = new Tuple();
 If this tuple has 0 fields 
   return true

 If the number of fields do not match
   return false

 if the Field.matches() method for each field returns true 
   return true

 else 
    return false
 
Parameters:
t_ - The SuperTuple to compare.
Returns:
true if the SuperTuples are equal, false otherwise.
See Also:
Field

equals

public boolean equals(java.lang.Object t_)
Return true if the specified Tuple is equal to this Tuple. This is different than matches because we don't support a wildcard tuple.
Overrides:
equals in class java.lang.Object
Parameters:
t_ - The SuperTuple to compare.
Returns:
true if the Tuples are equal, false otherwise.
See Also:
Object.equals(java.lang.Object)

template

public boolean template()
Deprecated. Since we no longer differentiate between "formal" and "actual" tuples, this is no longer useful.

Return true if the Tuple is a template. A Tuple is a template if it has at least one formal Field.
Returns:
true if the Tuple has at least one formal Field

fieldExists

public boolean fieldExists(java.lang.String name)
Return true if the named Field exists in the Tuple.
Parameters:
name - The name of the Field to look for.
Returns:
true if the Tuple has a Field with the passed name.

structureName

public java.lang.String structureName()
Return a string representation of the Tuple's structure.
Returns:
String representation of the Tuple's structure.

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException
Return a clone of the this SuperTuple. This will first check for a SuperTuple that contains Fields with only "simple" cloneable objects and will clone it by simply calling the clone methods for the fields.

If the SuperTuple contains objects that are not: String or extends Number or Boolean then convert SuperTuple to a byte array that contains the serialized version of the object then convert it back to a SuperTuple. This is the equivalent of a deep copy

Overrides:
clone in class java.lang.Object
Returns:
clone of the SuperTuple Object.

setFields

protected void setFields(java.util.Vector fields)
Reset the Vector that contains the Fields Used to clone the SuperTuple Since clients should not be aware of this Vector this must be a protected field.
Parameters:
fields - Vector that holds the Fields

toString

public java.lang.String toString()
Return a string representation of the Tuple.
Overrides:
toString in class java.lang.Object
Returns:
String representation of the Tuple.