*** 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