Session (Tentackle Session 8.2.8.0 API)

All Superinterfaces:

Comparable<Session>
```
public interface Session
extends Comparable<Session>
```
The session.
Describes a persistence and security context.

Author:

harald

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`default void`	`applyTo(Collection<? extends SessionDependable> list)` Applies this session to a collection of session dependables.
`default void`	`applyTo(SessionDependable obj)` Applies this session to a session dependable object. The method must invoke `obj.setSession()` only if the session really differs.
`static void`	`assertCurrentSessionValid()` Asserts that a thread local session is set.
`long`	`begin()` Starts a transaction. Does nothing if a transaction is already running!
`long`	`begin(String txName)` Starts a transaction. Does nothing if a transaction is already running!
`default void`	`clearCurrent()` Clears the current session if this session is current.
`Session`	`clone()` Clones a session. If the session is closed, a PersistenceException is thrown. The cloned session will always be non-grouped.
`void`	`close()` Close a session. Closing an already closed session is okay and ignored.
`boolean`	`commit(long txVoucher)` Commits a transaction if the corresponding begin() has started it.
`static Session`	`getCurrentSession()` Gets the session used by the current thread.
`SessionTaskDispatcher`	`getDispatcher()` Gets the dispatcher for this session. The dispatcher can be used to submit asynchroneous tasks in a serial manner.
`int`	`getInstanceNumber()` Gets the unique instance number of this Session.
`long`	`getKeepAliveInterval()` Gets the auto keep alive interval.
`String`	`getName()` Gets the session's name.
`Thread`	`getOwnerThread()` Gets the owner thread.
`SessionPool`	`getPool()` Gets the session pool.
`<T extends Serializable> T`	`getProperty(String key)` Gets a session property.
`RemoteSession`	`getRemoteSession()` Gets the remote session.
`static Session`	`getSession()` Gets the thread local session.
`int`	`getSessionGroupId()` Gets the session's group ID.
`int`	`getSessionId()` Gets the session ID.
`SessionInfo`	`getSessionInfo()` Gets the current user info.
`String`	`getTxName()` Gets the transaction name if a tx is currently running.
`String`	`getUrl()` Gets the url.
`int`	`groupWith(int sessionId)` Assigns this session to another session building a session group.
`boolean`	`isAlive()` Checks whether the session is still in use.
`default boolean`	`isCurrent()` Returns whether this session is the thread's local current session.
`boolean`	`isOpen()` Gets the connection state.
`boolean`	`isPooled()` Checks whether this session is pooled.
`boolean`	`isRemote()` Gets the persistence locality of this session. Sessions may refer to persistence layers not running in the current JVM.
`boolean`	`isTxRunning()` Determines whether a tx is currently running.
`default void`	`makeCurrent()` Makes this session the current session for this thread.
`void`	`open()` Opens a session. Opening an already open session throws a `PersistenceException`.
`void`	`releaseSavepoint(SavepointHandle handle)` Removes the specified `Savepoint` and subsequent `Savepoint` objects from the current transaction.
`void`	`reOpen()` Re-opens a session. If the session is open, it will be closed first. If the session belongs to a group, the re-opened session will be grouped as well.
`boolean`	`rollback(long txVoucher)` Rolls back a transaction if the corresponding begin() has started it. The rollback is logged as INFO along with all statements.
`void`	`rollback(SavepointHandle handle)` Undoes all changes made after the given `Savepoint` object was set.
`boolean`	`rollbackSilently(long txVoucher)` Rolls back a transaction if the corresponding begin() has started it. Same as `rollback(long)` but without logging.
`void`	`setAlive(boolean alive)` Sets the session's alive state.
`static void`	`setCurrentSession(Session session)` Sets the session used by the current thread. The session is stored as `ThreadLocal`.
`void`	`setKeepAliveInterval(long keepAliveInterval)` Sets the auto keep alive interval. If set, the session will be setAlive every keepAliveInterval milliseconds by the `SessionKeepAliveDaemon`.
`void`	`setOwnerThread(Thread ownerThread)` Sets the exclusive owner thread.
`<T extends Serializable> T`	`setProperty(String key, T value)` Sets a session property. Session properties are application specific. For remote sessions, the properties are delegated to the corresponding local session at the remote side.
`SavepointHandle`	`setSavepoint()` Creates an unnamed savepoint in the current transaction.
`SavepointHandle`	`setSavepoint(String name)` Creates a savepoint with the given name in the current transaction.
`<T,E extends Exception> T`	`transaction(Provider<T,E> txe)` Runs code within a transaction. The transaction name is derived from the enclosing method.
`<T,E extends Exception> T`	`transaction(String txName, Provider<T,E> txe)` Runs code within a transaction.

