com.ibm.websphere.objectgrid
Interface Session

public interface Session

This interface represents a session container for ObjectMaps. A thread must get its own Session object to interact with ObjectGrid. You can think of this interface as a session that can only be used by a single thread at a time. A Session itself is shareable across threads so long as only one thread uses it at a time. However, if a J2EE connection/transaction infrastructure is being used, that won't be shareable across threads and will prevent the Session object from being shared across threads. A good analogy for this object is a JDBC connection to a database. For best performance, use the close() method to close the session once it is no longer required.

Since:

WAS XD 6.0, XC10

See Also:

ObjectGrid.getSession(), ObjectGrid.getSession(Subject), ObjectGrid.getSession(CredentialGenerator)

Nested Class Summary

static class

Session.TxCommitProtocol The commit protocols that can be used to commit the Session's transaction

Field Summary

static long	DEFAULT_RETRY_TIMEOUT
static int	TRANSACTION_NO_TIMEOUT A special value for the timeout parameter of the setTransactionTimeout(int) method.
static int	TRANSACTION_READ_COMMITTED A transaction isolation level constant indicating that dirty reads are prevented; non-repeatable reads and phantom reads can occur.
static int	TRANSACTION_READ_UNCOMMITTED A transaction isolation level constant indicating that dirty reads, non-repeatable reads and phantom reads can occur.
static int	TRANSACTION_REPEATABLE_READ A transaction isolation level constant indicating that dirty reads and non-repeatable reads are prevented; phantom reads can occur.
static String	TRANSACTION_TYPE_DEFAULT A string indicating the default transaction type

Method Summary

void	begin() Begins a new transaction.
void	beginNoWriteThrough() Starts a new transaction that does not write changes through to a Loader or ObjectGrid server.
void	close() Closes this session, freeing all resources that are held.
void	commit() Commits a transaction.
ObjectQuery	createObjectQuery(String qlString) Creates an instance of an object query for executing a query over the ObjectMaps visible to this session.
void	flush() Forces the current changes in the Session to the Loader or ObjectGrid server.
EntityManager	getEntityManager() Retrieve the EntityManager associated with this Session.
ObjectMap	getMap(String cacheName) Returns the ObjectMap for the specified name.
ObjectGrid	getObjectGrid() Returns the ObjectGrid that owns this session.
long	getRequestRetryTimeout() Retrieves the current request retry timeout for this session.
SessionHandle	getSessionHandle() Retrieves a handle for this session.
int	getTransactionIsolation() Retrieves the current transaction isolation level for this session.
int	getTransactionTimeout() Gets current transaction timeout for this Session.
String	getTransactionType() Retrieves the transaction type that is set with the setTransactionType(String) method.
Session.TxCommitProtocol	getTxCommitProtocol() Retrieve the current commit protocol for this Session.
TxID	getTxID() Gets the TxID transaction identifier, if a transaction is active.
boolean	isCommitting() Returns whether the current session transaction is performing a session commit() operation.
boolean	isFlushing() Returns whether the current session transaction is performing a session flush() operation.
boolean	isMarkedRollbackOnly() Returns whether or not the current active session transaction is marked as being rollback only as a result of a prior call to the markRollbackOnly(Throwable) method on this Session.
boolean	isSessionHandleSet() Determines if a SessionHandle is currently set on this Session.
boolean	isTransactionActive() Determines if a transaction is currently active.
boolean	isWriteThroughEnabled() Returns whether the current session transaction is writing through to the back end Loader or ObjectGrid server(true), or if the changes are only applying to the BackingMap (false) or client respectively.
void	markRollbackOnly(Throwable t) Marks the current transaction as being rollback only.
void	processLogSequence(LogSequence logSequence) Processes a LogSequence.
void	rollback() Rolls back a transaction.
void	setRequestRetryTimeout(long requestRetryTimeout) Set the request retry timeout to indicate how long to retry a request (in milliseconds) when recoverable failures occur, such as fail-over exceptions.
void	setSessionHandle(SessionHandle target) Apply a SessionHandle to this session.
void	setTransactionIsolation(int level) Attempts to change the transaction isolation level for this session.
void	setTransactionTimeout(int timeout) Sets the transaction timeout for the next transaction started by this Session object to a specified number of seconds.
void	setTransactionType(String tranType) Sets the transaction type for future transactions.
void	setTxCommitProtocol(Session.TxCommitProtocol protocol) Set the commit protocol to be used when committing this Session's transaction.
boolean	transactionTimedOut() Determines whether the current session transaction has timed out.

