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

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

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

      The given name specifies the checkpoint used to service requests.
      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
      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

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