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.
    Properties
    frozenSystemProperties()
    Returns an unmodifiable defensive copy of the Java system properties taken early in PL/Java startup before user code has an opportunity to write them.
    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 Details

    • frozenSystemProperties

      Properties frozenSystemProperties()
      Returns an unmodifiable defensive copy of the Java system properties taken early in PL/Java startup before user code has an opportunity to write them.

      When PL/Java is running without security policy enforcement, as on stock Java 24 and later, using the frozen properties can simplify defensive coding against the possibility of arbitrary property modifications.

      Returns:
      a Properties object that departs from the API spec by throwing UnsupportedOperationException from any method if the properties would otherwise be modified.

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

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