package prefuse.data;
import java.util.Date;
/**
* Tuples are objects representing a row of a data table, providing
* a simplified interface to table data. They maintain a pointer to a
* corresponding row in a table. When rows are deleted, any live Tuples
* for that row become invalidated, and any further attempts to access
* or set data with that Tuple will result in an exception.
*
* @author jeffrey heer
*/
public interface Tuple {
/**
* Returns the schema for this tuple's data.
* @return the Tuple Schema
*/
public Schema getSchema();
/**
* Returns the Table instance that backs this Tuple, if it exists.
* @return the backing Table, or null if there is none.
*/
public Table getTable();
/**
* Returns the row index for this Tuple's backing Table, if it exists.
* @return the backing row index, or -1 if there is no backing table
* or if this Tuple has been invalidated (i.e., the Tuple's row was
* deleted from the backing table).
*/
public int getRow();
/**
* Indicates if this Tuple is valid. Trying to get or set values on an
* invalid Tuple will result in a runtime exception.
* @return true if this Tuple is valid, false otherwise
*/
public boolean isValid();
// ------------------------------------------------------------------------
// Column Methods
/**
* Returns the data type of the given field as a Java Class instance.
* @param field the data field
* @return the data type of the field, a Class instance indicating the
* top-level type of data values in this field.
*/
public Class getColumnType(String field);
/**
* Returns the data type of the given column as a Java Class instance.
* @param col the column index
* @return the data type of the column, a Class instance indicating the
* top-level type of data values in this field.
*/
public Class getColumnType(int col);
/**
* Get the column index corresponding to the given data field.
* @param field the data field to look up
* @return the column index of the field within the backing table, or
* -1 if no columns with the given name were found
*/
public int getColumnIndex(String field);
/**
* Get the number of columns maintained by the backing table.
* @return the number of columns / data fields.
*/
public int getColumnCount();
/**
* Get the data field name of the column at the given index.
* @param col the column index to look up
* @return the data field name of the given column index
*/
public String getColumnName(int col);
// ------------------------------------------------------------------------
// Data Access Methods
/**
* Check if the get
method for the given data field returns
* values that are compatible with a given target type.
* @param field the data field to check
* @param type a Class instance to check for compatibility with the
* data field values.
* @return true if the data field is compatible with provided type,
* false otherwise. If the value is true, objects returned by
* the {@link #get(String)} can be cast to the given type.
* @see #get(String)
*/
public boolean canGet(String field, Class type);
/**
* Check if the set
method for the given data field can
* accept values of a given target type.
* @param field the data field to check
* @param type a Class instance to check for compatibility with the
* data field values.
* @return true if the data field is compatible with provided type,
* false otherwise. If the value is true, objects of the given type
* can be used as parameters of the {@link #set(String, Object)} method.
* @see #set(String, Object)
*/
public boolean canSet(String field, Class type);
/**
* Get the data value at the given field as an Object.
* @param field the data field to retrieve
* @return the data value as an Object. The concrete type of this
* Object is dependent on the underlying data column used.
* @see #canGet(String, Class)
* @see #getColumnType(String)
*/
public Object get(String field);
/**
* Set the value of a given data field.
* @param field the data field to set
* @param value the value for the field. If the concrete type of this
* Object is not compatible with the underlying data model, an
* Exception will be thrown. Use the {@link #canSet(String, Class)}
* method to check the type-safety ahead of time.
* @see #canSet(String, Class)
* @see #getColumnType(String)
*/
public void set(String field, Object value);
/**
* Get the data value at the given column number as an Object.
* @param col the column number
* @return the data value as an Object. The concrete type of this
* Object is dependent on the underlying data column used.
* @see #canGet(String, Class)
* @see #getColumnType(int)
*/
public Object getValueAt(int col);
/**
* Set the value of at the given column number.
* @param col the column number
* @param value the value for the field. If the concrete type of this
* Object is not compatible with the underlying data model, an
* Exception will be thrown. Use the {@link #canSet(String, Class)}
* method to check the type-safety ahead of time.
* @see #canSet(String, Class)
* @see #getColumnType(String)
*/
public void setValueAt(int col, Object value);
/**
* Get the default value for the given data field.
* @param field the data field
* @return the default value, as an Object, used to populate rows
* of the data field.
*/
public Object getDefault(String field);
/**
* Revert this tuple's value for the given field to the default value
* for the field.
* @param field the data field
* @see #getDefault(String)
*/
public void revertToDefault(String field);
// ------------------------------------------------------------------------
// Convenience Data Access Methods
/**
* Check if the given data field can return primitive int
* values.
* @param field the data field to check
* @return true if the data field can return primitive int
* values, false otherwise. If true, the {@link #getInt(String)} method
* can be used safely.
*/
public boolean canGetInt(String field);
/**
* Check if the setInt
method can safely be used for the
* given data field.
* @param field the data field to check
* @return true if the {@link #setInt(String, int)} method can safely
* be used for the given field, false otherwise.
*/
public boolean canSetInt(String field);
/**
* Get the data value at the given field as an int
.
* @param field the data field to retrieve
* @see #canGetInt(String)
*/
public int getInt(String field);
/**
* Set the data value of the given field with an int
.
* @param field the data field to set
* @param val the value to set
* @see #canSetInt(String)
*/
public void setInt(String field, int val);
// --------------------------------------------------------------
/**
* Check if the given data field can return primitive long
* values.
* @param field the data field to check
* @return true if the data field can return primitive long
* values, false otherwise. If true, the {@link #getLong(String)} method
* can be used safely.
*/
public boolean canGetLong(String field);
/**
* Check if the setLong
method can safely be used for the
* given data field.
* @param field the data field to check
* @return true if the {@link #setLong(String, long)} method can safely
* be used for the given field, false otherwise.
*/
public boolean canSetLong(String field);
/**
* Get the data value at the given field as a long
.
* @param field the data field to retrieve
* @see #canGetLong(String)
*/
public long getLong(String field);
/**
* Set the data value of the given field with a long
.
* @param field the data field to set
* @param val the value to set
* @see #canSetLong(String)
*/
public void setLong(String field, long val);
// --------------------------------------------------------------
/**
* Check if the given data field can return primitive float
* values.
* @param field the data field to check
* @return true if the data field can return primitive float
* values, false otherwise. If true, the {@link #getFloat(String)} method
* can be used safely.
*/
public boolean canGetFloat(String field);
/**
* Check if the setFloat
method can safely be used for the
* given data field.
* @param field the data field to check
* @return true if the {@link #setFloat(String, float)} method can safely
* be used for the given field, false otherwise.
*/
public boolean canSetFloat(String field);
/**
* Get the data value at the given field as a float
.
* @param field the data field to retrieve
* @see #canGetFloat(String)
*/
public float getFloat(String field);
/**
* Set the data value of the given field with a float
.
* @param field the data field to set
* @param val the value to set
* @see #canSetFloat(String)
*/
public void setFloat(String field, float val);
// --------------------------------------------------------------
/**
* Check if the given data field can return primitive double
* values.
* @param field the data field to check
* @return true if the data field can return primitive double
* values, false otherwise. If true, the {@link #getDouble(String)} method
* can be used safely.
*/
public boolean canGetDouble(String field);
/**
* Check if the setDouble
method can safely be used for the
* given data field.
* @param field the data field to check
* @return true if the {@link #setDouble(String, double)} method can safely
* be used for the given field, false otherwise.
*/
public boolean canSetDouble(String field);
/**
* Get the data value at the given field as a double
.
* @param field the data field to retrieve
* @see #canGetDouble(String)
*/
public double getDouble(String field);
/**
* Set the data value of the given field with a double
.
* @param field the data field to set
* @param val the value to set
* @see #canSetDouble(String)
*/
public void setDouble(String field, double val);
// --------------------------------------------------------------
/**
* Check if the given data field can return primitive boolean
* values.
* @param field the data field to check
* @return true if the data field can return primitive boolean
* values, false otherwise. If true, the {@link #getBoolean(String)} method
* can be used safely.
*/
public boolean canGetBoolean(String field);
/**
* Check if the setBoolean
method can safely be used for the
* given data field.
* @param field the data field to check
* @return true if the {@link #setBoolean(String, boolean)} method can
* safely be used for the given field, false otherwise.
*/
public boolean canSetBoolean(String field);
/**
* Get the data value at the given field as a boolean
.
* @param field the data field to retrieve
* @see #canGetBoolean(String)
*/
public boolean getBoolean(String field);
/**
* Set the data value of the given field with a boolean
.
* @param field the data field to set
* @param val the value to set
* @see #canSetBoolean(String)
*/
public void setBoolean(String field, boolean val);
// --------------------------------------------------------------
/**
* Check if the given data field can return String
* values.
* @param field the data field to check
* @return true if the data field can return String
* values, false otherwise. If true, the {@link #getString(String)} method
* can be used safely.
*/
public boolean canGetString(String field);
/**
* Check if the setString
method can safely be used for the
* given data field.
* @param field the data field to check
* @return true if the {@link #setString(String, String)} method can safely
* be used for the given field, false otherwise.
*/
public boolean canSetString(String field);
/**
* Get the data value at the given field as a String
.
* @param field the data field to retrieve
* @see #canGetString(String)
*/
public String getString(String field);
/**
* Set the data value of the given field with a String
.
* @param field the data field to set
* @param val the value to set
* @see #canSetString(String)
*/
public void setString(String field, String val);
// --------------------------------------------------------------
/**
* Check if the given data field can return Date
* values.
* @param field the data field to check
* @return true if the data field can return Date
* values, false otherwise. If true, the {@link #getDate(String)} method
* can be used safely.
*/
public boolean canGetDate(String field);
/**
* Check if the setDate
method can safely be used for the
* given data field.
* @param field the data field to check
* @return true if the {@link #setDate(String, Date)} method can safely
* be used for the given field, false otherwise.
*/
public boolean canSetDate(String field);
/**
* Get the data value at the given field as a Date
.
* @param field the data field to retrieve
* @see #canGetDate(String)
*/
public Date getDate(String field);
/**
* Set the data value of the given field with a Date
.
* @param field the data field to set
* @param val the value to set
* @see #canSetDate(String)
*/
public void setDate(String field, Date val);
} // end of interface Tuple