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

Package com.sas.services.session

# Class SessionService

java.lang.Object
com.sas.services.AbstractRemoteService
com.sas.services.session.SessionService

All Implemented Interfaces:
  `com.sas.entities.EntityKeyInterface`, `ServiceNotificationBroadcasterInterface`, `QuiesceInterface`, `RemoteServiceInterface`, `RemoteSessionContextStateChangedListener`, `SessionServiceInterface`, `Remote`, `EventListener`

@SASScope("ALL") @BinaryCompatibilityOnly public class SessionService extends AbstractRemoteService 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

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `RB_KEY`
  Resource bundle key prefix.
  `static final 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

  Modifier and Type
  Method
  Description
  `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, 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 final SessionContextInterface`
  `getRootSessionContext()`
  Get the root SessionContext.
  `static final String`
  `getRootSessionContextEntityKey()`
  Returns the entity key for the root session context.
  `final RemoteServiceInterface`
  `getServiceProxy()`
  Gets the service proxy.
  `SessionContextInterface`
  `getSessionContext(UserContextInterface userContext, String uniqueId)`
  Obtains the session context interface identified by the unique identifer or `null` if no session context exists with this id.
  `SessionContextInterface`
  `getSessionContext(String uniqueId)`
  Obtains the session context interface identified by unique identifier or null if no session context exists with this id.
  `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 class java.lang.Object

  `clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface com.sas.entities.EntityKeyInterface

  `getEntityKey, sameEntity, setEntityKey`

  ### 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 Details

  - ### RB_KEY

    public static final 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 Details

  - ### configure

    public void configure(ServiceConfigurationInterface serviceConfiguration) throws 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:
      `RemoteException` - if a network anomaly is encountered.
      `ServiceException` - if unable to configure the service.

  - ### destroy

    public void destroy() throws ServiceException, 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:
      `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 `SessionContextPermission`is required to obtain the root session context.
    Returns:
      `SessionContextInterface` The root session context.

  - ### getRootSessionContextEntityKey

    public static final String getRootSessionContextEntityKey() throws 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:
      `IllegalStateException` - If the session context has already been destroyed.
      `RemoteException` - If a network anomaly is encountered.

  - ### newSessionContext

    public SessionContextInterface newSessionContext(UserContextInterface userContext) throws InitializationException, RemoteException, 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.
      `IllegalStateException` - If the session service has already been destroyed.
      `RemoteException` - If a network anomaly is encountered.

  - ### getSessionContext

    public SessionContextInterface getSessionContext(String uniqueId) throws RemoteException, 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 `SessionContextPermission`is 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:
      `IllegalStateException` - If the session service has already been destroyed.
      `RemoteException` - If a network anomaly is encountered.

  - ### getSessionContext

    public SessionContextInterface getSessionContext(UserContextInterface userContext, String uniqueId) throws RemoteException, 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 `SessionContextPermission`is 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:
      `IllegalStateException` - If the session service has already been destroyed.
      `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, 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 `SessionPermission`is 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.
      `IllegalStateException` - If the session service has already been destroyed.

  - ### isQuiesced

    public boolean isQuiesced() throws 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:
      `RemoteException` - if a network error occurs.

  - ### resume

    public void resume(UserContextInterface userContext) throws ServiceException, QuiesceException, 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 `SessionPermission`is 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.
      `IllegalStateException` - If the session service has already been destroyed.

  - ### destroySessions

    public void destroySessions(UserContextInterface userContext) throws RemoteException, 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 `SessionPermission`is required to destroy the active session contexts.

    Specified by:
      `destroySessions` in interface `SessionServiceInterface`
    Parameters:
      `userContext` - The user context
    Throws:
      `IllegalStateException` - If the session service has already been destroyed.
      `RemoteException` - If a network anomaly is encountered.

  - ### destroySession

    public boolean destroySession(UserContextInterface userContext, String sessionContextId) throws 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 `SessionPermission`is 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:
      `RemoteException` - If a network anomaly is encountered.

  - ### getSummaryData

    public List getSummaryData(UserContextInterface userContext) throws RemoteException, 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 `SessionPermission`is 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:
      `IllegalStateException` - If the session service has already been destroyed.
      `RemoteException` - if a network error occurs

  - ### finalize

    protected void finalize() throws Throwable
    Destroys all the session contexts that are being managed.
    Overrides:
      `finalize` in class `Object`
    Throws:
      `Throwable` - if uanble to finalize

  - ### fromByteArray

    public SessionContextInterface fromByteArray(byte[] data) throws 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:
      `RemoteException` - In the event of remote object failure.
      `ServiceException` - If an error occurs processing the data.