org.cytoscape.model
Interface CyTable

All Superinterfaces:

CyIdentifiable

public interface CyTable
extends CyIdentifiable

A simple representation of a table object consisting of rows and columns. Columns have names and specific types and rows contain the data for a specific primary key. Tables are limited in the types of data that may be stored. The allowable types are: String, Integer, Long, Double, Boolean, and Lists of those five types.

Cytoscape Backwards Compatibility (API Interface): We expect that this interface will be used but not implemented by developers using this interface. As such, we reserve the right to add methods to the interface as part of minor version upgrades. We will not remove methods for any changes other than major version upgrades.

Nested Class Summary

static class

CyTable.Mutability Mutability of the table specifies whether or not it is able to be deleted..

Field Summary

Fields inherited from interface org.cytoscape.model.CyIdentifiable

SUID

Method Summary

String	addVirtualColumn(String virtualColumn, String sourceColumn, CyTable sourceTable, String targetJoinKey, boolean isImmutable) Adds a "virtual" column to the the current table.
void	addVirtualColumns(CyTable sourceTable, String targetJoinKey, boolean isImmutable) Adds all columns in another table as "virtual" columns to the the current table.
int	countMatchingRows(String columnName, Object value) Returns the number of rows with the in the specified column with the specified value.
<T> void	createColumn(String columnName, Class<? extends T> type, boolean isImmutable) Create a column of the specified name and the specified type.
<T> void	createColumn(String columnName, Class<? extends T> type, boolean isImmutable, T defaultValue) Create a column of the specified name and the specified type.
<T> void	createListColumn(String columnName, Class<T> listElementType, boolean isImmutable) Create a column of Lists with the specified name and the specified element type.
<T> void	createListColumn(String columnName, Class<T> listElementType, boolean isImmutable, List<T> defaultValue) Create a column of Lists with the specified name and the specified element type.
void	deleteColumn(String columnName) Will delete the column of the specified name.
boolean	deleteRows(Collection<?> primaryKeys) Deletes the rows corresponding to the given primary keys and returns true if at least one row was deleted.
List<CyRow>	getAllRows() Return a list of all the rows stored in this data table.
CyColumn	getColumn(String columnName) Returns the column for the specified name.
Collection<CyColumn>	getColumns() Returns the column types for all columns in this table.
String	getLastInternalError() Returns a descriptive message for certain internal errors.
Collection<CyRow>	getMatchingRows(String columnName, Object value) Returns all the rows of a specified column that contain a certain value for that column.
CyTable.Mutability	getMutability() The table can be deleted if this returns Mutability.MUTABLE, otherwise it cannot be deleted!
CyColumn	getPrimaryKey() Returns the column type of the primary key for this table.
CyRow	getRow(Object primaryKey) Returns the row specified by the primary key object and if a row for the specified key does not yet exist in the table, a new row will be created and the new row will be returned.
int	getRowCount() Returns the number of rows in this table.
SavePolicy	getSavePolicy() Returns how (or if) this CyTable should be saved.
String	getTitle() Returns a human readable name for the CyTable.
boolean	isPublic() A public CyTable is a table that is accessible to the user through the user interface.
boolean	rowExists(Object primaryKey) Returns true if a row exists for the specified primary key and false otherwise.
void	setPublic(boolean isPublic) Sets the privacy flag for the CyTable.
void	setSavePolicy(SavePolicy policy) Sets how (or if) this CyTable should be saved.
void	setTitle(String title) Allows the title of the table to be set.
void	swap(CyTable otherTable) Swaps the contents and properties (such as mutability) of "otherTable" with this table.

Methods inherited from interface org.cytoscape.model.CyIdentifiable

getSUID

Method Detail

isPublic

boolean isPublic()

A public CyTable is a table that is accessible to the user through the user interface. Private or non-public CyTables will not be visible to the user from the normal user interface, although they will be accessible to app writers through the API.

Returns:

Whether or not this CyTable should be publicly accessible.

setPublic

void setPublic(boolean isPublic)

Sets the privacy flag for the CyTable. A public CyTable is a table that is accessible to the user through the user interface. Private or non-public CyTables will not be visible to the user from the normal user interface, although they will be accessible to app writers through the API. This method may fire CyTablePrivacyChangedEvent.

