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.

Since:

WAS XD 6.0

See Also:

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

Field Summary

static int	TRANSACTION_NO_TIMEOUT A special value for the timeout parameter of the setTransactionTimeout(int) method.
static java.lang.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	commit() Commits a transaction.
ObjectQuery	createObjectQuery(java.lang.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(java.lang.String cacheName) Returns the ObjectMap for the specified name.
ObjectGrid	getObjectGrid() Returns the ObjectGrid that owns this session.
int	getTransactionTimeout() Gets current transaction timeofut for this Session.
TxID	getTxID() Gets the TxID transaction identifier, if a transaction is active.
ObjectMap	getViewMap(java.lang.String mapName) Get an ObjectMap for the stream query view result map.
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	isWriteThroughEnabled() Returns whether the current session transaction is writing through to the backend Loader or ObjectGrid server(true), or if the changes are only applying to the BackingMap (false) or client respectively.
void	markRollbackOnly(java.lang.Throwable t) Marks the current transaction as being rollback only.
void	processLogSequence(LogSequence logSequence) Processes a LogSequence.
void	rollback() Rolls back a transaction.
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(java.lang.String tranType) Sets the transaction type for future transactions.
boolean	transactionTimedOut() Determines whether the current session transaction has timed out.

Field Detail

TRANSACTION_TYPE_DEFAULT

static final java.lang.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

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(java.lang.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.

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.

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 backend 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(java.lang.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

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(java.lang.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 timeofut 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)

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(java.lang.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".

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.

Returns:

this session's EntityManager instance.

Since:

WAS XD 6.1

getViewMap

ObjectMap getViewMap(java.lang.String mapName)
                     throws UndefinedMapException,
                            ObjectGridRuntimeException

Get an ObjectMap for the stream query view result map. This map will be continuously updated whenever the view changes.

If the ObjectGrid is a client side ObjectGrid, the returned map is a client-side near cache map, and it is also replcated from the server-side map to make sure the near cache reflects the latest data on the server side.

A stream query view ObjectMap is read-only, and should not be updated.

Parameters:

mapName - the view map name

Returns:

a read-only ObjectMap

Throws:

UndefinedMapException - the map is undefined

ObjectGridRuntimeException - the map cannot be replicated from the server if the ObjectGrid represents a client side ObjectGrid.

Since:

WAS XD 6.1