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

com.sas.services.session
Class SessionService

com.sas.services.session.SessionService

All Implemented Interfaces:

com.sas.entities.EntityKeyInterface, ServiceNotificationBroadcasterInterface, QuiesceInterface, RemoteServiceInterface, RemoteSessionContextStateChangedListener, SessionServiceInterface, java.rmi.Remote, java.util.EventListener

public class SessionService
implements SessionServiceInterface, RemoteSessionContextStateChangedListener

The Session Service provides a mechanism for creating and accessing session contexts. The session context 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.

Since:

1.0

See Also:

SessionServiceFactory, SessionServiceInitObject

Field Summary

static java.lang.String	RB_KEY Resource bundle key prefix.
static long	serialVersionUID Serial version ID.

Fields inherited from interface com.sas.services.RemoteServiceInterface

CLASS_IDENTIFIER, CLASS_IDENTIFIER_1_1, CLASS_IDENTIFIER_1_2, CLASS_IDENTIFIER_SERVICE_TYPE, CLASS_IDENTIFIER_SERVICE_TYPE_1_1, CLASS_IDENTIFIER_SERVICE_TYPE_1_2

Method Summary

void	configure(ServiceConfigurationInterface serviceConfiguration) Configures service.
void	contextStateChanged(SessionContextStateChangedEvent event) The session service implementation implements the RemoteSessionContextStateChangedListener so that it can be notified when the session context is a destroyed.
void	destroy() Destroys the service.
boolean	destroySession(UserContextInterface userContext, java.lang.String sessionContextId) Forcibly destroys the session context identified by the session context id.
void	destroySessions(UserContextInterface userContext) This destroys all session contexts created by this Session Service, without destroying the Session Service itself.
protected void	finalize() Destroys all the session contexts that are being managed.
SessionContextInterface	fromByteArray(byte[] data) Instantiate a SessionContext from a passivated byte array.
static SessionServiceInterface	getInstance(ServiceConfigurationInterface serviceConfiguration) Returns the singleton instance of the session service.
static SessionServiceInterface	getInstance(ServiceConfigurationInterface serviceConfiguration, DiscoveryServiceInterface discoveryService) Returns the singleton instance of the session service.
static SessionContextInterface	getRootSessionContext() Get the root SessionContext.
static java.lang.String	getRootSessionContextEntityKey() Returns the entity key for the root session context.
RemoteServiceInterface	getServiceProxy() Gets the service proxy.
SessionContextInterface	getSessionContext(java.lang.String uniqueId) Obtains the session context interface identified by unique identifier or null if no session context exists with this id.
SessionContextInterface	getSessionContext(UserContextInterface userContext, java.lang.String uniqueId) Obtains the session context interface identified by the unique identifer or null if no session context exists with this id.
java.util.List	getSummaryData(UserContextInterface userContext) Return summary information for all active session contexts created by this Session Service.
boolean	isQuiesced() Returns a flag indicating whether the Session Service is in a quiesce state or not.
SessionContextInterface	newSessionContext(UserContextInterface userContext) Create and return a new session context.
void	quiesce(UserContextInterface userContext) Quiesce the Session Service.
void	resume(UserContextInterface userContext) Resume the Session Service.

Methods inherited from class com.sas.services.AbstractRemoteService

addServiceObserver, bindToDiscoveryService, getCreationTime, getDetails, getDiscoveryService, getEntityKey, getEnvironment, getServiceConfiguration, getServiceConfiguration, getServiceState, handleJVMShutdown, isAccessibleToRemoteClients, isExported, isHandlingJVMShutdown, notifyServiceObservers, reconfigure, removeAllServiceObservers, removeServiceObserver, sameEntity, setDiscoveryService, setEntityKey, setRemoteableExporter, setServiceState, toString, unbindFromDiscoveryService

Methods inherited from interface com.sas.services.RemoteServiceInterface

getCreationTime, getServiceConfiguration, getServiceConfiguration, getServiceState, isAccessibleToRemoteClients, isExported, reconfigure, setServiceState

Methods inherited from interface com.sas.services.mgmt.ServiceNotificationBroadcasterInterface

addServiceObserver, notifyServiceObservers, removeAllServiceObservers, removeServiceObserver

Field Detail

RB_KEY

public static final java.lang.String RB_KEY

Resource bundle key prefix.

See Also:

Constant Field Values

serialVersionUID

public static final long serialVersionUID

Serial version ID. This value should be changed if backward compatibility with previously serialized versions is no longer desired.

