com.ibm.tspaces
Class Field

java.lang.Object
  |
  +--com.ibm.tspaces.Field
Direct Known Subclasses:
FieldPS, StaleTimestamp, XMLField

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

A Field is a type (Java Class) that may have an associated value (a Java class instance), a Class Type and optionally an associated name.

 
 Definitions:
   Field        - A Field object is an element of a Tuple.  It can have the
      following attributes.
 
      Name:  (String) Name used in indexing and query operations.
      Type:  (Class) Java Class object.  This is either the Class of
                     the value Object that is stored in the Field or the
                     the Class of Objects that this is a wildcard for.
      Value: (Object) Reference to an Object that represents
                     the value of the Field.
     isFormal  Boolean value that is true if the Field is a Formal.
 
   Formal Field  - A "Formal" has only a type. and "no value".
     A Formal Field is only valid in a Query Tuple.  A Field in a Tuple in
     the TupleSpace cannot by definition be a Formal Field.
     Example:
      Field f = new Field(String.class);
 
   Actual Field  - An "Actual" always has a Type and a Value.  The Value
     may be "null". Normally Type is extracted from the Value when setValue
     is called (implicitly or explicitly).  But it can be set independently 
     with thesetType method. :
     The following are equivalent
 
      Field f = new Field("foo");
 
      String foo = "foo";
      Field f = new Field(String.class,foo);
 
      String foo = "foo";
      Field f = new Field();
      f.setType(String.class);
      f.setValue(foo);
       *Note: The specification of String.class in the 2nd and 3rd
       example is required if "foo" may contain a value of null.

 

Author:
Daniel Ford, Toby Lehman, John Thomas
See Also:
SuperTuple, TupleSpace, Serialized Form

Field Summary
protected  boolean isFormal
          The flag to indicate that this Field is formal.
protected  java.lang.String theName
          The name of the Field.
protected  java.lang.Class theType
          The type of the Field, which can be any arbitrary Java Class.
protected  java.lang.String theTypeString
          The named type of the Field, This may be needed at the Server to access the Class definition.
protected  java.io.Serializable theValue
          The value of the Field, which is any arbitrary Java Serializable instance.
 
Constructor Summary
Field(java.lang.Class t)
          Create a Field that has the Class as its type.
Field(java.lang.Class t, java.io.Serializable v)
          Create a Field that has the value Object.
Field(double d_)
          Create a Field for the integral type "double" by wrapping it as a Double.
Field(Field f)
          Create a Field from another Field.
Field(float f_)
          Create a Field for the integral type "float" by wrapping it as a Float.
Field(int i_)
          Create a Field for the integral type "int" by wrapping it as a Integer.
Field(long l_)
          Create a Field for the integral type "long" by wrapping it as a Long.
Field(java.io.Serializable v)
          Create a Field that has the value Object.
Field(java.lang.String name, java.lang.Class t)
          Create a named Field that has the Class as its type.
Field(java.lang.String name, java.lang.Class t, java.io.Serializable v)
          Create a named Field that has the Class as its type and the passed Object as its value.
Field(java.lang.String name, double d_)
          Create a named Field for the integral type "double" by wrapping it as a Double.
Field(java.lang.String name, float f_)
          Create a named Field for the integral type "float" by wrapping it as a Float.
Field(java.lang.String name, int i_)
          Create a named Field for the integral type "int" by wrapping it as a Integer.
Field(java.lang.String name, long l_)
          Create a named Field for the longegral type "long" by wrapping it as a Long.
Field(java.lang.String name, java.io.Serializable v)
          Create a named Field that has the value Serializable.
 
Method Summary
 void assign(Field f)
          Assign the type and value of another Field to this Field.
 java.lang.Object clone()
          Return copy of the Field and its Fields.
 boolean formal()
          Deprecated. Use isFormal()
 java.lang.String getName()
          Return the name of the Field.
 java.lang.Class getType()
          Return the Class instance that represents the type of the Field.
 java.io.Serializable getValue()
          Return the value of the Field.
 boolean isFormal()
          Return true if the Field is "formal", meaning that it only has a type and not a value.
static void main(java.lang.String[] argv)
          Test routine for Field
static Field makeField(java.lang.String className)
          Construct a formal Field instance from the name of a class.
 boolean matches(Field f2)
          This method is used to determine if the specified Field matches the current Field.
 java.lang.String name()
          Deprecated. Use getName()
 void setFormal()
          Deprecated. Use setFormal(true)
 void setFormal(boolean setting)
          Set isFormal to specified value.
 void setName(java.lang.String name)
          Set the name of the Field.
 void setType(java.lang.Class t)
          Set the type of the Field.
 void setValue(java.io.Serializable v)
          Set the value of the Field to be any Serializable.
 java.lang.String toString()
          Return a String that represents the Field.
 java.lang.Class type()
          Deprecated. Use getType()
 java.io.Serializable value()
          Deprecated. Use getValue()
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

