oracle.security.xs

Class XSSessionManager

java.lang.Object

oracle.security.xs.XSSessionManager

public abstract class XSSessionManager
extends java.lang.Object

This class provides functions to manage the Session, inlcude session life cycle (createSession, attachSession, detachSessiona and destroySession), session attribute (cookie, inactivity timeout) and session namespace. It also provides functions to initialize the middle-tier cache and manage it. The following code snippet provides a typical use of this class:

  XSSessionManager manager = XSSessionManager.getSessionManager(cacheConn,
                                                      30, 2048000);

  Session lws = manager.createSession(lwsConn, user, cookie);
  
  manager.attachSession(lws_conn, lws, ...);    
  
  boolean ret = XSAccessController.checkPrivilege(lws, "UPDATE");
  
  manager.detachSession(lws);    
  manager.destroySession(lws);    
  
  
 

Most of the methods in this class are not static, and very security sensitive. The caller has to get hold of an object to call the methods. The object is highly protected. The only way to get the object is to call getSessionManager with followings:

     - XSSecurityPermission ("initSecurityManager") to be granted to the caller's code
     - Dispatcher's DB connection or Datasource
 

In the integration case, we expect only trusted layer (OPSS) can initialize and get hold of the the XSSessionManager object. Application code should not be able to get hold of the object and further invoke most of the methods.

Constructor Summary

Constructors

Constructor and Description
XSSessionManager()

Method Summary

