com.tibco.datagrid

## Interface Table

- All Superinterfaces:
    java.lang.AutoCloseable

      public interface Table
      extends java.lang.AutoCloseable

  The Table object has methods to put, get and delete rows as well as to create a `RowSet` for iterating over some or all of the data in the table.

  The call that creates a table is `Session.openTable`.

  A program that creates a table must explicitly call `Table.close` to reclaim its resources.

  This interface is implemented internally. Applications do not implement this interface.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Close a table.
    `Row` | `createRow()` Create an empty row object.
    `RowSet` | `createRowSet(java.lang.String filter, java.util.Properties props)` Create a RowSet to selectively get rows in the table.
    `TableListener` | `createTableListener(java.lang.String filter, TableEventHandler eventHandler)` Create a TableListener Table listeners receive `Event` objects to indicate that the table they are listening on has changed.
    `TableListener` | `createTableListener(java.lang.String filter, TableEventHandler eventHandler, java.util.Properties props)` Create a TableListener
    `void` | `delete(Row key)` Delete a row from a table.
    `Row` | `get(Row key)` Get a row from a table.
    `java.lang.String` | `getName()` Get the name of the table.
    `Session` | `getSession()` Get the session object that was used to create the table.
    `void` | `put(Row keyValue)` Put a row into a table.
    `long` | `update(Row key)` Update a row in the table.

- - ### Method Detail

    - #### createRow

          Row createRow()
                 throws DataGridException

      Create an empty row object.

      This function returns an empty row object. The application can set columns in the empty row object and use the object as a keyValue for `Table.createRow` or as a key for `Table.get` or `Table.delete`.

      Returns:
        `Row` object
      Throws:
        `DataGridException` - in case of failures

    - #### put

          void put(Row keyValue)
            throws DataGridException

      Put a row into a table.

      The contents of the row contain the information to be placed into the designated table. This must include the values for the columns that make up primary key. Values for the other columns are optional.

      Parameters:
        `keyValue` - The row to be placed in the table.
      Throws:
        `DataGridException` - in case of failures

    - #### get

          Row get(Row key)
           throws DataGridException

      Get a row from a table.

      Using the columns set in the key, this call fetches the row from the table and returns it.

      Note: Do not use a row object obtained from one table for operations in a different table. The schemas of the tables may not be compatible and the operations may fail.

      Any row object obtained from this function must be released by calling `Row.destroy`

      Parameters:
        `key` - The key information used to fetch the row.
      Returns:
        `Row` object
      Throws:
        `DataGridException` - in case of failures

    - #### update

          long update(Row key)
               throws DataGridException

      Update a row in the table.

      Sets the columns in the row specified by the key to the values set in the input row returning the number of rows modified. Will update only the columns specified leaving others intact in the existing row

      If the row does not exist, this will do nothing and return zero

      Parameters:
        `key` - The key information used to fetch the row.
      Returns:
        int number of rows modified by the update (zero if row was not in table)
      Throws:
        `DataGridException` - in case of failures

    - #### createRowSet

          RowSet createRowSet(java.lang.String filter,
                              java.util.Properties props)
                       throws DataGridException

      Create a RowSet to selectively get rows in the table.

      This call creates an RowSet object that contains an iterator which returns rows matching the filter.

      This call will block while it fetches the first batch of rows. If fetching each batch of rows is expected to take a long time then the `RowSet.TIBDG_ITERATOR_PROPERTY_DOUBLE_FETCH_TIMEOUT` property should be set to prevent the fetch requests from timing out.

      Parameters:
        `filter` - A string containing a valid query or null to include all the rows in the table
        `props` - Optional, null to omit
        - `RowSet.TIBDG_ITERATOR_PROPERTY_LONG_PREFETCH`
        - `RowSet.TIBDG_ITERATOR_PROPERTY_STRING_CONSISTENCY`
        - `RowSet.TIBDG_ITERATOR_PROPERTY_DOUBLE_FETCH_TIMEOUT`
      Returns:
        `RowSet`
      Throws:
        `DataGridException` - in case of failures

    - #### delete

          void delete(Row key)
               throws DataGridException

      Delete a row from a table.

      Using the columns in the key, this call deletes the row from the table.

      Parameters:
        `key` - The key used to identify row in the table.
      Throws:
        `DataGridException` - in case of failures

    - #### getName

          java.lang.String getName()
                            throws DataGridException

      Get the name of the table.

      Returns:
        a table name string
      Throws:
        `DataGridException` - in case of failures

    - #### getSession

          Session getSession()
                      throws DataGridException

      Get the session object that was used to create the table.

      Returns:
        `Session`
      Throws:
        `DataGridException` - in case of failures

    - #### createTableListener

          TableListener createTableListener(java.lang.String filter,
                                            TableEventHandler eventHandler)
                                     throws DataGridException

      Create a TableListener Table listeners receive `Event` objects to indicate that the table they are listening on has changed. A filter can be provided so that only events that match the filter will be received. The syntax for the filter is the same as the syntax for the `RowIterator`. An event matches the filter if either its previous or current value match.

      Parameters:
        `filter` - The filter string to for the listener to use
        `eventHandler` - the object to deliver events to (see `TableEventHandler`)
      Returns:
        `TableListener`
      Throws:
        `DataGridException` - in case of failures

    - #### createTableListener

          TableListener createTableListener(java.lang.String filter,
                                            TableEventHandler eventHandler,
                                            java.util.Properties props)
                                     throws DataGridException

      Create a TableListener

      Parameters:
        `filter` - The filter string to for the listener to use
        `eventHandler` - the object to deliver events to (see `TableEventHandler`)
        `props` - Optional, null to omit
        - `TableListener.TIBDG_LISTENER_PROPERTY_STRING_EVENT_TYPE_LIST`
      Returns:
        `TableListener`
      Throws:
        `DataGridException` - in case of failures

    - #### close

          void close()
              throws DataGridException

      Close a table.

      Release all resources associated with this table object.

      Note that pending operations on this table, e.g., transactional puts, gets or deletes, are marked as "rollback only" if this table is closed before the operations are committed.

      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Throws:
        `DataGridException` - in case of failures