Field Detail

TRANSACTION_TYPE_DEFAULT

static final String TRANSACTION_TYPE_DEFAULT

A string indicating the default transaction type

See Also:

Constant Field Values

TRANSACTION_NO_TIMEOUT

static final int TRANSACTION_NO_TIMEOUT

A special value for the timeout parameter of the setTransactionTimeout(int) method. This special value is used to indicate that the next transaction started by this Session is allowed unlimited amount of time.

See Also:

setTransactionTimeout(int), Constant Field Values

DEFAULT_RETRY_TIMEOUT

static final long DEFAULT_RETRY_TIMEOUT

See Also:

Constant Field Values

TRANSACTION_REPEATABLE_READ

static final int TRANSACTION_REPEATABLE_READ

A transaction isolation level constant indicating that dirty reads and non-repeatable reads are prevented; phantom reads can occur. This level prohibits a transaction from reading an uncommitted cache entry, and it also prohibits the situation where one transaction reads an entry, a second transaction alters the entry, and the first transaction rereads the entry, getting different values the second time (a "non-repeatable read").

Since:

WAS XD 6.1.0.1

See Also:

setTransactionIsolation(int), Constant Field Values

TRANSACTION_READ_COMMITTED

static final int TRANSACTION_READ_COMMITTED

A transaction isolation level constant indicating that dirty reads are prevented; non-repeatable reads and phantom reads can occur. This level only prohibits a transaction from reading a cache entry with uncommitted changes in it.

Since:

WAS XD 6.1.0.1

See Also:

setTransactionIsolation(int), Constant Field Values

TRANSACTION_READ_UNCOMMITTED

static final int TRANSACTION_READ_UNCOMMITTED

A transaction isolation level constant indicating that dirty reads, non-repeatable reads and phantom reads can occur. This level allows a cache entry changed by one transaction to be read by another transaction before any changes in that entry have been committed (a "dirty read"). If any of the changes are rolled back, the second transaction will have retrieved an invalid entry.

Since:

WAS XD 6.1.0.1

See Also:

setTransactionIsolation(int), Constant Field Values

Method Detail

beginNoWriteThrough

void beginNoWriteThrough()
                         throws TransactionAlreadyActiveException,
                                TransactionException

Starts a new transaction that does not write changes through to a Loader or ObjectGrid server.

Changes made by the session transaction started by this method are only applied to the BackingMap and not given to the Loader. This method can be used to apply changes made in a peer cache to the local BackingMap only. In addition, with a distributed map, this method can be used to start a session transaction which changes will only be applied to the client BackingMap, but not the BackingMap on the server side.

Throws:

TransactionAlreadyActiveException - if there is already an active transaction

TransactionException - a TransactionCallbackException occurred or some other error occurred starting a new transaction

getMap

ObjectMap getMap(String cacheName)
                 throws UndefinedMapException

Returns the ObjectMap for the specified name.

The ObjectMap is used to retrieve and modify values in the BackingMap. Multiple invocations of this method on the same Session object will always return the same object.

This method can also be used to create a BackingMap and its associated ObjectGrid after ObjectGrid initialization. If cacheName does not match the name of a previously created map, a name comparison will be executed against template maps that have been configured. The ObjectMap and BackingMap will be created if the name matches the regular expression of a template.

Required Client Permission: ObjectGridPermission.DYNAMIC_MAP (when creating a new map from a template)

Parameters:

cacheName - name of desired map

Returns:

ObjectMap the transactional interface to modify values in the map

Throws:

UndefinedMapException - if the map is not defined.

See Also:

ObjectGrid.defineMap(String), ObjectMap

begin

void begin()
           throws TransactionAlreadyActiveException,
                  TransactionException

Begins a new transaction.

Throws:

TransactionAlreadyActiveException - if this method is invoked with an active transaction

TransactionException - a TransactionCallbackException occurred or some other error occurred starting a new transaction

commit

void commit()
            throws NoActiveTransactionException,
                   TransactionException

