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 should explicitly call `Table.close` to reclaim its resources.

  Since Version 4.10: Whenever a `Table` that did not have its `Table.close` method called is garbage collected, the native resources will be reclaimed automatically. This behavior is controlled by the com.tibco.tibdg.autoclose System Property. If the property is not set or set to "cleanup" (the default), the native resources will be reclaimed as if the `Table.close` method had been called. If the System Property is set to "warn", a warning will be printed to stderr instead of doing the cleanup. If the property is set to "inactive", this feature will not be activated.

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

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `TIBDG_TABLE_CHECKPOINT_NAME_LATEST` A special checkpoint name that refers to the latest successful checkpoint Specifying this as the value for `Table.TIBDG_TABLE_PROPERTY_STRING_CHECKPOINT_NAME` property instructs the proxy to replace with the last successful checkpoint name.
    `static java.lang.String` | `TIBDG_TABLE_PROPERTY_STRING_CHECKPOINT_NAME` Property name for specifying checkpoint used with a table; string.

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

- - ### Field Detail

    - #### TIBDG_TABLE_PROPERTY_STRING_CHECKPOINT_NAME

          static final java.lang.String TIBDG_TABLE_PROPERTY_STRING_CHECKPOINT_NAME

      Property name for specifying checkpoint used with a table; string.

      Supply this property to `Session.openTable`.

      Specifying this property instructs the datagrid to use the named checkpoint as the data source for this table's read operations (gets, iterators). If this property is not set, the table will use the checkpoint named specified on the session, if any. If this property is set it will override any checkpoint name set on the session. The property value may be a checkpoint name or ID. Tables opened with this property are read-only, write operations (puts, deletes, updates) on the table are not supported. Not supported for transacted sessions.
      See Also:
        Constant Field Values

    - #### TIBDG_TABLE_CHECKPOINT_NAME_LATEST

          static final java.lang.String TIBDG_TABLE_CHECKPOINT_NAME_LATEST

      A special checkpoint name that refers to the latest successful checkpoint Specifying this as the value for `Table.TIBDG_TABLE_PROPERTY_STRING_CHECKPOINT_NAME` property instructs the proxy to replace with the last successful checkpoint name.
      See Also:
        Constant Field Values

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