theName

protected java.lang.String theName
The name of the Field. A Field name is not mandatory.

theType

protected java.lang.Class theType
The type of the Field, which can be any arbitrary Java Class.

theTypeString

protected java.lang.String theTypeString
The named type of the Field, This may be needed at the Server to access the Class definition.

theValue

protected java.io.Serializable theValue
The value of the Field, which is any arbitrary Java Serializable instance. The value can be null, provided that a Class is specified.

isFormal

protected boolean isFormal
The flag to indicate that this Field is formal. This flag has meaning only when the Field is being used in a SuperTuple template.
Constructor Detail

Field

public Field(java.io.Serializable v)
      throws TupleSpaceException
Create a Field that has the value Object. The type of the Field is the type (Class) of the value.
Parameters:
v - The value of the Field
Throws:
TupleSpaceException - if there is a problem creating the field

Field

public Field(java.lang.Class t,
             java.io.Serializable v)
      throws TupleSpaceException
Create a Field that has the value Object. The Class parameter must be the same as the type of the Object. This method is used for Objects that might be null.
Parameters:
v - The value of the Field
Throws:
TupleSpaceException - if there is a problem creating the field

Field

public Field(java.lang.String name,
             java.lang.Class t,
             java.io.Serializable v)
      throws TupleSpaceException
Create a named Field that has the Class as its type and the passed Object as its value. Used for named Fields with possibly null values.
Parameters:
name - The name of the Field. null is allowed.
t - The type of the Field.
v - The value of the Field. null is allowed.
Throws:
TupleSpaceException - If the type of the class does not match the type of the value.

Field

public Field(java.lang.Class t)
      throws TupleSpaceException
Create a Field that has the Class as its type. The Field does not have a value, this is used to specify a formal Field that can be used in a simple query to match another Field of this type that has any value.
Parameters:
t - The value of the class
Throws:
TupleSpaceException - if there is a problem creating the field

Field

public Field(java.lang.String name,
             java.lang.Class t)
      throws TupleSpaceException
Create a named Field that has the Class as its type. The Field does not have a value, this is used to specify a formal Field that can be used in a simple query to match another Field of this type that has any value.
Parameters:
name - The name of the Field.
t - The type of the Field.
Throws:
TupleSpaceException - if there is a problem creating the field

Field

public Field(java.lang.String name,
             java.io.Serializable v)
      throws TupleSpaceException
Create a named Field that has the value Serializable. The type of the Field is the type (Class) of the value.
Parameters:
name - The name of the Field.
v - The value of the Field.
Throws:
TupleSpaceException - if there is a problem creating the field

Field

public Field(Field f)
Create a Field from another Field.
Parameters:
f - The Field to copy.

Field

public Field(float f_)
      throws TupleSpaceException
Create 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.
Throws:
TupleSpaceException - if there is a problem creating the field
See Also:
Field, Float

Field

public Field(java.lang.String name,
             float f_)
      throws TupleSpaceException
Create 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.
Throws:
TupleSpaceException - if there is a problem creating the field
See Also:
Field, Float

Field

public Field(double d_)
      throws TupleSpaceException
Create 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.
Throws:
TupleSpaceException - if there is a problem creating the field
See Also:
Field, Double

Field

public Field(java.lang.String name,
             double d_)
      throws TupleSpaceException
Create 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.
Throws:
TupleSpaceException - if there is a problem creating the field
See Also:
Field, Double

Field

public Field(int i_)
      throws TupleSpaceException
Create a Field for the integral type "int" by wrapping it as a Integer.
Parameters:
i_ - The int that is the value of the new Field.
Throws:
TupleSpaceException - if there is a problem creating the field
See Also:
Field, Integer

Field

public Field(java.lang.String name,
             int i_)
      throws TupleSpaceException
Create a named Field for the integral type "int" by wrapping it as a Integer.
Parameters:
name - The name of the Field.
i_ - The int that is the value of the new Field.
Throws:
TupleSpaceException - if there is a problem creating the field
See Also:
Field, Integer

Field

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

Field

public Field(java.lang.String name,
             long l_)
      throws TupleSpaceException