See Also:

Constant Field Values

Method Detail

configure

public void configure(ServiceConfigurationInterface serviceConfiguration)
               throws java.rmi.RemoteException,
                      ServiceException

Configures service. Note that this method may used to initialize a service or to re-configure a previously initialized service.

Specified by:

configure in interface RemoteServiceInterface

Overrides:

configure in class AbstractRemoteService

Parameters:

serviceConfiguration - An object containing configuration data necessary to initialize or re-configure a service. Note that the service provider must verify that the object type is supported. An InitializationException should be thrown if the initialization was not completed successfully to indicate that the instance should not be used.

Throws:

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

ServiceException - if unable to configure the service.

destroy

public void destroy()
             throws ServiceException,
                    java.rmi.RemoteException

Destroys the service. The service should release any resources it holds in preparation for termination of use of this service.

Specified by:

destroy in interface RemoteServiceInterface

Overrides:

destroy in class AbstractRemoteService

Throws:

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

ServiceException - if the service is unable to prepare itself for destruction.

getInstance

public static SessionServiceInterface getInstance(ServiceConfigurationInterface serviceConfiguration)
                                           throws ServiceException

Returns the singleton instance of the session service. This getInstance() initializes the Session Sevice with the initialization object created from the PFS deployment configuration. This object will contain information about the default platform user context for the session.

Parameters:

serviceConfiguration - Session Service's initialization object.

Returns:

SessionServiceInterface The session service.

Throws:

ServiceException - If an error is encountered creating the singelton instance.

getInstance

public static SessionServiceInterface getInstance(ServiceConfigurationInterface serviceConfiguration,
                                                  DiscoveryServiceInterface discoveryService)
                                           throws ServiceException

Returns the singleton instance of the session service. This getInstance() initializes the Session Sevice with the initialization object created from the PFS deployment configuration. This object will contain information about the default platform user context for the session.

Parameters:

serviceConfiguration - Session Service's initialization object.

discoveryService - Discovery service to which the service will be registered.

Returns:

SessionServiceInterface The session service.

Throws:

ServiceException - If an error is encountered creating the singelton instance.

getRootSessionContext

public static final SessionContextInterface getRootSessionContext()

Get the root SessionContext. The Session Service creates a root session context during initialization. The root session context that is returned is the root session context for this JVM. This method is protected using JAAS permissions. A SessionContextPermissionis required to obtain the root session context.

Returns:

SessionContextInterface The root session context.

getRootSessionContextEntityKey

public static final java.lang.String getRootSessionContextEntityKey()
                                                             throws java.rmi.RemoteException

Returns the entity key for the root session context. The entity key may be null if the Session Service has not been deployed within this JVM.

Returns:

String the entity key for the root session context. This may be null if the Session Service has not been deployed in this JVM.

Throws:

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

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

newSessionContext

public SessionContextInterface newSessionContext(UserContextInterface userContext)
                                          throws InitializationException,
                                                 java.rmi.RemoteException,
                                                 java.lang.IllegalStateException

Create and return a new session context.

Specified by:

newSessionContext in interface SessionServiceInterface

Parameters:

userContext - User context for this session context; can be null. If null, it can be set later using setUserContext().

Returns:

SessionContextInterface The new session context.

Throws:

InitializationException - If the context fails to initialize.

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

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

getSessionContext

public SessionContextInterface getSessionContext(java.lang.String uniqueId)
                                          throws java.rmi.RemoteException,
                                                 java.lang.IllegalStateException

Obtains the session context interface identified by unique identifier or null if no session context exists with this id. This method is protected using JAAS permissions. A SessionContextPermissionis required to obtain the session context from the Session Service.

Specified by:

getSessionContext in interface SessionServiceInterface

Parameters:

uniqueId - Unique identifier of the session context be to returned.

Returns:

SessionContextInterface The session context interface.

Throws:

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

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

getSessionContext

public SessionContextInterface getSessionContext(UserContextInterface userContext,
                                                 java.lang.String uniqueId)
                                          throws java.rmi.RemoteException,
                                                 java.lang.IllegalStateException

Obtains the session context interface identified by the unique identifer or null if no session context exists with this id. The unique identifier is required to identify the desired context so that applications don't have access to all session contexts. This method is protected using JAAS permissions. A SessionContextPermissionis required to obtain the session context from the Session Service.

Specified by:

getSessionContext in interface SessionServiceInterface

Parameters:

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

uniqueId - Unique identifier of the session context to be returned.