Parameters:

isPublic - if true, the table will be public and if false, the table will be private.

getMutability

CyTable.Mutability getMutability()

The table can be deleted if this returns Mutability.MUTABLE, otherwise it cannot be deleted!

Returns:

the current mutability state

getTitle

String getTitle()

Returns a human readable name for the CyTable.

Returns:

A human readable name for the CyTable.

setTitle

void setTitle(String title)

Allows the title of the table to be set. The title is meant to be human readable and suitable for use in a user interface.

Parameters:

title - The human readable title for the CyTable suitable for use in a user interface.

getPrimaryKey

CyColumn getPrimaryKey()

Returns the column type of the primary key for this table.

Returns:

The column type of the primary key for this table.

getColumn

CyColumn getColumn(String columnName)

Returns the column for the specified name.

Parameters:

columnName - The name of the column.

Returns:

The column for the name provided, or null if there is no column named "columnName".

getColumns

Collection<CyColumn> getColumns()

Returns the column types for all columns in this table.

Returns:

A set of CyColumn objects that describe all columns in this table.

deleteColumn

void deleteColumn(String columnName)

Will delete the column of the specified name. columnName must be not null. If the column does not exist, there is no effect. If the column is immutable, IllegalArgumentException will be thrown. If the deletion is successful, ColumnDeletedEvent will be fired.

Parameters:

columnName - The name identifying the attribute.

createColumn

<T> void createColumn(String columnName,
                      Class<? extends T> type,
                      boolean isImmutable)

Create a column of the specified name and the specified type. The column type is limited to Integer, Long, Double, String, and Boolean. The default value for the column will be null. If the column name has the suffix ".SUID" and the column type is Long, Cytoscape will handle it as a column of SUIDs, and automatically update its values when the session file is loaded. However only SUIDs of CyNodes, CyEdges and CyNetworks can be updated. If the column already exists, IllegalArgumentException will be thrown.

Type Parameters:

T - The generic type of the column.

Parameters:

columnName - The name identifying the attribute.

type - The type of the column.

isImmutable - if true, this column can never be deleted

createColumn

<T> void createColumn(String columnName,
                      Class<? extends T> type,
                      boolean isImmutable,
                      T defaultValue)

Create a column of the specified name and the specified type. The column type is limited to Integer, Long, Double, String, and Boolean. If the column already exists, IllegalArgumentException will be thrown. The check for matching column names is case insensitive.

Type Parameters:

T - The generic type of the column.

Parameters:

columnName - The name identifying the attribute.

type - The type of the column.

isImmutable - if true, this column can never be deleted

defaultValue - The default value for the column. Must be of the specified type or null.

createListColumn

<T> void createListColumn(String columnName,
                          Class<T> listElementType,
                          boolean isImmutable)

Create a column of Lists with the specified name and the specified element type. The column type is limited to Integer, Long, Double, String, and Boolean. The default value for the column will be null. If the column already exists, IllegalArgumentException will be thrown. The check for matching column names is case insensitive.

Type Parameters:

T - The generic type of the elements of the list.

Parameters:

columnName - The name identifying the attribute.

listElementType - The type of the elements of the list.

isImmutable - if true, this column can never be deleted

createListColumn

<T> void createListColumn(String columnName,
                          Class<T> listElementType,
                          boolean isImmutable,
                          List<T> defaultValue)

Create a column of Lists with the specified name and the specified element type. The column type is limited to Integer, Long, Double, String, and Boolean. If the column already exists, IllegalArgumentException will be thrown. The check for matching column names is case insensitive.

Type Parameters:

T - The generic type of the elements of the list.

Parameters:

columnName - The name identifying the attribute.

listElementType - The type of the elements of the list.

isImmutable - if true, this column can never be deleted

defaultValue - A default list for the column. Must be a List of the specified element type or null.

getRow

CyRow getRow(Object primaryKey)

Returns the row specified by the primary key object and if a row for the specified key does not yet exist in the table, a new row will be created and the new row will be returned. The check for matching column names is case insensitive.

Parameters:

primaryKey - The primary key index of the row to return.

Returns:

The CyRow identified by the specified key or a new row identified by the key if one did not already exist.

rowExists

boolean rowExists(Object primaryKey)

Returns true if a row exists for the specified primary key and false otherwise.