Create a named Field for the longegral type "long" by wrapping it as a Long.
Parameters:
name - The name of the Field.
l_ - The long that is the value of the new Field.
Throws:
TupleSpaceException - if there is a problem creating the field
See Also:
Field, Long
Method Detail

setName

public void setName(java.lang.String name)
Set the name of the Field.
Parameters:
name - The new name of the Field.

setType

public void setType(java.lang.Class t)
Set the type of the Field.
Parameters:
t - The new type of the Field.

setValue

public void setValue(java.io.Serializable v)
              throws TupleSpaceException
Set the value of the Field to be any Serializable. The type of the Field is the type (Class) of the value. We will allow the value to be null, only if the Type has been previously set.
Parameters:
v - The value of the Field.
Throws:
TupleSpaceException - if there is a problem creating the field

setFormal

public void setFormal()
Deprecated. Use setFormal(true)

Set this Field to be formal.

setFormal

public void setFormal(boolean setting)
Set isFormal to specified value. If true, then also sets theValue to null.
Parameters:
setting - true is this is to be a Formal field.

assign

public void assign(Field f)
Assign the type and value of another Field to this Field.
Parameters:
f - The Field to be assigned from

name

public java.lang.String name()
Deprecated. Use getName()

Return the name of the Field. A Field is not required to have a name so the return value could be null.
Returns:
A String that is the name of the Field, or null if the Field doesn't have a name..

getName

public java.lang.String getName()
Return the name of the Field. A Field is not required to have a name so the return value could be null.
Returns:
A String that is the name of the Field, or null if the Field doesn't have a name..

type

public java.lang.Class type()
Deprecated. Use getType()

Return the Class instance that represents the type of the Field.
Returns:
A Class instance that represents the type of the Field.

getType

public java.lang.Class getType()
Return the Class instance that represents the type of the Field.
Returns:
A Class instance that represents the type of the Field.

value

public java.io.Serializable value()
Deprecated. Use getValue()

Return the value of the Field.
Returns:
An Serializable instance that is the value of the Field.

getValue

public java.io.Serializable getValue()
Return the value of the Field.
Returns:
An Serializable instance that is the value of the Field.

formal

public boolean formal()
Deprecated. Use isFormal()

Return true if the Field is "formal", meaning that it only has a type and not a value. A formal Field is used to do associative matching and is considered to be equal to any Field of the same type (Class).
Returns:
true if the Field is defined to be Formal .

isFormal

public boolean isFormal()
Return true if the Field is "formal", meaning that it only has a type and not a value. A formal Field is used to do associative matching and is considered to be equal to any Field of the same type (Class).
Returns:
true if the Field is defined to be Formal, false otherwise. ???? add isFormal()

matches

public boolean matches(Field f2)
This method is used to determine if the specified Field matches the current Field. The curent Field may be a Formal Field or an Actual Field.
  
 Rules for Matching:  Field f1.matches(Field f2)

 Rule 1: Field f1 is always the Query Field.
  This makes the matches code a bit more efficient and as discussed later
  solves a problem of what to do if a Formal Field is placed in the database.

 Rule 2 - If f1 is Formal and the type is assignable from the other field
   then return true.
         if f1.isFormal
             if f1 isAsignableFrom(f2) -> true

 Rule 3 - if both f1 and f2 are null and the types match, then return true
   
           if f1 == null && f2 == null && f1.getType()==f2.getType() -> true

 Rule 4 - if f1 == null || f2 == null  -> false

 Rule 5 - if f1 and f2 are SuperTuples then 
          return  f1.getValue().matches(f2.getValue()) 
 
 Rule 6   return  f1.getValue().equals(f2.getValue()) 

 

Override this method to change the matching behavior.

Parameters:
f2 - The Field to compare against.
Returns:
true if the two Fields match, false otherwise.

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException
Return copy of the Field and its Fields. If _theValue is not cloneable, it will throw an exception.
Overrides:
clone in class java.lang.Object
Returns:
A copy of the Field Object.

toString

public java.lang.String toString()
Return a String that represents the Field. If the Field does not have a value then return the name of the Class that is the type of the Field. If the Field does have a value then return the string representation of the value of the Field.
Overrides:
toString in class java.lang.Object
Returns:
A String that represents the Field.

makeField

public static Field makeField(java.lang.String className)
                       throws TupleSpaceException
Construct a formal Field instance from the name of a class.

Example: Field f = Field.makeField("java.util.Vector");

An alternative is:
Field f = new Field(Vector.class);

Parameters:
className - the name of the class that is the type of the Field.
Returns:
A formal Field whose type is the named class.
Throws:
TupleSpaceException - if the named class is invalid or cannot be found.

main

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