Module org.postgresql.pljava
Package org.postgresql.pljava

Interface Session

  • public interface Session
    A Session brings together some useful methods and data for the current database session. It provides a set of attributes (a String to Object map). Until PL/Java 1.2.0, its attribute store had transactional behavior (i.e., the data added since the last commit would be lost on a transaction rollback, or kept after a commit), but in 1.2.0 and later, it has not, and has functioned as a Map with no awareness of transactions. Java already provides those, so the attribute-related methods of Session are now deprecated. TransactionListeners and SavepointListeners are available for use by any code that needs to synchronize some state with PostgreSQL transactions.
    Author:
    Thomas Hallgren

    • Method Summary

      Modifier and Type Method Description
      void addSavepointListener​(SavepointListener listener)
      Adds the specified listener to the list of listeners that will receive savepoint events.
      void addTransactionListener​(TransactionListener listener)
      Adds the specified listener to the list of listeners that will receive transaction events.
      void executeAsOuterUser​(Connection conn, String statement)
      Execute a statement as the outer user rather than the effective user.
      void executeAsSessionUser​(Connection conn, String statement)
      Deprecated, for removal: This API element is subject to removal in a future version.
      As of 1.5.0, this method is retained only for compatibility with old code, and has the same effect as executeAsOuterUser, which should be used instead.
      Object getAttribute​(String attributeName)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Session's attribute store once had a special, and possibly useful, transactional behavior, but since PL/Java 1.2.0 it has lacked that, and offers nothing you don't get with an ordinary Map (that forbids nulls).
      <T extends PooledObject>
      ObjectPool<T>      		 getObjectPool​(Class<T> cls)
      Return an object pool for the given class.
      String getOuterUserName()
      Return the outer database user name.
      String getSessionUserName()
      Deprecated, for removal: This API element is subject to removal in a future version.
      As of 1.5.0, this method is retained only for compatibility with old code, and returns the same value as getOuterUserName, which should be used instead.
      String getUserName()
      Return the current effective database user name.
      void removeAttribute​(String attributeName)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Session's attribute store once had a special, and possibly useful, transactional behavior, but since PL/Java 1.2.0 it has lacked that, and offers nothing you don't get with an ordinary Map (that forbids nulls).
      void removeSavepointListener​(SavepointListener listener)
      Removes the specified listener from the list of listeners that will receive savepoint events.
      void removeTransactionListener​(TransactionListener listener)
      Removes the specified listener from the list of listeners that will receive transaction events.
      void setAttribute​(String attributeName, Object value)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Session's attribute store once had a special, and possibly useful, transactional behavior, but since PL/Java 1.2.0 it has lacked that, and offers nothing you don't get with an ordinary Map (that forbids nulls).

    • Method Detail

      • addSavepointListener

        void addSavepointListener​(SavepointListener listener)
        Adds the specified listener to the list of listeners that will receive savepoint events. An AccessControlContext saved by this method will be used when the listener is invoked. If the listener was already registered, it remains registered just once, though the AccessControlContext is updated and its order of invocation relative to other listeners may change.
        Parameters:
        listener - The listener to be added.

      • addTransactionListener

        void addTransactionListener​(TransactionListener listener)
        Adds the specified listener to the list of listeners that will receive transaction events. An AccessControlContext saved by this method will be used when the listener is invoked. If the listener was already registered, it remains registered just once, though the AccessControlContext is updated and its order of invocation relative to other listeners may change.
        Parameters:
        listener - The listener to be added.

      • getAttribute

        @Deprecated(since="1.5.3",
            forRemoval=true)