Returns:

SessionContextInterface The session context interface.

Throws:

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

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

contextStateChanged

public void contextStateChanged(SessionContextStateChangedEvent event)

The session service implementation implements the RemoteSessionContextStateChangedListener so that it can be notified when the session context is a destroyed. This allows this session service implementation to clean up its references to this context that has been destroyed.

Specified by:

contextStateChanged in interface RemoteSessionContextStateChangedListener

Parameters:

event - The event notifying us that the context has been destroyed.

getServiceProxy

public final RemoteServiceInterface getServiceProxy()

Gets the service proxy.

Specified by:

getServiceProxy in interface RemoteServiceInterface

Overrides:

getServiceProxy in class AbstractRemoteService

Returns:

A proxy to this service or null if a proxy is not available.

quiesce

public void quiesce(UserContextInterface userContext)
             throws ServiceException,
                    QuiesceException,
                    java.lang.IllegalStateException

Quiesce the Session Service. This will prevent the Session Service from creating any new session contexts.

This method is protected using JAAS permissions. A SessionPermissionis required to quiesce the Session Service.

Specified by:

quiesce in interface QuiesceInterface

Specified by:

quiesce in interface SessionServiceInterface

Parameters:

userContext - The user context.

Throws:

ServiceException - If a service error occurs.

QuiesceException - If an error occurs quiescing the session service.

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

isQuiesced

public boolean isQuiesced()
                   throws java.rmi.RemoteException

Returns a flag indicating whether the Session Service is in a quiesce state or not.

Specified by:

isQuiesced in interface SessionServiceInterface

Returns:

true if the Session Service is in a quiesce state; otherwise false is returned.

Throws:

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

resume

public void resume(UserContextInterface userContext)
            throws ServiceException,
                   QuiesceException,
                   java.lang.IllegalStateException

Resume the Session Service. This should be called after the Session Service has been quiesced, to allow the Session Service to start creating new session contexts again.

This method is protected using JAAS permissions. A SessionPermissionis required to resume the Session Service.

Specified by:

resume in interface QuiesceInterface

Specified by:

resume in interface SessionServiceInterface

Parameters:

userContext - The user context.

Throws:

ServiceException - If a service error occurs.

QuiesceException - If an error occurs resuming the session service.

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

destroySessions

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

This destroys all session contexts created by this Session Service, without destroying the Session Service itself.

This method is protected using JAAS permissions. A SessionPermissionis required to destroy the active session contexts.

Specified by:

destroySessions in interface SessionServiceInterface

Parameters:

userContext - The user context

Throws:

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

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

destroySession

public boolean destroySession(UserContextInterface userContext,
                              java.lang.String sessionContextId)
                       throws java.rmi.RemoteException

Forcibly destroys the session context identified by the session context id. The session context will be destroyed even if is locked.

This method is protected using JAAS permissions. A SessionPermissionis required to destroy the active session context.

Specified by:

destroySession in interface SessionServiceInterface

Parameters:

userContext - The user context.

sessionContextId - The unique identifier of the session context to destroy.

Returns:

boolean that is false if the session context identified by the unique id could not be found; otherwise true is returned.

Throws:

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

getSummaryData

public java.util.List getSummaryData(UserContextInterface userContext)
                              throws java.rmi.RemoteException,
                                     java.lang.IllegalStateException

Return summary information for all active session contexts created by this Session Service. Each session context can be bound to a user context. The summary data for each active session contains information such as the user context name, the user's email addresses, and the user's global profile.

This method is protected using JAAS permissions. A SessionPermissionis required to retrieve the user summary data.

Specified by:

getSummaryData in interface SessionServiceInterface

Parameters:

userContext - The user context.

Returns:

List A list of SummaryDataInterface objects.

Throws:

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

java.rmi.RemoteException - if a network error occurs

finalize

protected void finalize()
                 throws java.lang.Throwable

Destroys all the session contexts that are being managed.

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable - if uanble to finalize

fromByteArray

public SessionContextInterface fromByteArray(byte[] data)
                                      throws java.rmi.RemoteException,
                                             ServiceException

Description copied from interface: SessionServiceInterface

Instantiate a SessionContext from a passivated byte array. The first item in the passivated stream is the session ID. If that session ID is one this session service has in its known list, get it and return it.

Specified by:

fromByteArray in interface SessionServiceInterface

Parameters:

data - The passivated data stream.

Returns:

The instantiated Session Context

Throws:

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

ServiceException - If an error occurs processing the data.

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