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

Package com.sas.services.session

# Interface SessionContextInterface

All Superinterfaces:
  `com.sas.entities.EntityKeyInterface`, `Remote`

@SASScope("ALL") @BinaryCompatibilityOnly public interface SessionContextInterface extends com.sas.entities.EntityKeyInterface, 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

  Modifier and Type
  Method
  Description
  `void`
  `destroy()`
  Destroy the session context.
  `void`
  `destroy(long delay)`
  Destroy the session context after the specified delay.
  `Object`
  `getAttribute(String name)`
  Returns the object bound with the specified name in this session context, or `null` if no object is bound under this name.
  `SessionContextInterface`
  `getRootSessionContext()`
  Returns the root session context.
  `SessionContextInterface`
  `getRootSessionContext(UserContextInterface userContext)`
  Returns the root session context.
  `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.
  `Object`
  `lock(String applicationName)`
  Locks the session context so that it cannot be destroyed.
  `boolean`
  `removeAttribute(String name)`
  Removes the object from the session context.
  `String`
  `setAttribute(Object value)`
  Binds the object to the session context, creating and returning the unique key name that was used.
  `Object`
  `setAttribute(String name, 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(Object lockObject)`
  Unlocks the session context.

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

  `getEntityKey, sameEntity, setEntityKey`

- ## Method Details

  - ### getRootSessionContext

    SessionContextInterface getRootSessionContext() throws IllegalStateException, 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:
      `IllegalStateException` - If the session context has already been destroyed.
      `RemoteException` - If a network anomaly is encountered.

  - ### getRootSessionContext

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

  - ### getRootSessionContextEntityKey

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

  - ### getUserContext

    UserContextInterface getUserContext() throws IllegalStateException, 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:
      `IllegalStateException` - If the session context has already been destroyed.
      `RemoteException` - If a network anomaly is encountered.

  - ### setUserContext

    void setUserContext(UserContextInterface userContext) throws IllegalStateException, 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:
      `IllegalStateException` - If the session context has already been destroyed or if the user context has already been set.
      `RemoteException` - If a network anomaly is encountered.

  - ### setAttribute

    Object setAttribute(String name, Object value) throws IllegalStateException, 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:
      `IllegalArgumentException` - If a `null` name is specified.
      `IllegalStateException` - If the session context has already been destroyed.
      `RemoteException` - If a network anomaly is encountered.

  - ### setAttribute

    String setAttribute(Object value) throws IllegalStateException, 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:
      `IllegalStateException` - If the session context has already been destroyed.
      `RemoteException` - If a network anomaly is encountered.

  - ### getAttribute

    Object getAttribute(String name) throws IllegalStateException, 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:
      `IllegalArgumentException` - If a `null` name is specified.
      `IllegalStateException` - If the session context has already been destroyed.
      `RemoteException` - If a network anomaly is encountered.

  - ### removeAttribute

    boolean removeAttribute(String name) throws IllegalStateException, 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:
      `IllegalArgumentException` - If a `null` name is specified.
      `IllegalStateException` - If the session context has already been destroyed.
      `RemoteException` - If a network anomaly is encountered.

  - ### lock

    Object lock(String applicationName) throws IllegalStateException, 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:
      `IllegalStateException` - If the session context has already been destroyed.
      `RemoteException` - If a network anomaly is encountered.

  - ### unlock

    void unlock(Object lockObject) throws IllegalArgumentException, IllegalStateException, 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:
      `IllegalArgumentException` - If an invalid lockObject is specified.
      `IllegalStateException` - If the session context has already been destroyed.
      `RemoteException` - If a network anomaly is encountered.

  - ### destroy

    void destroy() throws LockingException, IllegalStateException, 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.
      `IllegalStateException` - If the session context has already been destroyed.
      `RemoteException` - If a network anomaly is encountered.

  - ### destroy

    void destroy(long delay) throws ServiceException, IllegalStateException, 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.
      `IllegalStateException` - If the session context has already been destroyed.
      `RemoteException` - If a network anomaly is encountered.

  - ### toByteArray

    byte[] toByteArray() throws 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.
      `RemoteException` - in the event of remote object failure.

  - ### touch

    void touch() throws RemoteException
    Touch the session so that its last access time is updated as recently used.
    Throws:
      `RemoteException` - in the event of remote object failure.

  - ### isDestroyPending

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

  - ### setTimeoutDisabled

    void setTimeoutDisabled(boolean timeoutDisabled) throws 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:
      `RemoteException`