Object getAttribute​(String attributeName)
        Deprecated, for removal: This API element is subject to removal in a future version.
        Session's attribute store once had a special, and possibly useful, transactional behavior, but since PL/Java 1.2.0 it has lacked that, and offers nothing you don't get with an ordinary Map (that forbids nulls). If some kind of store with transactional behavior is needed, it should be implemented in straight Java and kept in sync by using a TransactionListener.
        Obtain an attribute from the current session.
        Parameters:
        attributeName - The name of the attribute
        Returns:
        The value of the attribute

      • getObjectPool

        <T extends PooledObject> ObjectPool<T> getObjectPool​(Class<T> cls)
        Return an object pool for the given class.
        Parameters:
        cls - The class of object to be managed by this pool. It must implement the interface PooledObject and have an accessible constructor for one argument of type ObjectPool.
        Returns:
        An object pool that pools object of the given class.

      • getUserName

        String getUserName()
        Return the current effective database user name.

        Definition: "The one to use for all normal permissions-checking purposes." Within SECURITY DEFINER functions and some specialized commands, it can be different from the outer user name.

      • getOuterUserName

        String getOuterUserName()
        Return the outer database user name.

        Definition: "the current user ID in effect at the 'outer level' (outside any transaction or function)." The session user id taking into account any SET ROLE in effect. This is the ID that a SECURITY DEFINER function should revert to if it needs to operate with the invoker's permissions.

        Since:
        1.5.0

      • getSessionUserName

        @Deprecated(since="1.5.0",
            forRemoval=true)
String getSessionUserName()
        Deprecated, for removal: This API element is subject to removal in a future version.
        As of 1.5.0, this method is retained only for compatibility with old code, and returns the same value as getOuterUserName, which should be used instead. Previously, it returned the session ID unconditionally, which is incorrect for any PostgreSQL version newer than 8.0, because it was unaware of SET ROLE introduced in 8.1. Any actual use case for a method that ignores roles and reports only the session ID should be reported as an issue.
        Deprecated synonym for getOuterUserName.

      • executeAsOuterUser

        void executeAsOuterUser​(Connection conn,
                        String statement)
                 throws SQLException
        Execute a statement as the outer user rather than the effective user. This is useful when functions declared using SECURITY DEFINER wants to give up the definer rights.
        Parameters:
        conn - The connection used for the execution
        statement - The statement to execute
        Throws:
        SQLException - if something goes wrong when executing.
        See Also:
        Statement.execute(java.lang.String)

      • executeAsSessionUser

        @Deprecated(since="1.5.0",
            forRemoval=true)
void executeAsSessionUser​(Connection conn,
                          String statement)
                   throws SQLException
        Deprecated, for removal: This API element is subject to removal in a future version.
        As of 1.5.0, this method is retained only for compatibility with old code, and has the same effect as executeAsOuterUser, which should be used instead. Previously, it used the session ID unconditionally, which is incorrect for any PostgreSQL version newer than 8.0, because it was unaware of SET ROLE introduced in 8.1. Any actual use case for a method that ignores roles and uses only the session ID should be reported as an issue.
        Deprecated synonym for executeAsOuterUser.
        Throws:
        SQLException

      • removeAttribute

        @Deprecated(since="1.5.3",
            forRemoval=true)
void removeAttribute​(String attributeName)
        Deprecated, for removal: This API element is subject to removal in a future version.
        Session's attribute store once had a special, and possibly useful, transactional behavior, but since PL/Java 1.2.0 it has lacked that, and offers nothing you don't get with an ordinary Map (that forbids nulls). If some kind of store with transactional behavior is needed, it should be implemented in straight Java and kept in sync by using a TransactionListener.
        Remove an attribute previously stored in the session. If no attribute is found, nothing happens.
        Parameters:
        attributeName - The name of the attribute.

      • removeSavepointListener

        void removeSavepointListener​(SavepointListener listener)
        Removes the specified listener from the list of listeners that will receive savepoint events. This method does nothing unless the listener is found.
        Parameters:
        listener - The listener to be removed.

      • removeTransactionListener

        void removeTransactionListener​(TransactionListener listener)
        Removes the specified listener from the list of listeners that will receive transaction events. This method does nothing unless the listener is found.
        Parameters:
        listener - The listener to be removed.

      • setAttribute

        @Deprecated(since="1.5.3",
            forRemoval=true)
void setAttribute​(String attributeName,
                  Object value)
        Deprecated, for removal: This API element is subject to removal in a future version.
        Session's attribute store once had a special, and possibly useful, transactional behavior, but since PL/Java 1.2.0 it has lacked that, and offers nothing you don't get with an ordinary Map (that forbids nulls). If some kind of store with transactional behavior is needed, it should be implemented in straight Java and kept in sync by using a TransactionListener.
        Set an attribute to a value in the current session.
        Parameters:
        attributeName -
        value -