Modifier and Type	Method and Description
abstract void	abortSession(Session session) Detaches this session.
abstract void	assignUser(Session session, ExternalUser targetUser, java.util.Collection<java.lang.String> enabledDynamicRoles, java.util.Collection<java.lang.String> disabledDynamicRoles, java.util.Collection<ExternalRole> externalRoles, java.util.Collection<NamespaceValue> namespaceValues, java.sql.Timestamp authenticationTime) Assigns an external user to the session that was previously created for anonymous user.
abstract void	assignUser(Session session, java.lang.String targetUser, java.util.Collection<java.lang.String> enabledDynamicRoles, java.util.Collection<java.lang.String> disabledDynamicRoles, java.util.Collection<NamespaceValue> namespaceValues, java.sql.Timestamp authenticationTime) Assigns an XS user to the session that was previously created for anonymous user.
abstract void	attachSession(java.sql.Connection conn, Session session, java.util.Collection<java.lang.String> enabledDynamicRoles, java.util.Collection<java.lang.String> disabledDynamicRoles, java.util.Collection<ExternalRole> externalRoles, java.util.Collection<NamespaceValue> namespaceValues, java.sql.Timestamp authenticationTime) Attaches the JDBC connection to the specified XS user's session.
abstract void	attachSession(java.sql.Connection conn, Session session, java.util.Collection<java.lang.String> enabledDynamicRoles, java.util.Collection<java.lang.String> disabledDynamicRoles, java.util.Collection<NamespaceValue> namespaceValues, java.sql.Timestamp authenticationTime) Attaches the JDBC connection to the specified XS user's session.
abstract Session	attachSessionByCookie(java.sql.Connection conn, java.lang.String cookie, java.util.Collection<java.lang.String> enabledDynamicRoles, java.util.Collection<java.lang.String> disabledDynamicRoles, java.util.Collection<ExternalRole> externalRoles, java.util.Collection<NamespaceValue> namespaceValues, java.sql.Timestamp authenticationTime) Attaches the corresponding session for a specified cookie and returns the Session object.
abstract Session	attachSessionByID(java.sql.Connection conn, java.lang.String id, java.util.Collection<java.lang.String> enabledDynamicRoles, java.util.Collection<java.lang.String> disabledDynamicRoles, java.util.Collection<ExternalRole> externalRoles, java.util.Collection<NamespaceValue> namespaceValues, java.sql.Timestamp authenticationTime) Attaches the corresponding session for a specified ID and returns the Session object.
abstract void	clearCache() Explicitly clears the shared cache from the middle tier.
abstract Session	createAnonymousSession(java.sql.Connection conn, java.lang.String cookie, java.util.Collection<NamespaceValue> namespaceValues) Creates an anonymous Session for XS user (to be assigned to) on the server as well as its corresponding middle-tier representation.
abstract Session	createAnonymousSessionTrusted(java.sql.Connection conn, java.lang.String cookie, java.util.Collection<NamespaceValue> namespaceValues) Creates an anonymous Session in trusted mode on the server for external user (to be assigned to) as well as its corresponding middle-tier representation.
abstract SessionNamespaceAttribute	createAttribute(SessionNamespace sessionNS, java.lang.String name, java.lang.String value, java.util.List<SessionNamespace.ATTR_EVENT_TYPE> event) Creates a new attribute in the namespace with the specified name, value, and event.
abstract SessionNamespace	createNamespace(Session session, java.lang.String name) Creates a new namespace for the given session.
abstract Session	createSession(java.sql.Connection conn, ExternalUser externalUser, java.lang.String cookie, java.util.Collection<NamespaceValue> namespaceValues) Creates a Session object for specified external user on the server as well as its corresponding middle-tier representation.
abstract Session	createSession(java.sql.Connection conn, java.lang.String user, java.lang.String cookie, java.util.Collection<NamespaceValue> namespaceValues) Creates a Session object on the server as well as its corresponding midtier representation.
abstract Session	createSessionTrusted(java.sql.Connection conn, ExternalUser externalUser, java.lang.String cookie, java.util.Collection<NamespaceValue> namespaceValues) Creates a Session object for specified external user in trusted mode on the server as well as its corresponding middle-tier representation.
abstract void	deleteAttribute(SessionNamespace sessionNS, java.lang.String name) Deletes the specified attribute The dispatcher needs to have the privilege to delete the given attribute
abstract void	deleteNamespace(Session session, java.lang.String namespace) Removes a namespace from the session.
abstract void	destroySession(java.sql.Connection conn, Session session) Destroys the XS session.
abstract void	detachSession(Session session) Detaches this session.
abstract int	getCacheMaxIdleTime() Returns the maximum number of minutes for which the cache can remain without any activity
abstract long	getCacheMaxSize() Returns the maximum cache size, in bytes.
abstract float	getHighWaterMark() Gets the high watermark for the cache.
abstract float	getLowWaterMark() Gets the low watermark for the cache.
abstract int	getPrivateCacheMaxEntries() Returns the maximum number of entries that the ACL evaluation result can be cached in the session.
static XSSessionManager	getSessionManager(java.sql.Connection conn, int cacheMaxIdleTime, int cacheMaxsize) Initializes an XSSessionManager using a dedicated connections.
static XSSessionManager	getSessionManager(javax.sql.DataSource datasource, int cacheMaxIdleTime, int cacheMaxsize) Initializes an XSSessionManager using connections from the connection pool.
abstract SessionNamespaceAttribute	resetAttribute(SessionNamespace sessionNS, java.lang.String name) Resets the specified attribute in the namespace to its default value.
abstract void	saveSession(Session session) Saves the specified session leaving it attached.
abstract SessionNamespaceAttribute	setAttribute(SessionNamespace sessionNS, java.lang.String name, java.lang.String value) Sets the attribute for a session namespace with the specified name and value The dispatcher needs to have the privilege to set the attribute on the given namespace
abstract void	setCacheMaxIdleTime(int minutes) Sets the maximum number of minutes for which the cache can remain without any activity.
abstract void	setCacheMaxSize(long megaBytes) Sets the size of the cache on the middle tier, in bytes.
abstract void	setCookie(Session session, java.lang.String cookie) Sets the cookie for the session
abstract void	setInactivityTimeout(Session session, int minutes) Sets the inactivity timeout for the session in minutes.
abstract void	setPrivateCacheMaxEntries(int maxEntries) Sets the maximum number of entries that the ACL evaluation result can be cached in the session.
abstract void	setWaterMark(float low, float high) Sets the high and low watermarks for the cache.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XSSessionManager

public XSSessionManager()

Method Detail

createSession

public abstract Session createSession(java.sql.Connection conn,
                                      java.lang.String user,
                                      java.lang.String cookie,
                                      java.util.Collection<NamespaceValue> namespaceValues)
                               throws InvalidXSUserException,
                                      AccessDeniedException,
                                      java.sql.SQLException,
                                      XSException,
                                      InvalidXSNamespaceException

Creates a Session object on the server as well as its corresponding midtier representation. It also creates or changes the Namespace specified in the Session. The cookie can be used to identify the newly created XS user session in future calls, until the cookie value is changed or the session is destroyed. By default, the session is created in secure mode.

Parameters:

conn - the JDBC connection for server roundtrip

user - the XS user associated with the Session

cookie - used to identify the session

namespaceValues - the namespace with attributes The user must have the bindNamespace privilege.

Returns:

session the Session object

Throws:

AccessDeniedException - if the current user does not have the privilege to create this session

java.sql.SQLException - if a JDBC exception happens

InvalidXSUserException - if an invalid XS user is specified

XSException - if a generic error is detected

InvalidXSNamespaceException - if an invalid namespace is specified

See Also:

Session, SessionNamespace

createAnonymousSession

