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..

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      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.

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