*** This interface provides Binary Compatibility only, not Source Compatibility ***

com.sas.services.session
Interface SessionContextInterface

All Superinterfaces:

com.sas.entities.EntityKeyInterface, java.rmi.Remote

public interface SessionContextInterface
extends com.sas.entities.EntityKeyInterface, java.rmi.Remote

The SessionContextInterface provides a control structure for maintaining state within a bound session and facilitates resource management and context passing. It is a convenience container for passing multiple contexts.

Objects are bound to the session context by name when they are added with setAttribute(Object). If the object bound to the session context implements RemoteSessionContextStateChangedListener, it will be notified when it is removed from the session context or when the session context is destroyed. This notification will allow objects to cleanup any resources that are necessary. Additionally, the session context acts as a convenience container for other commonly used service resources, such as the user context and the default logger.

Since:

1.0

Method Summary

void	destroy() Destroy the session context.
void	destroy(long delay) Destroy the session context after the specified delay.
java.lang.Object	getAttribute(java.lang.String name) Returns the object bound with the specified name in this session context, or null if no object is bound under this name.
LoggerInterface	getLogger() Deprecated. The Logging Service has been deprecated. Use Log4J directly instead of calling this method to get the Logging Service logger.
SessionContextInterface	getRootSessionContext() Returns the root session context.
SessionContextInterface	getRootSessionContext(UserContextInterface userContext) Returns the root session context.
java.lang.String	getRootSessionContextEntityKey() Returns the entity key for the root session context.
UserContextInterface	getUserContext() Returns the user context defined for this session context.
boolean	isDestroyPending() Returns a flag indicating whether a destroy is pending for this session context.
java.lang.Object	lock(java.lang.String applicationName) Locks the session context so that it cannot be destroyed.
boolean	removeAttribute(java.lang.String name) Removes the object from the session context.
java.lang.String	setAttribute(java.lang.Object value) Binds the object to the session context, creating and returning the unique key name that was used.
java.lang.Object	setAttribute(java.lang.String name, java.lang.Object value) Binds the object to the session context, using the specified name.
void	setTimeoutDisabled(boolean timeoutDisabled) Set whether or not this session can timeout.
void	setUserContext(UserContextInterface userContext) Sets the user context to bind to this session context.
byte[]	toByteArray() This is a platform private method that should only be used internally by the Platform Services.
void	touch() Touch the session so that its last access time is updated as recently used.
void	unlock(java.lang.Object lockObject) Unlocks the session context.

Method Detail

getRootSessionContext

SessionContextInterface getRootSessionContext()
                                              throws java.lang.IllegalStateException,
                                                     java.rmi.RemoteException

Returns the root session context. The Session Service creates the root session context at initialization. This root session context can be obtained from any session context created by that Session Service. This method is protected using JAAS permissions. A SessionContextPermission is required to obtain the root session context.

Returns:

SessionContextInterface that is the root session context.

Throws:

java.lang.IllegalStateException - If the session context has already been destroyed.

java.rmi.RemoteException - If a network anomaly is encountered.

getRootSessionContext

SessionContextInterface getRootSessionContext(UserContextInterface userContext)
                                              throws java.lang.IllegalStateException,
                                                     java.rmi.RemoteException

Returns the root session context. The Session Service creates the root session context at initialization. This root session context can be obtained from any session context created by that Session Service. This method is protected using JAAS permissions. A SessionContextPermission is required to obtain the root session context.

Parameters:

userContext - A user context whose principals will be checked for permission to perform the getRootSessionContext function. This can be null, but if the method is invoked remotely, it will always fail with a null user context.

Returns:

SessionContextInterface that is the root session context.

Throws:

java.lang.IllegalStateException - If the session context has already been destroyed.

java.rmi.RemoteException - If a network anomaly is encountered.

getRootSessionContextEntityKey

java.lang.String getRootSessionContextEntityKey()
                                                throws java.rmi.RemoteException

Returns the entity key for the root session context. The Session Service creates the root session context at initialization. This root session context can be obtained from any session context created by that Session Service.

Returns:

String the entity key for the root session context.

Throws:

java.lang.IllegalStateException - If the session context has already been destroyed.

java.rmi.RemoteException - If a network anomaly is encountered.

getUserContext

UserContextInterface getUserContext()
                                    throws java.lang.IllegalStateException,
                                           java.rmi.RemoteException