public abstract Session createAnonymousSession(java.sql.Connection conn,
                                               java.lang.String cookie,
                                               java.util.Collection<NamespaceValue> namespaceValues)
                                        throws InvalidXSUserException,
                                               AccessDeniedException,
                                               java.sql.SQLException,
                                               XSException,
                                               InvalidXSNamespaceException

Creates an anonymous Session for XS user (to be assigned to) on the server as well as its corresponding middle-tier representation. It also creates or changes the Namespace specified in the Session. The user for this session is a seeded anonymous user. The cookie can be used to identify the newly created XS user session in future calls, until the cookie value is changed or the session is destroyed. It is possible to assign a specific user to take over this session that will keep some of the state of the session.

By default, the session is created in secure mode.

Parameters:

conn - the JDBC connection for server roundtrip

cookie - used to identify the session

namespaceValues - a list of namespaces with attributes

Returns:

Throws:

AccessDeniedException - if the current user does not have the privilege to create this session

java.sql.SQLException - if a JDBC exception happens

InvalidXSUserException - if an invalid XS user is specified

XSException - if a generic error is detected

InvalidXSNamespaceException - if an invalid namespace is specified

See Also:

Session, SessionNamespace

createAnonymousSessionTrusted

public abstract Session createAnonymousSessionTrusted(java.sql.Connection conn,
                                                      java.lang.String cookie,
                                                      java.util.Collection<NamespaceValue> namespaceValues)
                                               throws InvalidXSUserException,
                                                      AccessDeniedException,
                                                      java.sql.SQLException,
                                                      XSException,
                                                      InvalidXSNamespaceException

Creates an anonymous Session in trusted mode on the server for external user (to be assigned to) as well as its corresponding middle-tier representation. It also creates or changes the Namespace specified in the Session . The session is going to be assigned to an extenal user, which has no footprint at Database, so no database role is enabled in the session. The user for this session is a seeded anonymous user. The cookie can be used to identify the newly created session in future calls, until the cookie value is changed or the session is destroyed. It is possible to assign a specific external user to take over this session that will keep some of the state of the session.

Parameters:

conn - the JDBC connection for server roundtrip

cookie - used to identify the session

namespaceValues - a list of namespaces with attributes

Returns:

Throws:

AccessDeniedException - if the current user does not have the privilege to create this session

java.sql.SQLException - if a JDBC exception happens

InvalidXSUserException - if an invalid XS user is specified

XSException - if a generic error is detected

InvalidXSNamespaceException - if an invalid namespace is specified

See Also:

Session, SessionNamespace

saveSession

public abstract void saveSession(Session session)
                          throws java.sql.SQLException,
                                 NotAttachedException,
                                 XSException

Saves the specified session leaving it attached. It commits all the changes on the session. The changes can be related to namespace, user, role, and other session attributes. For committing changes, this method is same as the detachSession. The only difference is that it does not detach from the connection, but stay attached. This is a server roundtrip.

Parameters:

session, - a Session object

Throws:

java.sql.SQLException

NotAttachedException

XSException

createSessionTrusted

public abstract Session createSessionTrusted(java.sql.Connection conn,
                                             ExternalUser externalUser,
                                             java.lang.String cookie,
                                             java.util.Collection<NamespaceValue> namespaceValues)
                                      throws InvalidXSUserException,
                                             AccessDeniedException,
                                             java.sql.SQLException,
                                             XSException,
                                             InvalidXSNamespaceException

Creates a Session object for specified external user in trusted mode on the server as well as its corresponding middle-tier representation. It also creates or changes the Namespace specified in the Session. The cookie can be used to identify the newly session in future calls, until the cookie value is changed or the session is destroyed.

Parameters:

conn - the JDBC connection for server roundtrip

externalUser - the external user associated with the Session

cookie - used to identify the session

namespaceValues - the namespace with attributes

Returns:

session the Session object

Throws:

AccessDeniedException - if the current user does not have the privilege to create this session

java.sql.SQLException - if a JDBC exception happens

InvalidXSUserException - if an invalid XS user is specified

XSException - if a generic error is detected

InvalidXSNamespaceException - if an invalid namespace is specified

See Also:

Session, SessionNamespace

createSession

public abstract Session createSession(java.sql.Connection conn,
                                      ExternalUser externalUser,
                                      java.lang.String cookie,
                                      java.util.Collection<NamespaceValue> namespaceValues)
                               throws InvalidXSUserException,
                                      AccessDeniedException,
                                      java.sql.SQLException,
                                      XSException,
                                      InvalidXSNamespaceException

