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

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