Package org.zkoss.zk.ui.http

## Class SimpleSession

- java.lang.Object
- - org.zkoss.zk.ui.http.SimpleSession

- All Implemented Interfaces:
    `Scope`, `Session`, `SessionCtrl`
  Direct Known Subclasses:
    `SerializableSession`

      public class SimpleSession
      extends java.lang.Object
      implements Session, SessionCtrl

  A non-serializable implementation of `Session`.

  Note:
  Though this class is serializable, it is meaningless to serialize it directly. Reason: it doesn't serialize any session attributes. Rather, it is serialized when Web server serialized HttpSession. Also, notice that `SimpleSession` is stored as an attribute HttpSession.

  Author:
    tomyeh

- - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `SimpleSession()` | Used by the deriving class, only if the deriving class implements java.io.Serializable.
    `` | `SimpleSession​(WebApp wapp, java.lang.Object navsess, java.lang.Object request)` | Constructs a ZK session with either a HTTP session or a Portlet session.
    `` | `SimpleSession​(WebApp wapp, javax.servlet.http.HttpSession hsess, java.lang.Object request)` | Constructs a ZK session with a HTTP session.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `addScopeListener​(ScopeListener listener)` | Adds a listener to listen whether this scope is changed.
    `java.lang.Object` | `getAttribute​(java.lang.String name)` | Returns the value of the specified custom attribute.
    `java.lang.Object` | `getAttribute​(java.lang.String name, boolean recurse)` | Returns the custom attribute associated with this object.
    `java.util.Map<java.lang.String,​java.lang.Object>` | `getAttributes()` | Returns a map of custom attributes associated with this session.
    `DesktopCache` | `getDesktopCache()` | Returns the desktop cache, or null if not available.
    `java.lang.String` | `getDeviceType()` | Returns the device type that this session belongs to.
    `int` | `getMaxInactiveInterval()` | Return the time, in seconds, between client requests before the servlet container will invalidate this session.
    `java.lang.Object` | `getNativeSession()` | Returns the native session, or null if not available.
    `WebApp` | `getWebApp()` | Returns the Web application that this session belongs to.
    `boolean` | `hasAttribute​(java.lang.String name)` | Returns if a custom attribute is associated with this object (scope).
    `boolean` | `hasAttribute​(java.lang.String name, boolean recurse)` | Returns if a custom attribute is associated with this object.
    `void` | `invalidate()` | Invalidates this session then unbinds any objects bound to it.
    `void` | `invalidateNow()` | Really invalidates the session.
    `boolean` | `isInvalidated()` | Returns whether this session is invalidated (i.e., `Session.invalidate()` was called).
    `boolean` | `notifyClientRequest​(boolean keepAlive)` | Notifies the session that a client request is received.
    `void` | `onDestroyed()` | Called when the session is destroyed.
    `protected void` | `readThis​(java.io.ObjectInputStream s)` | Used by the deriving class to read back this object, only if the deriving class implements java.io.Serializable.
    `void` | `recover​(java.lang.Object nativeSession)` | Called when ZK detects `Session.getNativeSession()` is not initialized properly.
    `java.lang.Object` | `removeAttribute​(java.lang.String name)` | Removes the specified custom attribute.
    `java.lang.Object` | `removeAttribute​(java.lang.String name, boolean recurse)` | Removes the custom attribute associated with this scope.
    `boolean` | `removeScopeListener​(ScopeListener listener)` | Removes a change listener from this scope.
    `protected void` | `sessionDidActivate​(javax.servlet.http.HttpSession hsess)` | Used by the deriving class to post-process a session after it is read back.
    `protected void` | `sessionWillPassivate()` | Used by the deriving class to pre-process a session before writing the session
    `java.lang.Object` | `setAttribute​(java.lang.String name, java.lang.Object value)` | Sets the value of the specified custom attribute.
    `java.lang.Object` | `setAttribute​(java.lang.String name, java.lang.Object value, boolean recurse)` | Sets the custom attribute associated with this scope, or the parent scope.
    `void` | `setDesktopCache​(DesktopCache cache)` | Sets the desktop cache.
    `void` | `setDeviceType​(java.lang.String deviceType)` | Sets the device type that this session belongs to.
    `void` | `setMaxInactiveInterval​(int interval)` | Specifies the time, in seconds, between client requests before the servlet container will invalidate this session.
    `protected void` | `writeThis​(java.io.ObjectOutputStream s)` | Used by the deriving class to write this object, only if the deriving class implements java.io.Serializable.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### SimpleSession

          public SimpleSession​(WebApp wapp,
                               javax.servlet.http.HttpSession hsess,
                               java.lang.Object request)

      Constructs a ZK session with a HTTP session.
      Parameters:
        `hsess` - the original HTTP session.
        `request` - the original request causing this session to be created. If HTTP and servlet, it is javax.servlet.http.HttpServletRequest. If portlet, it is javax.portlet.RenderRequest.
      Since:
        3.0.1

    - #### SimpleSession

          public SimpleSession​(WebApp wapp,
                               java.lang.Object navsess,
                               java.lang.Object request)

      Constructs a ZK session with either a HTTP session or a Portlet session.

      Note: it assumes the scope of attributes is PortletSession.APPLICATION_SCOPE.

      Parameters:
        `navsess` - the original session, either an instance of HttpSession or PortletSession. Notice: we don't declare PortletSession in API to avoid this class failed to be loaded in some system (without portlet-api.jar)
        `request` - the original request causing this session to be created. If portlet, it is javax.portlet.RenderRequest.
      Since:
        3.6.2

    - #### SimpleSession

          protected SimpleSession()

      Used by the deriving class, only if the deriving class implements java.io.Serializable.

  - ### Method Detail

    - #### getDeviceType

          public java.lang.String getDeviceType()

      Description copied from interface: `Session`
      Returns the device type that this session belongs to.

      A device type identifies the type of a client. For example, "ajax" represents the Web browsers with Ajax support, while "mil" represents clients that supports Mobile Interactive markup Language (on Limited Connected Device, such as mobile phones).

      All desktops of the same session must belong to the same device type.

      The session's device type is determined by the first desktop's device type.

      Specified by:
        `getDeviceType` in interface `Session`

    - #### setDeviceType

          public void setDeviceType​(java.lang.String deviceType)

      Description copied from interface: `SessionCtrl`
      Sets the device type that this session belongs to.

      It is called by the desktop when `Desktop.setDeviceType(java.lang.String)` is called. Don't call this method directly. Otherwise, the result is unpredictable.

      Specified by:
        `setDeviceType` in interface `SessionCtrl`

    - #### getAttribute

          public java.lang.Object getAttribute​(java.lang.String name)

      Description copied from interface: `Session`
      Returns the value of the specified custom attribute.
      Specified by:
        `getAttribute` in interface `Scope`
      Specified by:
        `getAttribute` in interface `Session`

    - #### getAttribute

          public java.lang.Object getAttribute​(java.lang.String name,
                                               boolean recurse)

      Description copied from interface: `Scope`
      Returns the custom attribute associated with this object.
      Specified by:
        `getAttribute` in interface `Scope`
        `recurse` - whether to search its ancestor scope. If true and the current scope doen't define the attribute, it searches up its ancestor to see any of them has defined the specified attribute.

    - #### hasAttribute

          public boolean hasAttribute​(java.lang.String name)

      Description copied from interface: `Scope`
      Returns if a custom attribute is associated with this object (scope).

      Notice that `null` is a valid value, so you can tell if an attribute is associated by examining the return value of `Scope.getAttribute(java.lang.String)`.

      Specified by:
        `hasAttribute` in interface `Scope`

    - #### hasAttribute

          public boolean hasAttribute​(java.lang.String name,
                                      boolean recurse)

      Description copied from interface: `Scope`
      Returns if a custom attribute is associated with this object.

      Notice that `null` is a valid value, so you can tell if an attribute is associated by examining the return value of `Scope.getAttribute(java.lang.String)`.

      Specified by:
        `hasAttribute` in interface `Scope`
        `recurse` - whether to search its ancestor scope. If true and the current scope doen't define the attribute, it searches up its ancestor to see any of them has defined the specified attribute.

    - #### setAttribute

          public java.lang.Object setAttribute​(java.lang.String name,
                                               java.lang.Object value)

      Description copied from interface: `Session`
      Sets the value of the specified custom attribute.
      Specified by:
        `setAttribute` in interface `Scope`
      Specified by:
        `setAttribute` in interface `Session`
      Returns:
        the previous value if any (since ZK 5)

    - #### setAttribute

          public java.lang.Object setAttribute​(java.lang.String name,
                                               java.lang.Object value,
                                               boolean recurse)

      Description copied from interface: `Scope`
      Sets the custom attribute associated with this scope, or the parent scope.
      Specified by:
        `setAttribute` in interface `Scope`
        `recurse` - whether to look up the parent scope for the existence of the attribute.
        If recurse is true and the attribute is defined in one of its ancestor (including page), the attribute is replaced. Otherwise, it is the same as `Scope.setAttribute(String,Object)`.

    - #### removeAttribute

          public java.lang.Object removeAttribute​(java.lang.String name,
                                                  boolean recurse)

      Description copied from interface: `Scope`
      Removes the custom attribute associated with this scope.
      Specified by:
        `removeAttribute` in interface `Scope`
        `recurse` - whether to look up the parent scope for the existence of the attribute.
        If recurse is true and the attribute is defined in one of its ancestor (including page), the attribute is removed. Otherwise, it is the same as `Scope.removeAttribute(String)`.

    - #### removeAttribute

          public java.lang.Object removeAttribute​(java.lang.String name)

      Description copied from interface: `Session`
      Removes the specified custom attribute.
      Specified by:
        `removeAttribute` in interface `Scope`
      Specified by:
        `removeAttribute` in interface `Session`
      Returns:
        the previous value if any (since ZK 5)

    - #### addScopeListener

          public boolean addScopeListener​(ScopeListener listener)

      Description copied from interface: `Scope`
      Adds a listener to listen whether this scope is changed. The listener is called when a custom attribute is added, removed, or the parent is changed.
      Specified by:
        `addScopeListener` in interface `Scope`
      Returns:
        weather the listener is added successfully. Note: if the resolver was added before, it won't be added again and this method returns false.

    - #### removeScopeListener

          public boolean removeScopeListener​(ScopeListener listener)

      Description copied from interface: `Scope`
      Removes a change listener from this scope.
      Specified by:
        `removeScopeListener` in interface `Scope`
      Returns:
        false if listener is not added before.

    - #### getAttributes

          public java.util.Map<java.lang.String,​java.lang.Object> getAttributes()

      Description copied from interface: `Session`
      Returns a map of custom attributes associated with this session.
      Specified by:
        `getAttributes` in interface `Scope`
      Specified by:
        `getAttributes` in interface `Session`

    - #### invalidateNow

          public void invalidateNow()

      Description copied from interface: `SessionCtrl`
      Really invalidates the session.

      Application shall never access this method.

      Specified by:
        `invalidateNow` in interface `SessionCtrl`

    - #### setMaxInactiveInterval

          public void setMaxInactiveInterval​(int interval)

      Description copied from interface: `Session`
      Specifies the time, in seconds, between client requests before the servlet container will invalidate this session. A negative time indicates the session should never timeout.
      Specified by:
        `setMaxInactiveInterval` in interface `Session`
      See Also:
        `Configuration.setTimerKeepAlive(boolean)`, `Configuration.setSessionMaxInactiveInterval(int)`

    - #### getMaxInactiveInterval

          public int getMaxInactiveInterval()

      Description copied from interface: `Session`
      Return the time, in seconds, between client requests before the servlet container will invalidate this session. A negative time indicates the session should never timeout.
      Specified by:
        `getMaxInactiveInterval` in interface `Session`
      See Also:
        `Configuration.isTimerKeepAlive()`, `Configuration.getSessionMaxInactiveInterval()`

    - #### getNativeSession

          public java.lang.Object getNativeSession()

      Description copied from interface: `Session`
      Returns the native session, or null if not available. The returned object depends on the type of clients. If HTTP, the object is an instance of javax.servlet.http.HttpSession. If portlet, the object is an instance of javax.portlet.PortletSession.
      Specified by:
        `getNativeSession` in interface `Session`

    - #### notifyClientRequest

          public boolean notifyClientRequest​(boolean keepAlive)

      Description copied from interface: `SessionCtrl`
      Notifies the session that a client request is received.
      Specified by:
        `notifyClientRequest` in interface `SessionCtrl`
      Parameters:
        `keepAlive` - if the request will keep the session alive, or the request shall be ignored. If the request shall be ignored and the session is timeout, it will cause the session to expire (i.e., be invalidated).
      Returns:
        whether the session is invalidated (since 6.0.0)

    - #### getWebApp

          public final WebApp getWebApp()

      Description copied from interface: `Session`
      Returns the Web application that this session belongs to.
      Specified by:
        `getWebApp` in interface `Session`

    - #### invalidate

          public final void invalidate()

      Description copied from interface: `Session`
      Invalidates this session then unbinds any objects bound to it.

      Note: you usually have to ask the client to redirect to another page (or reload the same page) by use of `Executions.sendRedirect(java.lang.String)`.

      The session is not invalidated immediately. Rather, it is invalidated after processing the current request.

      Specified by:
        `invalidate` in interface `Session`

    - #### isInvalidated

          public final boolean isInvalidated()

      Description copied from interface: `SessionCtrl`
      Returns whether this session is invalidated (i.e., `Session.invalidate()` was called).

      Note: ZK doesn't invalidate it immediately (until the event has been processed), so the session might be still alive.

      Specified by:
        `isInvalidated` in interface `SessionCtrl`

    - #### getDesktopCache

          public DesktopCache getDesktopCache()

      Description copied from interface: `SessionCtrl`
      Returns the desktop cache, or null if not available.

      Note: this is an utility to implement `DesktopCacheProvider`, which might or might not use this method. Other part of ZK shall not access this method.

      Specified by:
        `getDesktopCache` in interface `SessionCtrl`

    - #### setDesktopCache

          public void setDesktopCache​(DesktopCache cache)

      Description copied from interface: `SessionCtrl`
      Sets the desktop cache.

      Note: this is an utility to implement `DesktopCacheProvider`, which might or might not use this method. Other part of ZK shall not access this method.

      Specified by:
        `setDesktopCache` in interface `SessionCtrl`
      Parameters:
        `cache` - the desktop cache; null to denote no cache available.

    - #### recover

          public void recover​(java.lang.Object nativeSession)

      Description copied from interface: `SessionCtrl`
      Called when ZK detects `Session.getNativeSession()` is not initialized properly.

      It is actually a workaround to solve the issue that some Web container fails to call HttpSessionActivationListener.sessionDidActivate() upon failover.

      It can be used to solve the issue that the mapping between the native session and the ZK session is changed. For example, you might manually invalidate the http session and recreate one. Then, you have to call this method to associate the ZK session with the new created session.

      Specified by:
        `recover` in interface `SessionCtrl`

    - #### onDestroyed

          public void onDestroyed()

      Description copied from interface: `SessionCtrl`
      Called when the session is destroyed.

      Application shall never access this method.

      Specified by:
        `onDestroyed` in interface `SessionCtrl`

    - #### writeThis

          protected void writeThis​(java.io.ObjectOutputStream s)
                            throws java.io.IOException

      Used by the deriving class to write this object, only if the deriving class implements java.io.Serializable.
      Throws:
        `java.io.IOException`

    - #### readThis

          protected void readThis​(java.io.ObjectInputStream s)
                           throws java.io.IOException,
                                  java.lang.ClassNotFoundException

      Used by the deriving class to read back this object, only if the deriving class implements java.io.Serializable.
      Throws:
        `java.io.IOException`
        `java.lang.ClassNotFoundException`

    - #### sessionWillPassivate

          protected void sessionWillPassivate()

      Used by the deriving class to pre-process a session before writing the session

    - #### sessionDidActivate

          protected void sessionDidActivate​(javax.servlet.http.HttpSession hsess)

      Used by the deriving class to post-process a session after it is read back.

      Application shall not call this method directly.