Creates a Session object for specified external user on the server as well as its corresponding middle-tier representation. It also creates or changes the Namespace specified for the Session.

The cookie can be used to identify the newly created XS user session in future calls, until the cookie value is changed or the session is destroyed. By default, the session is in secure mode

Parameters:

conn - the JDBC connection for server roundtrip

externalUser - the external user associated with the Session

cookie - used to identify the session

namespaceValues - the namespace with attributes

Returns:

session the Session object

Throws:

AccessDeniedException - if the current user does not have the privilege to create this session

java.sql.SQLException - if a JDBC exception happens

InvalidXSUserException - if an invalid XS user is specified

XSException - if a generic error is detected

InvalidXSNamespaceException - if an invalid namespace is specified

See Also:

Session, SessionNamespace

attachSessionByCookie

public abstract Session attachSessionByCookie(java.sql.Connection conn,
                                              java.lang.String cookie,
                                              java.util.Collection<java.lang.String> enabledDynamicRoles,
                                              java.util.Collection<java.lang.String> disabledDynamicRoles,
                                              java.util.Collection<ExternalRole> externalRoles,
                                              java.util.Collection<NamespaceValue> namespaceValues,
                                              java.sql.Timestamp authenticationTime)
                                       throws java.sql.SQLException,
                                              AccessDeniedException,
                                              InvalidSessionException,
                                              XSException,
                                              InvalidXSNamespaceException

Attaches the corresponding session for a specified cookie and returns the Session object. At same time, changes the dynamic roles, external roles, namespaces, and authentication time on the session. Dynamic roles, external roles, and namespace with attributes are supported in this operation.

Parameters:

conn - the JDBC connection for server roundtrip

cookie - the cookie string

enabledDynamicRoles - the enabled dynamic roles list

disabledDynamicRoles - the disabled dyamic roles list

externalRoles - the external roles list

namespaceValues - the namespaces with attributes.

authenticationTime - the authentication time

Returns:

a Session object

Throws:

AccessDeniedException - if the current user does not have the privilege to create this session

java.sql.SQLException - if a JDBC exception happens

InvalidXSUserException - if an invalid XS user is specified

XSException - if a generic error is detected

InvalidXSNamespaceException - if an invalid namespace is specified

InvalidSessionException

attachSessionByID

public abstract Session attachSessionByID(java.sql.Connection conn,
                                          java.lang.String id,
                                          java.util.Collection<java.lang.String> enabledDynamicRoles,
                                          java.util.Collection<java.lang.String> disabledDynamicRoles,
                                          java.util.Collection<ExternalRole> externalRoles,
                                          java.util.Collection<NamespaceValue> namespaceValues,
                                          java.sql.Timestamp authenticationTime)
                                   throws java.sql.SQLException,
                                          AccessDeniedException,
                                          InvalidSessionException,
                                          XSException,
                                          InvalidXSNamespaceException

Attaches the corresponding session for a specified ID and returns the Session object. At same time, changes the dynamic roles, external roles, namespaces, and authentication time on the session.

Parameters:

conn - the JDBC connection for server roundtrip

id - the session ID of the session

enabledDynamicRoles - the enabled dynamic roles list

disabledDynamicRoles - the disabled dyamic roles list

externalRoles - the external roles list

namespaceValues - the namespaces with attributes.

authenticationTime - the authentication time

Returns:

a Session object

Throws:

AccessDeniedException - if the current user does not have the privilege to create this session

java.sql.SQLException - if a JDBC exception happens

InvalidXSUserException - if an invalid XS user is specified

XSException - if a generic error is detected

InvalidXSNamespaceException - if an invalid namespace is specified

InvalidSessionException

attachSession

public abstract void attachSession(java.sql.Connection conn,
                                   Session session,
                                   java.util.Collection<java.lang.String> enabledDynamicRoles,
                                   java.util.Collection<java.lang.String> disabledDynamicRoles,
                                   java.util.Collection<ExternalRole> externalRoles,
                                   java.util.Collection<NamespaceValue> namespaceValues,
                                   java.sql.Timestamp authenticationTime)
                            throws java.sql.SQLException,
                                   AccessDeniedException,
                                   InvalidSessionException,
                                   XSException,
                                   InvalidXSNamespaceException

Attaches the JDBC connection to the specified XS user's session. At same time,changes the dynamic roles, namespaces, and authentication time on the session.

Parameters:

conn - database connection to be used to attach to the session

session - the session object that needs to be attached

enabledDynamicRoles - a collection of dynamic role names to be enabled

disabledDynamicRoles - a collection of dynamic role names to be disabled

externalRoles - a collection of ExternalRoles to be enabled