Methods inherited from interface java.lang.Comparable
compareTo

- Method Detail
  - getCurrentSession
```
static Session getCurrentSession()
```
    Gets the session used by the current thread.
    
    Returns:
    
    the session, null if current thread is not using a session
  - setCurrentSession
```
static void setCurrentSession(Session session)
```
    Sets the session used by the current thread.
    The session is stored as ThreadLocal.
    
    Parameters:
    
    session - the db
  - assertCurrentSessionValid
```
static void assertCurrentSessionValid()
```
    Asserts that a thread local session is set.
    
    Throws:
    
    PersistenceException - if thread-local session is null
  - getSession
```
static Session getSession()
```
    Gets the thread local session.
    
    Returns:
    
    the session, never null
    
    Throws:
    
    PersistenceException - if thread-local session is null
  - makeCurrent
```
default void makeCurrent()
```
    Makes this session the current session for this thread.
  - isCurrent
```
default boolean isCurrent()
```
    Returns whether this session is the thread's local current session.
    
    Returns:
    
    true if this is the current session
  - clearCurrent
```
default void clearCurrent()
```
    Clears the current session if this session is current.
    
    Throws:
    
    PersistenceException - if this is not the current session
  - applyTo
```
default void applyTo(SessionDependable obj)
```
    Applies this session to a session dependable object.
    The method must invoke obj.setSession() only if the session really differs. This prevents infinite loops in object circular references.
    
    Parameters:
    
    obj - the database object, null if ignore
  - applyTo
```
default void applyTo(Collection<? extends SessionDependable> list)
```
    Applies this session to a collection of session dependables.
    
    Parameters:
    
    list - the collection of session dependables
  - getName
```
String getName()
```
    Gets the session's name.
    
    Returns:
    
    the session's name
  - getSessionId
```
int getSessionId()
```
    Gets the session ID.
    
    Returns:
    
    the ID assigned to this session
  - getSessionGroupId
```
int getSessionGroupId()
```
    Gets the session's group ID.
    
    Returns:
    
    the group id, 0 if not member of a session group
  - groupWith
```
int groupWith(int sessionId)
```
    Assigns this session to another session building a session group.
    
    Parameters:
    
    sessionId - the ID of the session to build a group with
    
    Returns:
    
    the group id
  - open
```
void open()
```
    Opens a session.
    Opening an already open session throws a PersistenceException.
  - close
```
void close()
```
    Close a session.
    Closing an already closed session is okay and ignored.
    Notice: a non-blocking close can be requested by setKeepAliveInterval(long) with an interval < 0.
  - clone
```
Session clone()
```
    Clones a session.
    If the session is closed, a PersistenceException is thrown.
    The cloned session will always be non-grouped.
    
    Returns:
    
    the cloned session
  - reOpen
```
void reOpen()
```
    Re-opens a session.
    If the session is open, it will be closed first.
    If the session belongs to a group, the re-opened session will be grouped as well.
  - getSessionInfo
```
SessionInfo getSessionInfo()
```
    Gets the current user info.
    
    Returns:
    
    the SessionInfo
  - begin
```
long begin(String txName)
```
    Starts a transaction.
    Does nothing if a transaction is already running!
    
    Parameters:
    
    txName - is the optional transaction name, null if none
    
    Returns:
    
    the tx-voucher, 0 if no tx begun
  - begin
```
long begin()
```
    Starts a transaction.
    Does nothing if a transaction is already running!
    
    Returns:
    
    the tx-voucher, 0 if no tx begun
  - commit
