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

Interface Session

  • All Superinterfaces:
    java.lang.AutoCloseable, java.lang.Comparable<Session>
    public interface Session
extends java.lang.Comparable<Session>, java.lang.AutoCloseable
    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 Description
      default void applyTo​(java.util.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​(java.lang.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.
      java.lang.String getName()
      Gets the session's name.
      java.lang.Thread getOwnerThread()
      Gets the owner thread.
      SessionPool getPool()
      Gets the session pool.
      <T extends java.io.Serializable>
      T      		 getProperty​(java.lang.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.
      java.lang.String getTxName()
      Gets the transaction name if a tx is currently running.
      java.lang.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.
      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​(java.lang.Thread ownerThread)
      Sets the exclusive owner thread.
      <T extends java.io.Serializable>
      T      		 setProperty​(java.lang.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​(java.lang.String name)
      Creates a savepoint with the given name in the current transaction.
      <T,​E extends java.lang.Exception>
      T      		 transaction​(java.lang.String txName, org.tentackle.misc.Provider<T,​E> txe)
      Runs code within a transaction.
      <T,​E extends java.lang.Exception>
      T      		 transaction​(org.tentackle.misc.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 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​(java.util.Collection<? extends SessionDependable> list)
        Applies this session to a collection of session dependables.
        Parameters:
        list - the collection of session dependables

      • getName

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

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

        Specified by:
        close in interface java.lang.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()
        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​(java.lang.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

        java.lang.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 java.lang.Exception> T transaction​(java.lang.String txName,
                                                      org.tentackle.misc.Provider<T,​E> txe)
                                               throws E extends java.lang.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 java.lang.Exception

      • transaction

        <T,​E extends java.lang.Exception> T transaction​(org.tentackle.misc.Provider<T,​E> txe)
                                               throws E extends java.lang.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 java.lang.Exception

      • setSavepoint

        SavepointHandle setSavepoint()
        Creates an unnamed savepoint in the current transaction.
        Returns:
        the savepoint handle unique within current transaction

      • setSavepoint

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

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

      • getUrl

        java.lang.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 java.io.Serializable> T setProperty​(java.lang.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 java.io.Serializable> T getProperty​(java.lang.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