Returns the user context defined for this session context. If a user context was provided in the constructor to the session context, this will return the user context provided at creation. If the session context was initialized with a null user context and then it was set later using setUserContext(UserContextInterface), this will return the user context assigned by setUserContext.

Returns:

UserContextInterface The user context bound to this session context. This may be null if no user context has been set yet.

Throws:

java.lang.IllegalStateException - If the session context has already been destroyed.

java.rmi.RemoteException - If a network anomaly is encountered.

setUserContext

void setUserContext(UserContextInterface userContext)
                    throws java.lang.IllegalStateException,
                           java.rmi.RemoteException

Sets the user context to bind to this session context. This user context reference will be returned by getUserContext(). If the session context was created with a null user context, then the user context can be set at a later time. Once the user context has been set, it cannot be changed.

Parameters:

userContext - The user context to bind to this session.

Throws:

java.lang.IllegalStateException - If the session context has already been destroyed or if the user context has already been set.

java.rmi.RemoteException - If a network anomaly is encountered.

getLogger

LoggerInterface getLogger()
                          throws java.lang.IllegalStateException,
                                 java.rmi.RemoteException

Deprecated. The Logging Service has been deprecated. Use Log4J directly instead of calling this method to get the Logging Service logger.

Returns the default logger. When the Session Service is initialized, it creates a default logger that is then made available through all session contexts. The logger obtained from the session context has a logging context of "com.sas.services.session.SessionService". When this logger is used to send messages to the log, this default logging context will be associated with the message. The logging context can be overridden by explicitly providing a logging context on any of the logger methods.

Throws:

java.lang.IllegalStateException - If the session context has already been destroyed.

java.rmi.RemoteException - If a network anomaly is encountered.

setAttribute

java.lang.Object setAttribute(java.lang.String name,
                              java.lang.Object value)
                              throws java.lang.IllegalStateException,
                                     java.rmi.RemoteException

Binds the object to the session context, using the specified name. If the object implements RemoteSessionContextStateChangedListener, the session context will invoke RemoteSessionContextStateChangedListener.contextStateChanged(SessionContextStateChangedEvent) when the session is destroyed or when the object is removed from the session context. This allows the object to cleanup any resources that are necessary.

If an object of the same name is already bound to the session context, the object is replaced. If the object that is replaced implements RemoteSessionContextStateChangedListener, the session context will invoke RemoteSessionContextStateChangedListener.contextStateChanged(SessionContextStateChangedEvent) so that it will be notified of its removal from the session context.

The SessionContextInterface is a remotable interface. Distributed applications should ensure that bound objects are remotable.

Parameters:

name - String that identifies the name of the object bound to the session context; cannot be null.

value - The object to bind to the session context; can be null.

Returns:

Object The previous value associated with specified key, or null if there was no mapping for key

Throws:

java.lang.IllegalArgumentException - If a null name is specified.

java.lang.IllegalStateException - If the session context has already been destroyed.

java.rmi.RemoteException - If a network anomaly is encountered.

setAttribute

java.lang.String setAttribute(java.lang.Object value)
                              throws java.lang.IllegalStateException,
                                     java.rmi.RemoteException

Binds the object to the session context, creating and returning the unique key name that was used. This is useful when a session context is shared among applications as it takes care of creating the unique name to use when adding the object to the context.

Parameters:

value - The object to bind to the session context; can be null.

Returns:

String The generated unique key name used to track the object. The name will be in the form of "session1", "session2", ..., "sessionN".

Throws:

java.lang.IllegalStateException - If the session context has already been destroyed.

java.rmi.RemoteException - If a network anomaly is encountered.

getAttribute

java.lang.Object getAttribute(java.lang.String name)
                              throws java.lang.IllegalStateException,
                                     java.rmi.RemoteException

Returns the object bound with the specified name in this session context, or null if no object is bound under this name.

Parameters:

name - A string that identifies the name of the object; cannot be null.

Returns:

Object The object.

Throws:

java.lang.IllegalArgumentException - If a null name is specified.

java.lang.IllegalStateException - If the session context has already been destroyed.

java.rmi.RemoteException - If a network anomaly is encountered.

removeAttribute

boolean removeAttribute(java.lang.String name)
                        throws java.lang.IllegalStateException,
                               java.rmi.RemoteException

Removes the object from the session context. If the session context does not have an object bound with the specified name, a value of false will be returned.

If the object being removed implements RemoteSessionContextStateChangedListener, the session context will invoke RemoteSessionContextStateChangedListener.contextStateChanged(SessionContextStateChangedEvent).

Parameters:

name - Name that identifies the object; cannot be null.

Returns:

boolean that is true if the object was removed or false if an object with the specified name was not found.

Throws:

java.lang.IllegalArgumentException - If a null name is specified.

java.lang.IllegalStateException - If the session context has already been destroyed.

java.rmi.RemoteException - If a network anomaly is encountered.

lock

java.lang.Object lock(java.lang.String applicationName)
                      throws java.lang.IllegalStateException,
                             java.rmi.RemoteException

Locks the session context so that it cannot be destroyed. This is useful when multiple applications are sharing the session context. Multiple applications can lock the same session context. Each call to the lock method will return a unique lock object that must be used by that application to unlock the session context. The session context cannot be destroyed until all locks have been removed. See Session Context Sharing for details on session context locking and sharing.

Parameters:

applicationName - The application name that will be used by the session context for logging and monitoring purposes.

Returns:

Object The lock object that will be required to unlock the session context.

Throws:

java.lang.IllegalStateException - If the session context has already been destroyed.

java.rmi.RemoteException - If a network anomaly is encountered.

unlock

void unlock(java.lang.Object lockObject)
            throws java.lang.IllegalArgumentException,
                   java.lang.IllegalStateException,
                   java.rmi.RemoteException

Unlocks the session context. The session context can only be destroyed if it is not locked. See Session Context Sharing for details on session context locking and sharing.

Parameters:

lockObject - The lock object returned by lock(String).

Throws:

java.lang.IllegalArgumentException - If an invalid lockObject is specified.

java.lang.IllegalStateException - If the session context has already been destroyed.

java.rmi.RemoteException - If a network anomaly is encountered.

destroy

void destroy()
             throws LockingException,
                    java.lang.IllegalStateException,
                    java.rmi.RemoteException

Destroy the session context. All objects are unbound from the session context. If the bound objects implement RemoteSessionContextStateChangedListener, the session context will invoke RemoteSessionContextStateChangedListener.contextStateChanged(SessionContextStateChangedEvent). This allows objects to be notified when they are removed from the session context so they can perform any necessary cleanup.

The session context cannot be destroyed until all locks have been removed using the unlock method. See Session Context Sharing for details on session context locking and sharing.

Throws:

LockingException - If the session context is locked.

java.lang.IllegalStateException - If the session context has already been destroyed.

java.rmi.RemoteException - If a network anomaly is encountered.

destroy

void destroy(long delay)
             throws ServiceException,
                    java.lang.IllegalStateException,
                    java.rmi.RemoteException

Destroy the session context after the specified delay. All objects are unbound from the session context. If the bound objects implement RemoteSessionContextStateChangedListener, the session context will invoke RemoteSessionContextStateChangedListener.contextStateChanged(SessionContextStateChangedEvent). This allows objects to be notified when they are removed from the session context so they can perform any necessary cleanup.

The session context cannot be destroyed until all locks have been removed using the unlock method. See Session Context Sharing for details on session context locking and sharing.

Parameters:

delay - delay in milliseconds before the session context will be destroyed.

Throws:

ServiceException - If the service encounters an error with the deferred destroy.

java.lang.IllegalStateException - If the session context has already been destroyed.

java.rmi.RemoteException - If a network anomaly is encountered.

toByteArray

byte[] toByteArray()
                   throws java.rmi.RemoteException,
                          ServiceException

This is a platform private method that should only be used internally by the Platform Services.

Returns:

A byte array with the serialized Session Context.

Throws:

ServiceException - if a service level error occurs.

java.rmi.RemoteException - in the event of remote object failure.

touch

void touch()
           throws java.rmi.RemoteException

Touch the session so that its last access time is updated as recently used.

Throws:

java.rmi.RemoteException - in the event of remote object failure.

isDestroyPending

boolean isDestroyPending()
                         throws java.rmi.RemoteException

Returns a flag indicating whether a destroy is pending for this session context.

Returns:

<true if the Session Context is in a destroy pending state; otherwise false is returned.

Throws:

java.rmi.RemoteException - if a network error occurs.

setTimeoutDisabled

void setTimeoutDisabled(boolean timeoutDisabled)
                        throws java.rmi.RemoteException

Set whether or not this session can timeout. Default is that the session will be eligible for timeout; i.e., timeoutDisabled = false

Parameters:

timeoutDisabled - true if the session should not timeout, false otherwise

Throws:

java.rmi.RemoteException

*** This interface provides Binary Compatibility only, not Source Compatibility ***