```
boolean commit(long txVoucher)
```
    Commits a transaction if the corresponding begin() has started it.
    
    Parameters:
    
    txVoucher - the transaction voucher, 0 if ignore (nested tx)
    
    Returns:
    
    true if tx was really committed, false if not.
  - rollback
```
boolean rollback(long txVoucher)
```
    Rolls back a transaction if the corresponding begin() has started it.
    The rollback is logged as INFO along with all statements.
    
    Parameters:
    
    txVoucher - the transaction voucher, 0 if ignore (nested tx)
    
    Returns:
    
    true if tx was really rolled back, false if not.
  - rollbackSilently
```
boolean rollbackSilently(long txVoucher)
```
    Rolls back a transaction if the corresponding begin() has started it.
    Same as rollback(long) but without logging. Used for expected rollbacks or rollbacks not related to persistence exceptions.
    
    Parameters:
    
    txVoucher - the transaction voucher, 0 if ignore (nested tx)
    
    Returns:
    
    true if tx was really rolled back, false if not.
  - isTxRunning
```
boolean isTxRunning()
```
    Determines whether a tx is currently running.
    
    Returns:
    
    true if tx running.
  - getTxName
```
String getTxName()
```
    Gets the transaction name if a tx is currently running.
    
    Returns:
    
    the tx name, null if none or no tx running.
    
    See Also:
    
    isTxRunning()
  - transaction
```
<T,E extends Exception> T transaction(String txName,
                                      Provider<T,E> txe)
                               throws E extends Exception
```
    Runs code within a transaction.
    Provided as an alternative to the @Transaction-interceptor, if the class holding the implementation of the transaction is not an Interceptable.
    Usage:
```
 return session.transaction(() -> {
    ..do something..
    return whatever;
 });
 
```
    whatever is returned by session.transaction(). The type is determined by type inference automatically. If there is nothing to return, null must be returned by the envelope:
```
 session.transaction(() -> {
    ..do something..
    return null;
 });
 
```
    The exception is optional. If given, it can be caught as if there was no lambda.
```
 try {
   session.transaction(() -> {
     throw new MyException("blah");
   });
 }
 catch (MyException ex) {
   ...
 }
 
```
    Type Parameters:
    
    T - the return type
    
    E - the exception type
    
    Parameters:
    
    txName - the transaction name, null will derive it from enclosing method
    
    txe - the transaction supplier
    
    Returns:
    
    the return value of the transaction supplier
    
    Throws:
    
    E - the exception type
    
    E extends Exception
  - transaction
```
<T,E extends Exception> T transaction(Provider<T,E> txe)
                               throws E extends Exception
```
    Runs code within a transaction.
    The transaction name is derived from the enclosing method.
    
    Type Parameters:
    
    T - the return type
    
    E - the exception type
    
    Parameters:
    
    txe - the transaction supplier
    
    Returns:
    
    the return value of the supplier
    
    Throws:
    
    E - the exception type
    
    E extends Exception
  - setSavepoint
```
SavepointHandle setSavepoint()
```
    Creates an unnamed savepoint in the current transaction.
    
    Returns:
    
    the savepoint handle unique within current transaction
  - setSavepoint
```
SavepointHandle setSavepoint(String name)
```
    Creates a savepoint with the given name in the current transaction.
    
    Parameters:
    
    name - the savepoint name
    
    Returns:
    
    the savepoint handle unique within current transaction
  - rollback
```
void rollback(SavepointHandle handle)
```
    Undoes all changes made after the given Savepoint object was set.
    
    Parameters:
    
    handle - the savepoint handle
  - releaseSavepoint
```
void releaseSavepoint(SavepointHandle handle)
```
    Removes the specified Savepoint and subsequent Savepoint objects from the current transaction.
    
    Parameters:
    
    handle - the savepoint handle
  - getInstanceNumber
```
int getInstanceNumber()
```
    Gets the unique instance number of this Session.
    
    Returns:
    
    the instance number
  - setOwnerThread