Commits a transaction.

Throws:

NoActiveTransactionException - if this method is invoked with no active transaction

TransactionException - if an error occurred during commit processing, see the caused by to determine the root error

See Also:

markRollbackOnly(Throwable)

rollback

void rollback()
              throws NoActiveTransactionException,
                     TransactionException

Rolls back a transaction.

Throws:

NoActiveTransactionException - if this method is invoked with no active transaction

TransactionException - if an error occurred during rollback processing, see the caused by to determine the root error

flush

void flush()
           throws NoActiveTransactionException,
                  TransactionException

Forces the current changes in the Session to the Loader or ObjectGrid server. This method does not commit the changes, it just applies the changes.

Throws:

NoActiveTransactionException - if this method is invoked with no active transaction

TransactionException - if an error occurred during flush processing, see the caused by to determine the root error

getObjectGrid

ObjectGrid getObjectGrid()

Returns the ObjectGrid that owns this session.

Returns:

the owning ObjectGrid instance.

isTransactionActive

boolean isTransactionActive()

Determines if a transaction is currently active.

Returns:

true if a transaction is currently active for this session.

Since:

WAS XD 6.1 FIX3

getTxID

TxID getTxID()
             throws NoActiveTransactionException

Gets the TxID transaction identifier, if a transaction is active.

Returns:

The current TxID object.

Throws:

NoActiveTransactionException - if this method is invoked with no active transaction

isWriteThroughEnabled

boolean isWriteThroughEnabled()

Returns whether the current session transaction is writing through to the back end Loader or ObjectGrid server(true), or if the changes are only applying to the BackingMap (false) or client respectively.

Returns:

true, if write through is enabled

See Also:

begin(), beginNoWriteThrough()

setTransactionType

void setTransactionType(String tranType)

Sets the transaction type for future transactions.

After this method is called, all future transactions will have the same type until another transaction type is set. If no transaction type is set, the default transaction type TRANSACTION_TYPE_DEFAULT will be used.

Transaction types are used mainly for statistical data tracking purpose. Users can predefine types of transactions that will be executed in an application. The idea is to categorize transactions with the same characteristics to one category (type), so one transaction response time statistics can be used to track each transaction type. This approach is useful when your application has different types of transactions. Some types of transactions, such as update transactions, process longer than others transactions, such as read-only transactions. By using the transaction type, different transactions are tracked by different statistics, so the statistics can be more useful.

Parameters:

tranType - the transaction type for future transactions.

See Also:

TRANSACTION_TYPE_DEFAULT

getTransactionType

String getTransactionType()

Retrieves the transaction type that is set with the setTransactionType(String) method.

Returns:

the transaction type for the session.

Since:

7.1.1.1

processLogSequence

void processLogSequence(LogSequence logSequence)
                        throws NoActiveTransactionException,
                               UndefinedMapException,
                               ObjectGridException

Processes a LogSequence.

Each LogElement within the LogSequence will be examined and the appropriate operation (insert, update, invalidate, etc) will be performed against the BackingMap identified by the LogSequence's map name. An ObjectGrid Session must be active before this method is invoked. The caller is responsible for issuing the appropriate commit or rollback invocation to complete the Session. Autocommit processing is not available for this method invocation.

The main use of this method is for processing a LogSequence that was received by a remote JVM. For example, using the Distributed Commit support, the LogSequences associated with a given committed Session are distributed to other listening ObjectGrids in other JVMs. After receiving the LogSequences at the remote JVM, the listener could start a Session using beginNoWriteThrough(), invoke this method, and commit the Session transaction.

Parameters:

logSequence - LogSequence of changes to be applied to an active transaction

Throws:

NoActiveTransactionException - if this method is invoked with no active transaction

UndefinedMapException - if the map referenced by the LogSequence cannot be found

ObjectGridException - if the LogSequence elements cannot be processed

See Also:

beginNoWriteThrough(), LogSequence, ObjectGridEventListener

isFlushing

boolean isFlushing()

Returns whether the current session transaction is performing a session flush() operation. It is helpful to know if a session flush() is active (true), or if only an ObjectMap.flush() is in progress (returns false in this case).

Returns:

true, if the session is executing a session flush() call.

Since:

WAS XD 6.0.1

