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

Package com.sas.services.session

# Interface SessionServiceInterface

All Superinterfaces:
  `com.sas.entities.EntityKeyInterface`, `QuiesceInterface`, `Remote`, `RemoteServiceInterface`, `ServiceNotificationBroadcasterInterface`

All Known Implementing Classes:
  `SessionService`, `SessionServiceProxy`

@SASScope("ALL") @BinaryCompatibilityOnly public interface SessionServiceInterface extends RemoteServiceInterface, QuiesceInterface
The SessionServiceInterface 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

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final long`
  `serialVersionUID`
  Deprecated.
  serialVersionUID will be deleted in a future release.

  ### 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
  `boolean`
  `destroySession(UserContextInterface userContext, String sessionContextId)`
  Forcibly destroys the session context identified by the session context id.
  `void`
  `destroySessions(UserContextInterface userContext)`
  Forces a destroy of all session contexts created by this Session Service.
  `SessionContextInterface`
  `fromByteArray(byte[] data)`
  Instantiate a SessionContext from a passivated byte array.
  `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 the unique identifer 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)`
  Creates and returns a new session context interface.
  `void`
  `quiesce(UserContextInterface userContext)`
  Quiesce the Session Service.
  `void`
  `resume(UserContextInterface userContext)`
  Resume the Session Service.

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

  `getEntityKey, sameEntity, setEntityKey`

  ### Methods inherited from interface com.sas.services.RemoteServiceInterface

  `configure, destroy, getCreationTime, getServiceConfiguration, getServiceConfiguration, getServiceProxy, getServiceState, isAccessibleToRemoteClients, isExported, reconfigure, setServiceState`

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

  `addServiceObserver, notifyServiceObservers, removeAllServiceObservers, removeServiceObserver`

- ## Field Details

  - ### serialVersionUID

    static final long serialVersionUID
    Deprecated.
    serialVersionUID will be deleted in a future release.
    Serial version ID.
    See Also:
      - Constant Field Values

- ## Method Details

  - ### newSessionContext

    SessionContextInterface newSessionContext(UserContextInterface userContext) throws InitializationException, RemoteException
    Creates and returns a new session context interface. The user context to bind to the session context can be provided. If a null user context is provided, it can be set at a later time. Once the user context has been set to a non-null value, it cannot be changed.

    The creation will fail if the session service is in a quiesce state. If a quiesce state failure occurs, the `InitializationException.getRootException` will return a `QuiesceException`.

    Parameters:
      `userContext` - User context for this session context; can be `null`.
    Returns:
      `SessionContextInterface` The created session context interface.
    Throws:
      `InitializationException` - If the context fails to initialize.
      `RemoteException` - If a network anomaly is encountered.

  - ### getSessionContext

    SessionContextInterface getSessionContext(String uniqueId) throws RemoteException
    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.
    Parameters:
      `uniqueId` - Unique identifier of the session context to be returned.
    Returns:
      `SessionContextInterface` The session context interface.
    Throws:
      `RemoteException` - If a network anomaly is encountered.

  - ### getSessionContext

    SessionContextInterface getSessionContext(UserContextInterface userContext, String uniqueId) throws RemoteException
    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.
    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:
      `RemoteException` - If a network anomaly is encountered.

  - ### quiesce

    void quiesce(UserContextInterface userContext) throws ServiceException, QuiesceException, RemoteException
    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`
    Parameters:
      `userContext` - The user context.
    Throws:
      `ServiceException` - If a service error occurs.
      `QuiesceException` - If an error occurs quiescing the service.
      `RemoteException` - If a network anomaly is encountered.

  - ### resume

    void resume(UserContextInterface userContext) throws ServiceException, QuiesceException, RemoteException
    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`
    Parameters:
      `userContext` - The user context.
    Throws:
      `ServiceException` - If a service error occurs.
      `QuiesceException` - If an error occurs resuming the service.
      `RemoteException` - If a network anomaly is encountered.

  - ### destroySessions

    void destroySessions(UserContextInterface userContext) throws RemoteException
    Forces a destroy of all session contexts created by this Session Service. The session contexts will be destroyed even if they are locked. The Session Service itself is not destroyed, The root session context is not destroyed. The root session context is created when the Session Service is initialized, and is available throughout the life time of the Session Service. It is not destroyed until the Session Service itself is destroyed.

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

    Parameters:
      `userContext` - The user context.
    Throws:
      `RemoteException` - If a network anomaly is encountered.

  - ### destroySession

    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.

    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

    List getSummaryData(UserContextInterface userContext) throws RemoteException
    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.

    Parameters:
      `userContext` - The user context.
    Returns:
      `List` A list of `SummaryDataInterface` objects.
    Throws:
      `RemoteException` - if a network error occurs

  - ### isQuiesced

    boolean isQuiesced() throws RemoteException
    Returns a flag indicating whether the Session Service is in a quiesce state or not.
    Returns:
      `true` if the Session Service is in a quiesce state; otherwise `false` is returned.
    Throws:
      `RemoteException` - if a network error occurs.

  - ### fromByteArray

    SessionContextInterface fromByteArray(byte[] data) throws RemoteException, ServiceException
    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.
    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.