com.tibco.datagrid

## Interface Session

- All Superinterfaces:
    java.lang.AutoCloseable

      public interface Session
      extends java.lang.AutoCloseable

  A session object provides the context for a thread of operations involving data grid resources.

  The session object is NOT thread-safe. Do not invoke multiple operations on a single session using more than one thread. Behavior is not defined if this happens.

  To create a session object, call `Connection.createSession`.

  A program that creates a session should explicitly call `Session.close` to reclaim its resources.

  Since Version 4.10: Whenever a `Session` that did not have its `Session.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 `Session.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_SESSION_CHECKPOINT_NAME_LATEST` A special checkpoint name that refers to the latest successful checkpoint Specifying this as the value for `Session.TIBDG_SESSION_PROPERTY_STRING_CHECKPOINT_NAME` property instructs the proxy to replace with the last successful checkpoint name.
    `static java.lang.String` | `TIBDG_SESSION_PROPERTY_BOOLEAN_IMMUTABLE_ROWS` Property to specify immutability of rows returned from ResultSet/Get APIs.
    `static java.lang.String` | `TIBDG_SESSION_PROPERTY_BOOLEAN_TRANSACTED` Property name for a transacted session; boolean.
    `static java.lang.String` | `TIBDG_SESSION_PROPERTY_DOUBLE_TRANSACTION_TIMEOUT` Property name for specifying the per-session transaction activity timeout.
    `static java.lang.String` | `TIBDG_SESSION_PROPERTY_STRING_CHECKPOINT_NAME` Property name for specifying checkpoint used in a session; string.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Destroy a session.
    `void` | `commit()` Commit the current transaction on this session and begin a new transaction.
    `Statement` | `createStatement(java.lang.String sql, java.util.Properties props)` Create a SQL statement object.
    `BatchResult` | `deleteRows(Row[] rows, java.util.Properties properties)` DELETE a batch of rows from the datagrid
    `long` | `executeUpdate(java.lang.String sqlString, java.util.Properties props)` Execute a SQL Update
    `Connection` | `getConnection()` Get the connection object that was used to create the session.
    `BatchResult` | `getRows(Row[] rows, java.util.Properties properties)` GET a batch of rows from the datagrid
    `void` | `interrupt()` Interrupt interrupts any outstanding request on the Session forcing it to throw an interrupted exception (`InterruptedException`).
    `Table` | `openTable(java.lang.String name, java.util.Properties props)` Open a table in the data grid.
    `BatchResult` | `putRows(Row[] rows, java.util.Properties properties)` PUT a batch of rows from the datagrid
    `void` | `rollback()` Rollback a transaction on this session.
    `BatchResult` | `updateRows(Row[] rows, java.util.Properties properties)` UPDATE a batch of rows from the datagrid

- - ### Field Detail

    - #### TIBDG_SESSION_PROPERTY_BOOLEAN_TRANSACTED

          static final java.lang.String TIBDG_SESSION_PROPERTY_BOOLEAN_TRANSACTED

      Property name for a transacted session; boolean.

      When creating a session, supply this property to `Connection.createSession`.

      The value true specifies that the created session will be transacted.

      See Also:
        Constant Field Values

    - #### TIBDG_SESSION_PROPERTY_STRING_CHECKPOINT_NAME

          static final java.lang.String TIBDG_SESSION_PROPERTY_STRING_CHECKPOINT_NAME

      Property name for specifying checkpoint used in a session; string.

      Supply this property to `Connection.createSession`.

      Specifying this property instructs the datagrid to use the named checkpoint as the data source for this session's read operations (gets, iterators, queries, or statements). The property value may be a checkpoint name or ID. Sessions opened with this property are read-only, write operations (puts, deletes, updates) do not support this property. Not supported for transacted sessions.
      See Also:
        Constant Field Values

    - #### TIBDG_SESSION_PROPERTY_DOUBLE_TRANSACTION_TIMEOUT

          static final java.lang.String TIBDG_SESSION_PROPERTY_DOUBLE_TRANSACTION_TIMEOUT

      Property name for specifying the per-session transaction activity timeout. When creating a session, supply this property to @ref tibdgConnection_CreateSession. Not supported for non-transacted sessions.
      See Also:
        Constant Field Values

    - #### TIBDG_SESSION_CHECKPOINT_NAME_LATEST

          static final java.lang.String TIBDG_SESSION_CHECKPOINT_NAME_LATEST

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

    - #### TIBDG_SESSION_PROPERTY_BOOLEAN_IMMUTABLE_ROWS

          static final java.lang.String TIBDG_SESSION_PROPERTY_BOOLEAN_IMMUTABLE_ROWS

      Property to specify immutability of rows returned from ResultSet/Get APIs.

      Supply this property to `Connection.createSession`.

      If true, rows returned cannot be modified. If unspecified, the value is inherited from the parent Connection, which is false by default. See also: `Connection.TIBDG_CONNECTION_PROPERTY_BOOLEAN_IMMUTABLE_ROWS`.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### openTable

          Table openTable(java.lang.String name,
                          java.util.Properties props)
                   throws DataGridException

      Open a table in the data grid. A table object contains rows and columns.

      Parameters:
        `name` - The name of the table to be opened. This table must already be defined in the data grid.
        `props` - Optional, null to omit
        - `Table.TIBDG_TABLE_PROPERTY_STRING_CHECKPOINT_NAME`
      Returns:
        `Table`
      Throws:
        `DataGridException` - in case of failures

    - #### commit

          void commit()
               throws DataGridException

      Commit the current transaction on this session and begin a new transaction.

      Committing a transaction causes the data grid to make permanent all table operations performed since the start of the current transaction.

      Throws:
        `DataGridException` - in case of failures

    - #### rollback

          void rollback()
                 throws DataGridException

      Rollback a transaction on this session.

      Rolling back a transaction causes the data grid to discard all table operations performed since the start of the transaction.

      Throws:
        `DataGridException` - in case of failures

    - #### getConnection

          Connection getConnection()
                            throws DataGridException

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

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

    - #### createStatement

          Statement createStatement(java.lang.String sql,
                                    java.util.Properties props)
                             throws DataGridException

      Create a SQL statement object.

      Parameters:
        `sql` - The sql string used to create the statement.
        `props` - Optional, null to omit
        - `Statement.TIBDG_STATEMENT_PROPERTY_LONG_PREFETCH`
        - `Statement.TIBDG_STATEMENT_PROPERTY_STRING_CONSISTENCY`
        - `Statement.TIBDG_STATEMENT_PROPERTY_DOUBLE_FETCH_TIMEOUT`
        - `Statement.TIBDG_STATEMENT_PROPERTY_DOUBLE_UPDATE_TIMEOUT`
      Returns:
        `Statement`
      Throws:
        `DataGridException` - in case of failures

    - #### executeUpdate

          long executeUpdate(java.lang.String sqlString,
                             java.util.Properties props)
                      throws DataGridException

      Execute a SQL Update

      A SQL update can be Create Table, Create Index, Drop Table, or Drop Index

      Parameters:
        `sqlString` - The sql string representing the update to execute
        `props` - Optional. \c null to omit.
      Returns:
        The number of rows modified by the update.
      Throws:
        `DataGridException` - in case of failures

    - #### getRows

          BatchResult getRows(Row[] rows,
                              java.util.Properties properties)
                       throws DataGridException

      GET a batch of rows from the datagrid

      Note: the rows may be on different tables. Not valid for transacted sessions

      Parameters:
        `rows` - The array of rows to GET
        `properties` - Optional, null to omit
      Returns:
        `BatchResult`
      Throws:
        `DataGridException` - in case of failures

    - #### putRows

          BatchResult putRows(Row[] rows,
                              java.util.Properties properties)
                       throws DataGridException

      PUT a batch of rows from the datagrid

      Note: the rows may be on different tables. Not valid for transacted sessions

      Parameters:
        `rows` - The array of rows to PUT
        `properties` - Optional, null to omit
      Returns:
        `BatchResult`
      Throws:
        `DataGridException` - in case of failures

    - #### deleteRows

          BatchResult deleteRows(Row[] rows,
                                 java.util.Properties properties)
                          throws DataGridException

      DELETE a batch of rows from the datagrid

      Note: the rows may be on different tables. Not valid for transacted sessions

      Parameters:
        `rows` - The array of rows to DELETE
        `properties` - Optional, null to omit
      Returns:
        `BatchResult`
      Throws:
        `DataGridException` - in case of failures

    - #### updateRows

          BatchResult updateRows(Row[] rows,
                                 java.util.Properties properties)
                          throws DataGridException

      UPDATE a batch of rows from the datagrid

      Note: the rows may be on different tables. Not valid for transacted sessions

      Parameters:
        `rows` - The array of rows to UPDATE
        `properties` - Optional, null to omit
      Returns:
        `BatchResult`
      Throws:
        `DataGridException` - in case of failures

    - #### close

          void close()
              throws DataGridException

      Destroy a session.

      If a transaction was started on this session, this call automatically rolls back the transaction.

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

    - #### interrupt

          void interrupt()
                  throws DataGridException

      Interrupt interrupts any outstanding request on the Session forcing it to throw an interrupted exception (`InterruptedException`).
      Throws:
        `DataGridException` - in case of failures