com.sap.tc.mobile.session.api
Class Session

java.lang.Object
  com.sap.tc.mobile.session.api.Session

All Implemented Interfaces:

java.lang.Cloneable

public abstract class Session
extends java.lang.Object
implements java.lang.Cloneable

Application session. Each user session (e.g., application or background process) holds a Session object, which manages used services in this session. Generally, there is 1:1 mapping of threads and Session instances, but more precisely, each thread of control (may be composed of several alternating threads, e.g., for Tomcat-based applications) is associated with one session.

For example, persistence manager is one service, synchronization another. Instances of these services will be created on-demand on this session and destroyed after session ends.

It is important to get handles to other services from session in session service initializer. This causes building up a unidirectional dependency graph, which is used to commit/rollback/release services in proper order (e.g., first we call commit on synchronization service and at the very last on persistence manager). Handles to sibling services (e.g., sync service called from some kind of application service) don't need to and should not be be obtained at service initialization time to allow for lazy loading.

Each session service implementation must implement SessionService interface.

Sessions are transactional. Each service should use persistence facilities of underlying data store service (i.e., persistency service) and not persist data by itself. Persistence manager can and should be obtained using standardized means in session service initialization. Please see configuration session service implementation for an example of how to get persistence manager.

Please use SessionSPI.createSession() (SPI) to instantiate sessions.

Author:

d039184

See Also:

SessionService, SessionSPI, More information about sessions

Field Summary

protected boolean

invalid Invalid flag on current session's transaction.

Constructor Summary

Session()

Method Summary

abstract void	assertValid() Assert that current session is still valid.
abstract java.lang.Object	clone()
abstract Session	cloneSession() Clone a session.
abstract void	commit() Commit session's changes.
abstract void	commit(boolean toPassive)
abstract void	flushCache() Flush caches
abstract java.lang.String	getProperty(java.lang.String key, java.lang.String defValue) Get user-defined session property.
abstract long	getTimeout() Get timeout for this session.
abstract boolean	hasChanged()
void	invalidate() Invalidate current (sub-)transaction running in the session.
void	invalidateCond(boolean doInvalidate) Invalidate current (sub-)transaction running in the session conditionally.
boolean	isInvalidated() Check whether the (sub-)transaction has been invalidated.
abstract Subtransaction	openSubtrans() Creates a new subtransaction.
abstract void	release() Release the session and all registered services.
abstract void	rollback() Roll back session's changes.
abstract void	setProperty(java.lang.String key, java.lang.String value) Set user-defined session property.
abstract void	setTimeout(long ms) Set timeout for this session.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

invalid

protected boolean invalid

Invalid flag on current session's transaction. Must be reverted by commit/rollback. If invalid is set, commit is not allowed and results in rollback.

Constructor Detail

Session

public Session()

Method Detail

setTimeout

public abstract void setTimeout(long ms)

Set timeout for this session. If no action is done on the session for this period of time, the session will be forcefully released. Normally, persistence manager actions reset the timeout.

Parameters:

ms - timeout in milliseconds.

getTimeout

public abstract long getTimeout()

Get timeout for this session.

Returns:

timeout in milliseconds.

commit

public abstract void commit()

Commit session's changes. If the session has been invalidated, rollback is executed instead and an exception is thrown.

Throws:

java.lang.RuntimeException - subclass of RuntimeException is throws, when commit fails from some reason. In this case, rollback() is executed instead of commit. If more than one exception occurs, all exceptions are chained into one exception to have all stack traces available.

See Also:

invalidate(), invalidateCond(boolean), isInvalidated()

commit

public abstract void commit(boolean toPassive)

flushCache

public abstract void flushCache()

Flush caches

rollback

public abstract void rollback()

Roll back session's changes. If the session has been invalidated, rollback will validate it, so later commits can be executed.

Throws:

java.lang.RuntimeException - subclass of RuntimeException is thrown, when rollback fails from some reason. If more than one exception occurs, all exceptions are chained into one exception to have all stack traces available.

See Also:

invalidate(), invalidateCond(boolean), isInvalidated()

openSubtrans

public abstract Subtransaction openSubtrans()

Creates a new subtransaction. Subtransactions are realized using savepoints on service level. The subtransaction should be properly closed in a finally block.

Returns:

handle of a subtransaction.

See Also:

Subtransaction

release

public abstract void release()

Release the session and all registered services.

Throws:

java.lang.RuntimeException - subclass of RuntimeException is thrown, when release fails for some reason. If release of one module fails, other modules are released nevertheless. If more than one exception occurs, all exceptions are chained into one exception to have all stack traces available.

cloneSession

public abstract Session cloneSession()

Clone a session. This is useful to start a background thread in an application or to generate a second session for starting an application.

Returns:

new session with deeply-copied service handles.

Throws:

java.lang.RuntimeException - subclass of RuntimeException is thrown, when clone fails from some reason.

setProperty

public abstract void setProperty(java.lang.String key,
                                 java.lang.String value)

Set user-defined session property.

Parameters:

key - property key.

value - property value.

getProperty

public abstract java.lang.String getProperty(java.lang.String key,
                                             java.lang.String defValue)

Get user-defined session property.

Parameters:

key - property key.

defValue - default value.

Returns:

property value or default if not set.

invalidate

public final void invalidate()

Invalidate current (sub-)transaction running in the session.

See Also:

invalidateCond(boolean), isInvalidated()

invalidateCond

public final void invalidateCond(boolean doInvalidate)

Invalidate current (sub-)transaction running in the session conditionally. When subtransactions are implemented, invalidateCond can be replaced at many places with yet-to-be defined closeSubtrans(boolean error).

Parameters:

doInvalidate - if true, do the invalidation.

See Also:

invalidate(), isInvalidated()

isInvalidated

public final boolean isInvalidated()

Check whether the (sub-)transaction has been invalidated.

Returns:

true, if the current (sub-)transaction has been invalidated.

See Also:

invalidate(), invalidateCond(boolean)

assertValid

public abstract void assertValid()

Assert that current session is still valid.

Throws:

java.lang.RuntimeException - if the session is not valid anymore.

clone

public abstract java.lang.Object clone()

Overrides:

clone in class java.lang.Object

hasChanged

public abstract boolean hasChanged()

Returns:

true anything has changed in persistency.