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. For column naming conventions: org.cytoscape.model document.

Column Namespaces

A column name can be broken down into two parts, a "namespace" and a "name". The namespace and name can be combined into a String by separating them with a "::", for example: "MyNamespace::MyName". The namespace part is optional, for example the column name "MyName" does not have a namespace. All methods that take a namespace argument will accept null to indicate no namespace. All of the default network columns created by Cytoscape do not have a namespace.

Apps are encouraged to put any columns they create into a namespace. The advantages of doing this are:

1. Avoid name collision with other apps.
2. Enable UI features based on namespaces.
3. Use namespace aware APIs in CyColumn, CyRow and CyTable

Column Naming Rules

Case is ignored when column names are compared, or example "MyColumnName" and "mycolumnname" are equivalent. This also applies to namespaces, for example "MyNamespace::MyName" and "mynamespace::myname" are equivalent.

Whitespace is significant in both the namespace and the name (for historical reasons), for example " mynamespace ::myname" is in the namespace " mynamespace ". The empty string is a valid name for a namespace, for example "::myname" is in the "" namespace. It is highly recommended not to use whitespace in namespace identifiers, stick with alphanumeric characters and underscores.

Pick a namespace identifier that is between 6-15 characters in length that does not contain whitespace or special characters. Good examples are "EnrichmentMap", "clusterMaker" or "WordCloud".

Module: model-api

To use this in your app, include the following dependency in your POM:

<dependency>
    <groupId>org.cytoscape</groupId>
    <artifactId>model-api</artifactId>
</dependency>

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

Nested Classes

Modifier and Type	Interface and Description
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

Modifier and Type	Method and Description
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 fullyQualifiedName, Object value) Returns the number of rows with the in the specified column with the specified value in the user namespace.
default int	countMatchingRows(String namespace, String columnName, Object value) Returns the number of rows with the in the specified column with the specified value.
<T> void	createColumn(String fullyQualifiedName, Class<? extends T> type, boolean isImmutable) Create a column of the specified name and the specified type.
<T> void	createColumn(String fullyQualifiedName, Class<? extends T> type, boolean isImmutable, T defaultValue) Create a column of the specified name and the specified type.
default <T> void	createColumn(String namespace, String columnName, Class<? extends T> type, boolean isImmutable) Create a column of the specified name and the specified type in the specified namespace.
default <T> void	createColumn(String namespace, String columnName, Class<? extends T> type, boolean isImmutable, T defaultValue) Create a column of the specified name and the specified type in the specified namespace.
<T> void	createListColumn(String fullyQualifiedName, Class<T> listElementType, boolean isImmutable) Create a column of Lists with the specified name and the specified element type.
<T> void	createListColumn(String fullyQualifiedName, Class<T> listElementType, boolean isImmutable, List<T> defaultValue) Create a column of Lists with the specified name and the specified element type.
default <T> void	createListColumn(String namespace, String columnName, Class<T> listElementType, boolean isImmutable) Create a column of Lists with the specified name and the specified element type in the specified namespace.
default <T> void	createListColumn(String namespace, String columnName, Class<T> listElementType, boolean isImmutable, List<T> defaultValue) Create a column of Lists with the specified name and the specified element type in the specified namespace.
void	deleteColumn(String fullyQualifiedName) Will delete the column with the specified fully-qualified name.
default void	deleteColumn(String namespace, String columnName) Will delete the column of the specified name in the specified namespace.
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 fullyQualifiedName) Returns the column with the specified fully-qualified name.
default CyColumn	getColumn(String namespace, String name) Returns the column for the specified name in the specified namespace.
Collection<CyColumn>	getColumns() Returns the column types for all columns in this table.
default Collection<CyColumn>	getColumns(String namespace) Returns the column types for all columns in this table in the given namespace.
String	getLastInternalError() Returns a descriptive message for certain internal errors.
<T> Collection<T>	getMatchingKeys(String fullyQualifiedName, Object value, Class<T> type) Returns all the keys of a specified column that match the given value.
default <T> Collection<T>	getMatchingKeys(String namespace, String columnName, Object value, Class<T> type) Returns all the keys of a specified column that match the given value.
Collection<CyRow>	getMatchingRows(String fullyQualifiedName, Object value) Returns all the rows of a specified column that contain a certain value for that column.
default Collection<CyRow>	getMatchingRows(String namespace, 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!
default Collection<String>	getNamespaces() Returns all the namespaces used in the table.
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 fullyQualifiedName)

Returns the column with the specified fully-qualified name.

Parameters:

fullyQualifiedName - The fully-qualified name of the column, not null.

Returns:

The column for the name provided, or null if there is no column with the given name.

See Also:

getColumn(String, String)

getColumn

default CyColumn getColumn(String namespace,
                           String name)

