Package 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
    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
    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 Details

    • 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!