namespaceValues - a list of NamespaceAttributeValue objects to be created

authenticationTime - the authenticateion time

Throws:

AccessDeniedException - the current user does not have the privilege to attach to this session

XSException - a generic error is detected

java.sql.SQLException - a JDBC exception is thrown

InvalidSessionException - an attempt is made to reference an invalid session

InvalidXSNamespaceException - if an invalid namespace is specified

See Also:

Session, oracle.security.xs.NamespaceAttributeValue

attachSession

public abstract void attachSession(java.sql.Connection conn,
                                   Session session,
                                   java.util.Collection<java.lang.String> enabledDynamicRoles,
                                   java.util.Collection<java.lang.String> disabledDynamicRoles,
                                   java.util.Collection<NamespaceValue> namespaceValues,
                                   java.sql.Timestamp authenticationTime)
                            throws java.sql.SQLException,
                                   AccessDeniedException,
                                   InvalidSessionException,
                                   XSException,
                                   InvalidXSNamespaceException

Attaches the JDBC connection to the specified XS user's session. At same time, changes the dynamic roles and namespaces on the session.

Parameters:

conn - database connection to be used to attach to the session

session - the session object that needs to be attached

enabledDynamicRoles - a collection of dynamic role names to be enabled

disabledDynamicRoles - a collection of dynamic role names to be disabled

namespaceValues - a list of NamespaceAttributeValue objects to be created

authenticationTime - the authenticateion time

Throws:

AccessDeniedException - the current user does not have the privilege to attach to this session

XSException - a generic error is detected

java.sql.SQLException - a JDBC exception is thrown

InvalidSessionException - an attempt is made to reference an invalid session

InvalidXSNamespaceException - if an invalid namespace is specified

See Also:

Session, oracle.security.xs.NamespaceAttributeValue

detachSession

public abstract void detachSession(Session session)
                            throws java.sql.SQLException,
                                   NotAttachedException,
                                   XSException

Detaches this session. Commits all the changes. A database round trip is required to perform this operation.

Throws:

java.sql.SQLException - a JDBC exception is thrown

XSException - a generic error is detected

NotAttachedException - session not attached

abortSession

public abstract void abortSession(Session session)
                           throws java.sql.SQLException,
                                  NotAttachedException,
                                  XSException

Detaches this session. Rollback all the changes. A database round trip is required to perform this operation.

Throws:

java.sql.SQLException - a JDBC exception is thrown

XSException - a generic error is detected

NotAttachedException - session not attached

destroySession

public abstract void destroySession(java.sql.Connection conn,
                                    Session session)
                             throws java.sql.SQLException,
                                    XSException,
                                    AccessDeniedException,
                                    InvalidSessionException

Destroys the XS session. The destroyed session may no longer be accessed from any JVM. A database round trip is required to perform this operation.

Parameters:

conn - the JDBC Connection used to make a roundtrip operation to the server and destroy the session

Throws:

AccessDeniedException - the current user does not have the privilege to destroy

XSException - a generic error is detected

java.sql.SQLException - a JDBC exception is thrown

InvalidSessionException - an attempt is made to reference an invalid session

assignUser

public abstract void assignUser(Session session,
                                java.lang.String targetUser,
                                java.util.Collection<java.lang.String> enabledDynamicRoles,
                                java.util.Collection<java.lang.String> disabledDynamicRoles,
                                java.util.Collection<NamespaceValue> namespaceValues,
                                java.sql.Timestamp authenticationTime)
                         throws java.sql.SQLException,
                                AccessDeniedException,
                                InvalidSessionException,
                                XSException,
                                InvalidXSNamespaceException

Assigns an XS user to the session that was previously created for anonymous user. At same time, changes the dynamic roles, namespaces, and authentication time on the session.

Parameters:

session - Session obejct to assign user on

targetUser - a user initialized based on authentication

enabledDynamicRoles - a list of dynamic role names to be enabled

disabledDynamicRoles - a list of dynamic role names to be disabled

namespaceValues - a list of NamespaceValue objects to be created.

authenticationTime - a timestamp indicated if the user authenticated

Throws:

AccessDeniedException - the current user does not have the privilege to switchuser

XSException - a generic error is detected

java.sql.SQLException - a JDBC exception is thrown

InvalidSessionException - an attempt is made to reference an invalid session

InvalidXSUserException - an invalid XS user is specified

NotAttachedException - session not attached

InvalidXSNamespaceException - if an invalid namespace is specified

assignUser