See Also:

flush(), ObjectMap.flush()

isCommitting

boolean isCommitting()

Returns whether the current session transaction is performing a session commit() operation. It is helpful to know if a session commit is active (true), or if an ObjectMap.flush() or session flush() is in progress (returns false in these cases).

Returns:

true, if session is executing a session commit() call.

Since:

WAS XD 6.0.1

See Also:

commit(), flush(), ObjectMap.flush()

markRollbackOnly

void markRollbackOnly(Throwable t)
                      throws NoActiveTransactionException

Marks the current transaction as being rollback only.

Marking a transaction rollback only ensures that even if the commit() method is called for this session transaction, the transaction is rolled back. A rollback is typically done when either ObjectGrid itself or the application knows that data corruption could occur if the commit() method was allowed to commit the transaction. Once this method is called, the Throwable object that is passed to it is chained to the TransactionException that is thrown if the commit method is ever called. Any subsequent calls to this method for the current active transaction is ignored (e.g. only the first call that passes a non null Throwable reference is used). Once the transaction is completed, the rollback only mark is removed so that the next transaction that is started using this session can be committed.

Parameters:

t - the Throwable that caused this method to be called.

Throws:

NoActiveTransactionException - if there is no active transaction for this Session.

Since:

WAS XD 6.0.1

See Also:

commit(), TransactionException

isMarkedRollbackOnly

boolean isMarkedRollbackOnly()

Returns whether or not the current active session transaction is marked as being rollback only as a result of a prior call to the markRollbackOnly(Throwable) method on this Session.

Returns:

true if and only if current session transaction is marked rollback only.

Since:

WAS XD 6.0.1

See Also:

markRollbackOnly(Throwable)

setTransactionTimeout

void setTransactionTimeout(int timeout)

Sets the transaction timeout for the next transaction started by this Session object to a specified number of seconds.

This method does not affect the transaction timeout of any transactions previously started by this Session. It only affects transactions that are started after this method is called. If this method is never called, the ObjectGrid configured transaction timeout value is used.

Parameters:

timeout - is the transaction timeout value in seconds. Use the special value TRANSACTION_NO_TIMEOUT if transaction is allowed unlimited amount of time and no transaction timeout should occur.

Since:

WAS XD 6.0.1

See Also:

TRANSACTION_NO_TIMEOUT, ObjectGrid.setTxTimeout(int), TransactionTimeoutException

getTransactionTimeout

int getTransactionTimeout()

Gets current transaction timeout for this Session.

The transaction timeout value returned is the value that was configured for the ObjectGrid using ObjectGrid.setTxTimeout(int) or the value passed to setTransactionTimeout(int) to override the value configured on ObjectGrid. The return value is in seconds.

Returns:

timeout value in seconds.

Since:

WAS XD 6.0.1

See Also:

setTransactionTimeout(int), ObjectGrid.setTxTimeout(int)

getTransactionIsolation

int getTransactionIsolation()

Retrieves the current transaction isolation level for this session.

Returns:

one of the following Session constants: TRANSACTION_READ_UNCOMMITTED, TRANSACTION_READ_COMMITTED or TRANSACTION_REPEATABLE_READ

Since:

WAS XD 6.1.0.1

transactionTimedOut

boolean transactionTimedOut()

Determines whether the current session transaction has timed out.

Returns:

true if and only if transaction has timed out.

Since:

WAS XD 6.0.1

See Also:

setTransactionTimeout(int)

createObjectQuery

ObjectQuery createObjectQuery(String qlString)
                              throws ObjectQueryException

Creates an instance of an object query for executing a query over the ObjectMaps visible to this session.

When ObjectGrid security is enabled, this method requires an com.ibm.websphere.objectgrid.security.ObjectGridPermission with action "query".

Required Client Permission: ObjectGridPermission.QUERY

Parameters:

qlString - a query string

Returns:

the new query instance.

Throws:

ObjectQueryException - if an error occurs creating the object query.

Since:

WAS XD 6.1

getEntityManager

EntityManager getEntityManager()

Retrieve the EntityManager associated with this Session. Each session is associated with a single EntityManager instance. Repeated calls to this method on the same Session instance will result in the same EntityManager instance.

Returns:

this session's EntityManager instance.