Parameters:

primaryKey - The primary key index of the row.

Returns:

True if a row exists for the specified primary key and false otherwise.

deleteRows

boolean deleteRows(Collection<?> primaryKeys)

Deletes the rows corresponding to the given primary keys and returns true if at least one row was deleted.

Parameters:

primaryKeys - The primary keys of the rows to delete.

Returns:

true if at least one row was deleted.

getAllRows

List<CyRow> getAllRows()

Return a list of all the rows stored in this data table.

WARNING. If this method is invoked multiple times, rows may not be returned in the same order. If you need to iterate through rows in the same order:

1. create your own ordered list of the table's primary keys
2. loop through your list of primary keys
3. in each loop iteration, obtain the row using getRow(java.lang.Object).

Returns:

a list of all the rows stored in this data table.

getLastInternalError

String getLastInternalError()

Returns a descriptive message for certain internal errors. Please note that only the very last message will be retrieved.

Returns:

if available, a message describing an internal error, otherwise null

getMatchingRows

Collection<CyRow> getMatchingRows(String columnName,
                                  Object value)

Returns all the rows of a specified column that contain a certain value for that column.

Parameters:

columnName - the column for which we want the rows

value - the value for which we want the rows that contain it

Returns:

the rows, if any that contain the value "value" for the column "columnName"

countMatchingRows

int countMatchingRows(String columnName,
                      Object value)

Returns the number of rows with the in the specified column with the specified value.

Parameters:

columnName - the column to check

value - the value we want to check for

Returns:

the number of rows with the in the specified column with the specified value.

getRowCount

int getRowCount()

Returns the number of rows in this table.

Returns:

The number if rows in the table.

addVirtualColumn

String addVirtualColumn(String virtualColumn,
                        String sourceColumn,
                        CyTable sourceTable,
                        String targetJoinKey,
                        boolean isImmutable)

Adds a "virtual" column to the the current table. A virtual column is a column in one table that points to a column in a different table. Instead of duplicating the column data found in the other table, a virtual column allows us to share that data by reference. A virtual column requires that columns be matched according to the primary key of the other table with a column in this table.

Parameters:

virtualColumn - The name of the new virtual column, if this name already exists, new column names with -1, -2 and so appended to this name on will be tried until a non-existing name will be found.

sourceColumn - The name of the column in "sourceTable" that will be mapped to "virtualColumn".

sourceTable - The table that really contains the column that we're adding (all updates and lookups of this new column will be redirected to here). The table will be joined on the primary key column of this table.

targetJoinKey - The column in current table that will be used for the join. This column will be joined with the primary key column of the source table. These columns must be of the same type!

isImmutable - If true, this column cannot be deleted.

Returns:

The actual name of the new virtual column.

addVirtualColumns

void addVirtualColumns(CyTable sourceTable,
                       String targetJoinKey,
                       boolean isImmutable)

Adds all columns in another table as "virtual" columns to the the current table. A virtual column is a column in one table that points to a column in a different table. Instead of duplicating the column data found in the other table, a virtual column allows us to share that data by reference. A virtual column requires that columns be matched according to the primary key of the other table with a column in this table.

Parameters:

sourceTable - The table that really contains the column that we're adding (all updates and lookups of this new column will be redirected to here). The table will be joined on the primary key column of this table. None of the column names in "sourceTable" must exist in the current table!

targetJoinKey - The column in current table that will be used for the join. This column will be joined with the primary key column of the source table. These columns must be of the same type!

isImmutable - If true, these columns cannot be deleted.

getSavePolicy

SavePolicy getSavePolicy()

Returns how (or if) this CyTable should be saved.

Returns:

how (or if) this CyTable should be saved.

setSavePolicy

void setSavePolicy(SavePolicy policy)

Sets how (or if) this CyTable should be saved.

Parameters:

policy - the policy to follow during the life-cycle of the CyTable.

swap

void swap(CyTable otherTable)

Swaps the contents and properties (such as mutability) of "otherTable" with this table. This method is used to copy tables for backup, undo, and deletion and generally shouldn't be needed for most normal work.

Parameters:

otherTable - the table that we're being swapped with. Note: the one "property" that is not being swapped is the SUID. Also, no events are being fired to give any listeners a chance to react to the exchange!