public abstract void assignUser(Session session,
                                ExternalUser targetUser,
                                java.util.Collection<java.lang.String> enabledDynamicRoles,
                                java.util.Collection<java.lang.String> disabledDynamicRoles,
                                java.util.Collection<ExternalRole> externalRoles,
                                java.util.Collection<NamespaceValue> namespaceValues,
                                java.sql.Timestamp authenticationTime)
                         throws java.sql.SQLException,
                                AccessDeniedException,
                                InvalidSessionException,
                                XSException,
                                InvalidXSNamespaceException

Assigns an external user to the session that was previously created for anonymous user. At same time, changes the dynamic roles, external roles, namespace, and authentication time on the session.

Parameters:

session - Session obejct to assign user on

targetUser - a User object initialized based on authentication

enabledDynamicRoles - a list of dynamic role names to be enabled

disabledDynamicRoles - a list of dynamic role names to be disabled

externalRoles - a list of external roles to be granted

namespaceValues - a list of NamespaceAttributeValue objects to be created.

authenticationTime - a timestamp indicated if the user authenticated

Throws:

AccessDeniedException - the current user does not have the privilege to switchuser

XSException - a generic error is detected

java.sql.SQLException - a JDBC exception is thrown

InvalidSessionException - an attempt is made to reference an invalid session

InvalidXSUserException - an invalid XS user is specified

NotAttachedException - session not attached

InvalidXSNamespaceException - if an invalid namespace is specified

clearCache

public abstract void clearCache()
                         throws java.security.AccessControlException,
                                XSSessionManagerException

Explicitly clears the shared cache from the middle tier.

Throws:

java.security.AccessControlException - if security manager is enabled and clearCache XSSecurityPermission is not granted

XSSecurityManagerException - XSSecurityManager is not initialized

XSSessionManagerException

getSessionManager

public static XSSessionManager getSessionManager(javax.sql.DataSource datasource,
                                                 int cacheMaxIdleTime,
                                                 int cacheMaxsize)
                                          throws XSException,
                                                 java.security.NoSuchAlgorithmException,
                                                 java.security.InvalidAlgorithmParameterException,
                                                 java.security.spec.InvalidKeySpecException,
                                                 java.security.InvalidKeyException,
                                                 java.sql.SQLException

Initializes an XSSessionManager using connections from the connection pool. By default, the initialized XSSessionManager will sign the request. So the given connection pool user will be used to authorize the session operations. The caller of this method needs to have initSecurityManager XSSecurityPermission if security manager is enabled.

Parameters:

datasource - the connection pool DateSource for the database connection

cacheMaxIdleTime - maximum amount of time that the cache persists, in minutes, before synchronizing with the server

cacheMaxsize - maximum allowable size, in bytes, of the ACL or SecurityClass cache

Throws:

XSException - a generic error is detected

java.security.NoSuchAlgorithmException - a particular cryptographic algorithm is requested but is not available in the environment

java.security.InvalidAlgorithmParameterException - invalid or inappropriate algorithm parameters

java.security.spec.InvalidKeySpecException - invalid key specifications

java.security.InvalidKeyException - invalid Keys

java.sql.SQLException - a problem in the SQL

getSessionManager

public static XSSessionManager getSessionManager(java.sql.Connection conn,
                                                 int cacheMaxIdleTime,
                                                 int cacheMaxsize)
                                          throws XSException,
                                                 java.security.NoSuchAlgorithmException,
                                                 java.security.InvalidAlgorithmParameterException,
                                                 java.security.spec.InvalidKeySpecException,
                                                 java.security.InvalidKeyException,
                                                 java.sql.SQLException

Initializes an XSSessionManager using a dedicated connections. By default, the initialized XSSessionManager will sign the request. So the given connection will be used to authorize the session operations. The caller of this method needs to have initSecurityManager XSSecurityPermission if security manager is enabled.

Parameters:

conn - decicated JDBC connection

cacheMaxIdleTime - maximum amount of time that the cache persists, in minutes, before synchronizing with the server

cacheMaxsize - maximum allowable size, in bytes, of the ACL or SecurityClass cache

Throws:

XSException - a generic error is detected

java.security.NoSuchAlgorithmException - a particular cryptographic algorithm is requested but is not available in the environment

java.security.InvalidAlgorithmParameterException - invalid or inappropriate algorithm parameters

java.security.spec.InvalidKeySpecException - invalid key specifications

java.security.InvalidKeyException - invalid Keys

java.sql.SQLException - a problem in the SQL

getCacheMaxIdleTime

public abstract int getCacheMaxIdleTime()
                                 throws XSSessionManagerException

Returns the maximum number of minutes for which the cache can remain without any activity

Returns:

maximum number of minutes for which the cache can remain without any activity

Throws:

XSSecurityManagerException - XSSecurityManager is not initialized

XSSessionManagerException

setCacheMaxIdleTime

public abstract void setCacheMaxIdleTime(int minutes)
                                  throws java.security.AccessControlException,
                                         XSSessionManagerException

Sets the maximum number of minutes for which the cache can remain without any activity. The caller of this method needs to have setCacheMaxIdleTime XSSecurityPermission if security manager is enabled.

Parameters:

minutes - the maximum number of minutes for which the cache can remain without any activity

Throws:

java.security.AccessControlException - if missing required permission

XSSecurityManagerException - if XSSecurityManager is not initialized

XSSessionManagerException

getCacheMaxSize

public abstract long getCacheMaxSize()
                              throws XSSessionManagerException

Returns the maximum cache size, in bytes.

Returns:

maximum cache size, in bytes

Throws:

XSSecurityManagerException - if XSSecurityManager is not initialized

XSSessionManagerException

setCacheMaxSize

public abstract void setCacheMaxSize(long megaBytes)
                              throws java.security.AccessControlException,
                                     XSSessionManagerException

Sets the size of the cache on the middle tier, in bytes. The default value is 10MB and the minimum value is 1MB. The caller of this method needs to have setCacheSize XSSecurityPermission if security manager is enabled.

Parameters:

megaBytes - integer value representing cache in bytes

Throws:

java.security.AccessControlException - if missing required permission

XSSecurityManagerException - if XSSecurityManager is not initialized.

XSSessionManagerException

getHighWaterMark

public abstract float getHighWaterMark()
                                throws XSSessionManagerException

Gets the high watermark for the cache. if the cache size reaches high watermark the cache eviction algorithm removes entries until the cache size reaches low watermark.

Throws:

XSSecurityManagerException - if XSSecurityManager is not initialized

XSSessionManagerException

getLowWaterMark

public abstract float getLowWaterMark()
                               throws XSSessionManagerException

Gets the low watermark for the cache. if the cache size reaches high watermark the cache eviction algorithm removes entries until the cache size reaches low watermark.

Throws:

XSSecurityManagerException - if XSSecurityManager is not initialized

XSSessionManagerException

setWaterMark

public abstract void setWaterMark(float low,
                                  float high)
                           throws java.security.AccessControlException,
                                  XSSessionManagerException

Sets the high and low watermarks for the cache. The high watermark value must be in the range of 0.0 to 1.0, and the low watermark value must be lower then the high watermark value. The caller of this method needs to have setWaterMark XSSecurityPermission if security manager is enabled.

Parameters:

low - low watermark value

high - high watermark value

Throws:

java.security.AccessControlException - if missing required permission

XSSecurityManagerException - if XSSecurityManager is not initialized

XSSessionManagerException

getPrivateCacheMaxEntries

public abstract int getPrivateCacheMaxEntries()

Returns the maximum number of entries that the ACL evaluation result can be cached in the session.

setPrivateCacheMaxEntries

public abstract void setPrivateCacheMaxEntries(int maxEntries)
                                        throws java.security.AccessControlException,
                                               XSSessionManagerException

Sets the maximum number of entries that the ACL evaluation result can be cached in the session. The caller of this method needs to have setPrivateCacheMaxEntries XSSecurityPermission if security manager is enabled.

Parameters:

maxEntries - number of cache entries

Throws:

java.security.AccessControlException

XSSessionManagerException

setCookie

public abstract void setCookie(Session session,
                               java.lang.String cookie)
                        throws XSException

Sets the cookie for the session

Parameters:

session - the session to be set

cookie - value of the cookie

Throws:

XSException - a generic error is detected

setInactivityTimeout

public abstract void setInactivityTimeout(Session session,
                                          int minutes)
                                   throws XSException

Sets the inactivity timeout for the session in minutes.

Parameters:

session - the session to be set

minutes - number in minutes

Throws:

XSException - a generic error is detected

createNamespace

public abstract SessionNamespace createNamespace(Session session,
                                                 java.lang.String name)
                                          throws java.sql.SQLException,
                                                 AccessDeniedException,
                                                 XSException,
                                                 InvalidXSNamespaceException,
                                                 InvalidSessionException,
                                                 NotAttachedException

Creates a new namespace for the given session. The createNamespace method creates a new session namespace using the namespace template document, whose name matches with the specified name. If an event handler is defined in the template document, then the defined event handler applies to all the namespaces created using that template. The dispatcher needs to have the privilege for the given namesapce.

Parameters:

session - the given session

name - the name of the session namespace.

Returns:

SessionNamespace that is created

Throws:

AccessDeniedException - the dispatcher does not have the privilege to create the namespace