Since:

WAS XD 6.1

setTransactionIsolation

void setTransactionIsolation(int level)

Attempts to change the transaction isolation level for this session. The constants defined in the Session interface are the possible transaction isolation levels.

This method should normally be invoked prior to beginning a transaction. Invoking after a transaction has started may result in an exception.

Parameters:

level - one of the following Session constants: TRANSACTION_READ_UNCOMMITTED, TRANSACTION_READ_COMMITTED or TRANSACTION_REPEATABLE_READ

Since:

WAS XD 6.1.0.1

getSessionHandle

SessionHandle getSessionHandle()

Retrieves a handle for this session.

A SessionHandle contains partition information for the current session and can be re-applied to a new session using the setSessionHandle(SessionHandle) method. A SessionHandle is only applicable for ObjectGrids using per-container partition placement. If setSessionHandle(SessionHandle) is not called before invoking this method, a Session Handle is selected using the properties configured in the ClientProperties. If there are no per-container partition placement mapsets or more than one in the ObjectGrid, an IllegalStateException is thrown.

Returns:

the SessionHandle for this session

Throws:

IllegalStateException - if this method is called in an invalid environment.

Since:

WAS XD 6.1.0.3

setSessionHandle

void setSessionHandle(SessionHandle target)
                      throws TargetNotAvailableException

Apply a SessionHandle to this session.

Parameters:

target - the SessionHandle to apply or null to disassociate a SessionHandle from this session.

Throws:

TargetNotAvailableException - when the target is no longer available.

IllegalStateException - if the Session has modified some maps already and the SessionHandle has already been set or if this method is called in an invalidate environment.

Since:

WAS XD 6.1.0.3

setRequestRetryTimeout

void setRequestRetryTimeout(long requestRetryTimeout)

Set the request retry timeout to indicate how long to retry a request (in milliseconds) when recoverable failures occur, such as fail-over exceptions. A request will timeout when either the request timeout expires or the transaction timeout expires, whichever expires first.

A value of 0 indicates that all requests should fail immediately and avoid any retry logic. Exceptions that cannot succeed even if tried again such as DuplicateKeyException exceptions will be thrown immediately.

A value of -1 indicates that the request retry timeout is not set, meaning that the request duration is governed by the request retry timeout set on the ClientProperties. If the ClientProperties is also set to -1, then the request retry timeout is governed by the transaction timeout.

Parameters:

requestRetryTimeout - the duration in milliseconds retry a client request, 0 if the request should fail immediately or -1 if the request timeout is not set.

Since:

7.0

See Also:

ClientProperties.setRequestRetryTimeout(long), setTransactionTimeout(int)

getRequestRetryTimeout

long getRequestRetryTimeout()

Retrieves the current request retry timeout for this session. Returns -1 if it was not set.

Returns:

the duration in milliseconds retry a client request, 0 if the request should fail immediately or -1 if the request timeout is not set.

Since:

7.0

isSessionHandleSet

boolean isSessionHandleSet()

Determines if a SessionHandle is currently set on this Session.

Returns:

true if a SessionHandle is currently set on this session.

Since:

7.1

close

void close()

Closes this session, freeing all resources that are held. Once closed, this session must be discarded. Use one of the ObjectGrid.getSession() methods to retrieve a new session. If the session has an active transaction, the transaction will be rolled back and the session resources are not freed.

Throws:

ObjectGridRuntimeException - thrown if there is a problem releasing resources held by this session.

Since:

7.1.1

setTxCommitProtocol

void setTxCommitProtocol(Session.TxCommitProtocol protocol)

Set the commit protocol to be used when committing this Session's transaction. The constants defined in the TxCommitProtocol enum are the possible commit protocols.

This method should normally be invoked prior to beginning a transaction. Invoking after a transaction has started will result in an exception.

Parameters:

protocol - one of the following constants TxCommitProtocol.ONEPHASE or TxCommitProtocol.TWOPHASE

Since:

WAS XD 8.6

getTxCommitProtocol

Session.TxCommitProtocol getTxCommitProtocol()

Retrieve the current commit protocol for this Session.

Returns:

one of the following constants TxCommitProtocol.ONEPHASE or TxCommitProtocol.TWOPHASE

Since:

WAS XD 8.6