```
void setOwnerThread(Thread ownerThread)
```
    Sets the exclusive owner thread.
    Allows to detect other threads accidently using this session.
    
    Parameters:
    
    ownerThread - the owner thread, null to clear
  - getOwnerThread
```
Thread getOwnerThread()
```
    Gets the owner thread.
    
    Returns:
    
    the exclusive thread, null if none
  - setAlive
```
void setAlive(boolean alive)
```
    Sets the session's alive state.
    
    Parameters:
    
    alive - is true to signal it's alive, false to clear
  - isAlive
```
boolean isAlive()
```
    Checks whether the session is still in use.
    
    Returns:
    
    true if session still in use, false if not used since last setAlive(false).
  - setKeepAliveInterval
```
void setKeepAliveInterval(long keepAliveInterval)
```
    Sets the auto keep alive interval.
    If set, the session will be setAlive every keepAliveInterval milliseconds by the SessionKeepAliveDaemon. Useful for remote sessions to prevent them from being closed by the remote server due to timeout.
    
    Parameters:
    
    keepAliveInterval - the interval in ms, 0 to disable, < 0 to close session
  - getKeepAliveInterval
```
long getKeepAliveInterval()
```
    Gets the auto keep alive interval.
    
    Returns:
    
    the interval in ms, 0 if disabled
  - isPooled
```
boolean isPooled()
```
    Checks whether this session is pooled.
    
    Returns:
    
    true if pooled, false if not pooled
  - getPool
```
SessionPool getPool()
```
    Gets the session pool.
    
    Returns:
    
    the db pool, null = not pooled
  - isOpen
```
boolean isOpen()
```
    Gets the connection state.
    
    Returns:
    
    true if session is open, else false
  - isRemote
```
boolean isRemote()
```
    Gets the persistence locality of this session.
    Sessions may refer to persistence layers not running in the current JVM. A session is called remote if the physical connection to the database backend is located in another JVM. It is called local if the backend is connected to the current JVM.
    
    Returns:
    
    true if remote, false if local
    
    See Also:
    
    getRemoteSession()
  - getRemoteSession
```
RemoteSession getRemoteSession()
```
    Gets the remote session.
    
    Returns:
    
    the remote session
    
    Throws:
    
    PersistenceException - if session is not remote
    
    See Also:
    
    isRemote()
  - getUrl
```
String getUrl()
```
    Gets the url.
    
    Returns:
    
    the url
  - getDispatcher
```
SessionTaskDispatcher getDispatcher()
```
    Gets the dispatcher for this session.
    The dispatcher can be used to submit asynchroneous tasks in a serial manner. The returned dispatcher is configured to shutdown if idle for a given timeout.
    
    Returns:
    
    the dispatcher
  - setProperty
```
<T extends Serializable> T setProperty(String key,
                                       T value)
```
    Sets a session property.
    Session properties are application specific.
    For remote sessions, the properties are delegated to the corresponding local session at the remote side. Thus, session properties can be used to share some application state between the client and the server.
    
    Type Parameters:
    
    T - the value's type
    
    Parameters:
    
    key - the property key
    
    value - the property value
    
    Returns:
    
    the old value, null if key is new
  - getProperty
```
<T extends Serializable> T getProperty(String key)
```
    Gets a session property.
    
    Type Parameters:
    
    T - the value's type
    
    Parameters:
    
    key - the property key
    
    Returns:
    
    the property value, null if no such property

Interface Session

Method Summary

Methods inherited from interface java.lang.Comparable

Method Detail

getCurrentSession

setCurrentSession

assertCurrentSessionValid

getSession

makeCurrent

isCurrent

clearCurrent

applyTo

applyTo

getName

getSessionId

getSessionGroupId

groupWith

open

close

clone

reOpen

getSessionInfo

begin

begin

commit

rollback

rollbackSilently

isTxRunning

getTxName

transaction

transaction

setSavepoint

setSavepoint

rollback

releaseSavepoint

getInstanceNumber

setOwnerThread

getOwnerThread

setAlive

isAlive

setKeepAliveInterval

getKeepAliveInterval

isPooled

getPool

isOpen

isRemote

getRemoteSession

getUrl

getDispatcher

setProperty

getProperty