Returns the column for the specified name in the specified namespace. Default columns created by Cytoscape do not have a namespace.

Parameters:

name - The name of the column, not null.

namespace - The namespace of the column, or null to indicate no namespace.

Returns:

The column for the name provided, or null if there is no column with the given namespace and name.

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.

getColumns

default Collection<CyColumn> getColumns(String namespace)

Returns the column types for all columns in this table in the given namespace.

Parameters:

namespace - The namespace, or null to indicate no namespace.

Returns:

A set of CyColumn objects that describe all columns in the given namespace.

getNamespaces

default Collection<String> getNamespaces()

Returns all the namespaces used in the table. If there is a column in the default namespace then the returned collection will contain null.

deleteColumn

void deleteColumn(String fullyQualifiedName)

Will delete the column with the specified fully-qualified name. 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. Default columns created by Cytoscape do not have a namespace.

Parameters:

fullyQualifiedName - The fully-qualified name of the column, not null.

See Also:

deleteColumn(String, String)

deleteColumn

default void deleteColumn(String namespace,
                          String columnName)

Will delete the column of the specified name in the specified namespace. 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, must not be null.

namespace - The namespace of the column, or null to indicate no namespace.

createColumn

<T> void createColumn(String fullyQualifiedName,
                      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:

fullyQualifiedName - The fully-qualified name identifying the attribute.

type - The type of the column.

isImmutable - if true, this column can never be deleted

See Also:

createColumn(String, String, Class, boolean)

createColumn

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

Create a column of the specified name and the specified type in the specified namespace. 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.

namespace - The namespace for the column, or null to indicate no namespace.

type - The type of the column.

isImmutable - if true, this column can never be deleted

createColumn

<T> void createColumn(String fullyQualifiedName,
                      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:

fullyQualifiedName - The fully-qualified 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.

See Also:

createColumn(String, String, Class, boolean, Object)

createColumn

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

Create a column of the specified name and the specified type in the specified namespace. 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.

namespace - The namespace for the column, or null to indicate no namespace.

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 fullyQualifiedName,
                          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:

fullyQualifiedName - The fully-qualified name identifying the attribute.

listElementType - The type of the elements of the list.

isImmutable - if true, this column can never be deleted

See Also:

createListColumn(String, String, Class, boolean)

createListColumn

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

Create a column of Lists with the specified name and the specified element type in the specified namespace. 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.

namespace - The namespace for the column, or null to indicate no namespace.

listElementType - The type of the elements of the list.

isImmutable - if true, this column can never be deleted

createListColumn

<T> void createListColumn(String fullyQualifiedName,
                          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:

fullyQualifiedName - The fully-qualified 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.

See Also:

createListColumn(String, String, Class, boolean, List)

createListColumn

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

Create a column of Lists with the specified name and the specified element type in the specified namespace. 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.

namespace - The namespace for the column, or null to indicate no namespace.

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. The order of the rows in the list corresponds to the order in which the rows have been inserted in the table.

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 fullyQualifiedName,
                                  Object value)

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

Parameters:

fullyQualifiedName - the fully-qualified column name 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"

See Also:

getMatchingRows(String, String, Object)

getMatchingRows

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

Returns all the rows of a specified column that contain a certain value for that column. Default columns created by Cytoscape are in the CyTable#USER_NAMESPACE namespace.

Parameters:

columnName - the column for which we want the rows

namespace - the namespace that contains the column.

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"

getMatchingKeys

<T> Collection<T> getMatchingKeys(String fullyQualifiedName,
                                  Object value,
                                  Class<T> type)

Returns all the keys of a specified column that match the given value.

Parameters:

fullyQualifiedName - the fully-qualified column name for which we want the row keys

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

Returns:

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

Throws:

ClassCastException - if the keys are not of the given type

See Also:

getMatchingKeys(String, String, Object, Class)

getMatchingKeys

default <T> Collection<T> getMatchingKeys(String namespace,
                                          String columnName,
                                          Object value,
                                          Class<T> type)

Returns all the keys of a specified column that match the given value. Default columns created by Cytoscape are in the CyTable#USER_NAMESPACE namespace.

Parameters:

columnName - the column for which we want the row keys

namespace - the namespace that contains the column

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

Returns:

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

Throws:

ClassCastException - if the keys are not of the given type

countMatchingRows

int countMatchingRows(String fullyQualifiedName,
                      Object value)

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

Parameters:

fullyQualifiedName - the fully-qualified column name 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.

See Also:

countMatchingRows(String, String, Object)

countMatchingRows

default int countMatchingRows(String namespace,
                              String columnName,
                              Object value)

Returns the number of rows with the in the specified column with the specified value. Default columns created by Cytoscape are in the CyTable#USER_NAMESPACE namespace.

Parameters:

columnName - the column to check

namespace - the namespace that contains the column

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!