Module org.tentackle.session
Package org.tentackle.session

Interface Session

All Superinterfaces:
AutoCloseable, Comparable<Session>
public interface Session extends Comparable<Session>, AutoCloseable
The session.
Describes a persistence and security context.
Author:
harald

  • Method Summary

    Modifier and Type
    Method
    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!
    long
    begin(String txName, TransactionIsolation transactionIsolation, TransactionWritability transactionWritability)
    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(String sessionName)
    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.
    If this session is the root of a session group, all grouped sessions will be ungrouped.
    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 asynchronous 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.
    The session group is unique for sessions with the same URL.
    int
    getSessionId()
    Gets the session ID.
    Session IDs are unique for sessions with the same URL.
    For remote sessions, the ID is the same as the one used in remote server.
    SessionInfo
    getSessionInfo()
    Gets the current session info.
    String
    getTxName()
    Gets the transaction name if a tx is currently running.
    String
    getUrl()
    Gets the connection url.
    void
    groupWith(int sessionId)
    Assigns this session to another session building a session group.
    If the referenced session already belongs to a group, this session will be added to that 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 session's 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
    postCommit(Consumer<Session> postCommit)
    Registers a post commit.
    Post commits are invoked after the successful physical commit of a transaction.
    boolean
    registerCloseHandler(SessionCloseHandler closeHandler)
    Registers a close handler.
    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(String txName, Provider<T,E> txe)
    Runs code within a 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.
    boolean
    unregisterCloseHandler(SessionCloseHandler closeHandler)
    Unregisters a close handler.

    Methods inherited from interface java.lang.Comparable

    compareTo

  • Method Details

    • 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.
      Session IDs are unique for sessions with the same URL.
      For remote sessions, the ID is the same as the one used in remote server.
      Returns:
      the ID assigned to this session
      See Also:

    • getSessionGroupId

      int getSessionGroupId()
      Gets the session's group ID.
      The session group is unique for sessions with the same URL.
      Returns:
      the ID of the session this session is grouped with, 0 if not member of a session group

    • groupWith

      void groupWith(int sessionId)
      Assigns this session to another session building a session group.
      If the referenced session already belongs to a group, this session will be added to that group. If the referenced session does not belong to a group, it will become the root session of the group and the group id will be the session id of the root session.
      Parameters:
      sessionId - the ID of the session to build a group with

    • close

      void close()
      Close a session.
      Closing an already closed session is okay and ignored.
      If this session is the root of a session group, all grouped sessions will be ungrouped.

      Notice: a non-blocking close can be requested by setKeepAliveInterval(long) with an interval < 0.

      Specified by:
      close in interface AutoCloseable

    • registerCloseHandler

      boolean registerCloseHandler(SessionCloseHandler closeHandler)
      Registers a close handler.
      Parameters:
      closeHandler - the handler
      Returns:
      true if added, false if already registered

    • unregisterCloseHandler

      boolean unregisterCloseHandler(SessionCloseHandler closeHandler)
      Unregisters a close handler.
      Parameters:
      closeHandler - the handler
      Returns:
      true if removed, false if not registered

    • clone

      Session clone(String sessionName)
      Clones a session.
      If the session is closed, a PersistenceException is thrown.
      The cloned session will always be non-grouped.
      Parameters:
      sessionName - the name of the cloned session, null if same as this session
      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. If this session is the root of a session group, all grouped sessions will be ungrouped.

    • getSessionInfo

      SessionInfo getSessionInfo()
      Gets the current session info.
      Returns:
      the session info

    • begin

      long begin(String txName, TransactionIsolation transactionIsolation, TransactionWritability transactionWritability)
      Starts a transaction.
      Does nothing if a transaction is already running!

      If a transaction is already running and the transactionIsolation or readOnly mode does not correspond to the values at the effective beginning of the transaction, a PersistenceException is thrown.

      Parameters:
      txName - is the optional transaction name, null if none
      transactionIsolation - the transaction isolation level, null or TransactionIsolation.DEFAULT if default
      transactionWritability - the transaction writabilty, null or TransactionWritability.DEFAULT if default
      Returns:
      the tx-voucher, 0 if no tx begun

    • 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:

    • transaction

      <T, E extends Exception> T transaction(String txName, Provider<T,E> txe) throws E
      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

    • transaction

      <T, E extends Exception> T transaction(Provider<T,E> txe) throws E
      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

    • 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 accidentally 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 session's 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

      RemoteSession getRemoteSession()
      Gets the remote session.
      Returns:
      the remote session
      Throws:
      PersistenceException - if session is not remote
      See Also:

    • getUrl

      String getUrl()
      Gets the connection url.
      Returns:
      the url

    • getDispatcher

      SessionTaskDispatcher getDispatcher()
      Gets the dispatcher for this session.
      The dispatcher can be used to submit asynchronous tasks in a serial manner. The returned dispatcher is configured to shut down 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

    • postCommit

      void postCommit(Consumer<Session> postCommit)
      Registers a post commit.
      Post commits are invoked after the successful physical commit of a transaction. They must be registered from within a transactional method, i.e. the transaction must be running.
      They are executed in reverse order of their registration, which is the expected behavior for nested transactions.
      Post commits are intended for non-transactional purposes, such as firing events. They must not be used to directly or indirectly invoke other transactional methods that in turn register post commits.
      Parameters:
      postCommit - the post commit