-
public interface Session
A Session brings together some useful methods and data for the current database session. It provides a set of attributes (aString
toObject
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 aMap
with no awareness of transactions. Java already provides those, so the attribute-related methods ofSession
are now deprecated.TransactionListeners
andSavepointListeners
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 specifiedlistener
to the list of listeners that will receive savepoint events.void
addTransactionListener(TransactionListener listener)
Adds the specifiedlistener
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 asexecuteAsOuterUser
, 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 ordinaryMap
(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 asgetOuterUserName
, 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 ordinaryMap
(that forbids nulls).void
removeSavepointListener(SavepointListener listener)
Removes the specifiedlistener
from the list of listeners that will receive savepoint events.void
removeTransactionListener(TransactionListener listener)
Removes the specifiedlistener
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 ordinaryMap
(that forbids nulls).
-
-
-
Method Detail
-
addSavepointListener
void addSavepointListener(SavepointListener listener)
Adds the specifiedlistener
to the list of listeners that will receive savepoint events. AnAccessControlContext
saved by this method will be used when the listener is invoked. If the listener was already registered, it remains registered just once, though theAccessControlContext
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 specifiedlistener
to the list of listeners that will receive transaction events. AnAccessControlContext
saved by this method will be used when the listener is invoked. If the listener was already registered, it remains registered just once, though theAccessControlContext
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 ordinaryMap
(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 aTransactionListener
.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 interfacePooledObject
and have an accessible constructor for one argument of typeObjectPool
.- 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 aSECURITY 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 asgetOuterUserName
, 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 ofSET 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 forgetOuterUserName
.
-
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 usingSECURITY DEFINER
wants to give up the definer rights.- Parameters:
conn
- The connection used for the executionstatement
- 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 asexecuteAsOuterUser
, 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 ofSET 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 forexecuteAsOuterUser
.- 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 ordinaryMap
(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 aTransactionListener
.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 specifiedlistener
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 specifiedlistener
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 ordinaryMap
(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 aTransactionListener
.Set an attribute to a value in the current session.- Parameters:
attributeName
-value
-
-
-