XSException - a generic error is detected

java.sql.SQLException - a JDBC exception is thrown

InvalidXSNamespaceException - namespace already exists

InvalidSessionException - an attempt is made to reference an invalid session

NotAttachedException - session not attached

deleteNamespace

public abstract void deleteNamespace(Session session,
                                     java.lang.String namespace)
                              throws java.sql.SQLException,
                                     AccessDeniedException,
                                     XSException,
                                     InvalidXSNamespaceException,
                                     InvalidSessionException,
                                     NotAttachedException

Removes a namespace from the session. The dispatcher needs to have the privilege for the given namesapce.

Parameters:

session - the given session

namespace - the namespace to be removed

Throws:

AccessDeniedException - the dispatcher does not have the privilege to delete this namespace

java.sql.SQLException - a JDBC exception is thrown

InvalidXSNamespaceException - namespace is invalid

InvalidSessionException - attempted to reference an invalid session

NotAttachedException - session not attached

XSException - a generic error is detected

createAttribute

public abstract SessionNamespaceAttribute createAttribute(SessionNamespace sessionNS,
                                                          java.lang.String name,
                                                          java.lang.String value,
                                                          java.util.List<SessionNamespace.ATTR_EVENT_TYPE> event)
                                                   throws java.sql.SQLException,
                                                          SessionNamespaceException,
                                                          AccessDeniedException,
                                                          XSException,
                                                          InvalidXSAttributeException,
                                                          NotAttachedException

Creates a new attribute in the namespace with the specified name, value, and event. The dispatcher needs to have the privilege for the given namesapce and attribute

Parameters:

sessionNS - the given SessionNamespace

name - name of the attribute

value - value of the attribute

event - event registration of the attribute

Returns:

the newly created attribute

Throws:

java.sql.SQLException - when a JDBC exception is thrown

AccessDeniedException - when the dispatcher does not have the privilege

XSException - when a generic error is detected

SessionNamespaceException - when the attibute name is invalid

InvalidXSAttributeException - when the attribute value is invalid

NotAttachedException - when the session is not attached

deleteAttribute

public abstract void deleteAttribute(SessionNamespace sessionNS,
                                     java.lang.String name)
                              throws java.sql.SQLException,
                                     AccessDeniedException,
                                     XSException,
                                     InvalidXSAttributeException,
                                     NotAttachedException

Deletes the specified attribute The dispatcher needs to have the privilege to delete the given attribute

Parameters:

sessionNS - the given SessionNamespace

name - name of the attribute

Throws:

java.sql.SQLException - when a JDBC exception is thrown

AccessDeniedException - when the dispatcher user does not have the privilege to delete the attribute

XSException - when a generic error is detected

InvalidXSAttributeException - when the attribute is invalid

NotAttachedException - when the session is not attached

resetAttribute

public abstract SessionNamespaceAttribute resetAttribute(SessionNamespace sessionNS,
                                                         java.lang.String name)
                                                  throws java.sql.SQLException,
                                                         AccessDeniedException,
                                                         XSException,
                                                         InvalidXSAttributeException,
                                                         NotAttachedException

Resets the specified attribute in the namespace to its default value. The dispatcher needs to have the privilege to restet the namespace

Parameters:

sessionNS - the given SessionNamespace

name - name of the attribute

Returns:

the attribute that has been reset

Throws:

java.sql.SQLException - when a JDBC exception is thrown

AccessDeniedException - when the current user does not have the privilege to reset the attribute

XSException - when a generic error is detected

InvalidXSAttributeException - when the attribute is invalid

NotAttachedException - when the session is not attached

setAttribute

public abstract SessionNamespaceAttribute setAttribute(SessionNamespace sessionNS,
                                                       java.lang.String name,
                                                       java.lang.String value)
                                                throws java.sql.SQLException,
                                                       SessionNamespaceException,
                                                       AccessDeniedException,
                                                       XSException,
                                                       InvalidXSAttributeException,
                                                       NotAttachedException

Sets the attribute for a session namespace with the specified name and value The dispatcher needs to have the privilege to set the attribute on the given namespace

Parameters:

sessionNS - the given SessionNamespace

name - name of the attribute

value - value of the attribute

Returns:

SessionNamespaceAttribute attribute object whose value is set

Throws:

java.sql.SQLException - when a JDBC exception is thrown

AccessDeniedException - when the dispatcher does not have the privilege to set the attribute on the namespace/attribute

XSException - when a generic error is detected

SessionNamespaceException - when the namespace is invalid

InvalidXSAttributeException - when the attribute is invalid

NotAttachedException - when the session is not attached