Package com.tangosol.coherence.servlet

Interface HttpSessionCollection

  • All Known Subinterfaces:
    CoherenceHttpSessionCollection
    All Known Implementing Classes:
    AbstractHttpSessionCollection, MonolithicHttpSessionCollection, SplitHttpSessionCollection, TraditionalHttpSessionCollection
    public interface HttpSessionCollection
    This is the abstract model for a collection of HttpSessionModel objects. The interface is not at all concerned with how the sessions are communicated between the clients and the servers (e.g. cookies, URLs) and thus is decoupled from those concerns.

    Some of the methods presented on this interface may seem out-of-place and better located on the HttpSessionModel itself; however, the choice was made to place them on the collection (this interface) if their purpose is related to managing the model, and to place the methods on the model only if their purpose is related to accessing and manipulating the data represented by the session model itself. This helps to simplify the model, making it a logical terminal (an object that is not dependent on other objects in the framework).

    For consistency purposes, the API takes the session ID as a parameter, even when the HttpSessionModel reference is expected to be available.

    There are three different session state transitions that the collection is responsible for managing. The first is existence: A session enters the exists state as a result of the create() method, and is transitioned back to the does not exist state only by the destroy() method.

    The second transition is ownership. Ownership refers to the ability for a deployer to specify that a session be owned by a particular thread, application or server at a time, such that only that one thread, application or server could modify the session, blocking any other thread, application or server attempting to access the same session. (Note that "thread" level ownership is actually "server+application+thread" ownership, since it implies that only one thread in the entire cluster will own the session at a time. Likewise, "application" level ownership is actually "server+application" ownership, since it implies that only one application in the entire cluster will own the session at a time, while "server" level ownership implies that multiple threads from potentially multiple applications on the same server can access the session at the same time.) The state transition is from not owned to owned state as a result of the enter() method, and from owned to not owned as a result of the exit() method. Since the deployer may choose to allow multiple threads on multiple applications on multiple servers to access the same session at the same time (a legitimate choice for many applications, assuming that the session management implementation supports it), the state transition can be reduced to a no-op, or it can be as complex as using cluster-wide locking and application and thread level synchronization on a server. Even more complex is the ability for multiple threads from potentially multiple applications on the same server to access the session, while maintaining ownership for that session on that server; this implies a sub-attribute of the ownership state to be a thread-or reference-count.

    As an added complexity for the ownership state, when a session is created it is considered to be owned, as if the enter() method were called as part of the create() method's processing. This implies that, when an HTTP request results in a session being created, the request processing must invoke the exit() method although the enter() method has not been invoked. Correspondingly, the destroy() method will release the ownership state, implying that the exit() method should not be called in this case.

    The third transition is activation. Activation refers to a state in which the session can be manipulated, such that it is considered to be "alive" on a particular server in the cluster. This primarily relates to the optional event interface (HttpSessionActivationListener) that session attributes can implement to find out when the session is passivated and activated. Moreover, it implies strict adherence to the specification such that a session is only able to be "alive" on one server at a time. (Since such strict adherence may not be desired, it is possible to disable its side-effects. However, like the ownership state, disabling the feature is the easy part, while providing the feature is singularly daunting.) The state transition is from passive to active state as a result of the activate() method, and from active to passive as a result of the passivate() method.

    The combination of the ownership and activation state transitions introduces a potential logical deadlock, resulting from the following set of rules:

    • The session must be owned before activate() or passivate() can be invoked for that session.
    • Only one thread, applicaton, or JVM can logically own the session at a time.
    The result is that a thread may request the ownership for a session, and succeed in obtaining it. It may then request the activation of the session, which could first require the passivation of the same session on another server in the cluster (assuming a lazy passivation implementation, which is a good assumption if performance is an important attribute of the implementation.) The result is that the other server must gain ownership of the session in order to passivate it, but the ownership has already been claimed by the server attempting to activate the session. The solution to this logical deadlock is similar to how Java's own synchronization works with respect to the Object.wait method, in that the ownership is given up temporarily until notification is received to continue. Similarly, an implementation that handles the problem described above must be able to "wait" for the session to be passivated on the other server, allowing that other server to gain ownership temporarily for the purpose of passivating the session.

    An extremely strict implementation would not suffer from this problem, in that it would always passivate the session (which is to say, it would always notify the session attributes of their passivation) at the end of each request, and it would limit concurrent access to the session to the thread level (i.e. only one thread could access the session at a time.) The result is that, even in the case of unexpected server failure, the passivation would have occurred if the request completed successfully, thus allowing activation to occur without concern once the ownership state is owned as a result of the enter() method.

    If the class implementating this interface requires configuration information, it should implement the XmlConfigurable interface.

    Version:
    Coherence 2.3
    Author:
    cp 2003.07.29

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Interface Description
      static interface  HttpSessionCollection.AttributeScopeController
      The AttributeScopeController is an optional interface that is used to selectively scope attributes in cases when a session may be shared across more than one application.
      static interface  HttpSessionCollection.SessionDistributionController
      An optional interface to override the default distribution of session objects in the cluster, allowing the sessions to remain "local" to the originating application until a later point in the life of the session, that point determined by the implementation of this interface.

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void activate​(String sId, javax.servlet.http.HttpSession session)
      Move the session into an active state, if it is not already.
      void addHttpSessionAttributeListener​(javax.servlet.http.HttpSessionAttributeListener listener)
      Sign up the specified listener to receive HttpSessionBindingEvent objects.
      void addHttpSessionListener​(javax.servlet.http.HttpSessionListener listener)
      Sign up the specified listener to receive HttpSessionEvent objects.
      HttpSessionModel create​(javax.servlet.http.HttpSession session)
      This method creates a new session, returning the session model for the new session.
      HttpSessionModel create​(javax.servlet.http.HttpSession session, String sId)
      This method attempts to create a new session with a specific ID, returning the session model for the new session.
      Set<String> deleteExpiredLocalSessions()
      Deletes the locally opened sessions in the session-cache which have timed out, using an EntryProcessor and return the ids of the deleted sessions.
      Set<String> deleteExpiredSessions()
      Delete the sessions in the session-cache which have timed out, using an EntryProcessor and return the ids of deleted sessions.
      void destroy​(String sId)
      Destroy the specified session.
      boolean enter​(String sId, boolean fWait)
      Obtain any necessary ownership for the specified session.
      boolean enter​(String sId, boolean fWait, boolean fExclusive)
      Obtain any necessary ownership for the specified session.
      void exit​(String sId, boolean fFlush)
      Release ownership for the specified session.
      void exit​(String sId, boolean fFlush, boolean fExclusive)
      Release ownership for the specified session.
      HttpSessionModel get​(String sId)
      Obtain the HttpSessionModel for the specified session, or null if it does not exist.
      Serializer getSerializer()
      Get the serializer used to serialize and deserialize session attributes.
      boolean isActive​(String sId)
      Determine if the specified session ID identifies a session that is in the active state.
      boolean isExistent​(String sId)
      Determine if the specified session ID identifies a session that exists.
      boolean isOwned​(String sId)
      Determine if the specified session ID identifies a session that exists and that this thread has ownership for, either by a call to enter(sId) or create() without a corresponding call to exit(sId).
      Iterator iterateIds()
      Obtain an iterator of the session IDs.
      Iterator iteratePotentiallyExpiredIds()
      Obtain an iterator of the session IDs that this JVM is responsible for invalidating when the sessions for those IDs have timed out.
      Iterator iteratePotentiallyExpiredLocalIds()
      Obtain an iterator of the locally opened session IDs that are opened in this web application instance and have timed out.
      void passivate​(String sId)
      Move the session into a passive state, if it is not already.
      void postCreate​(javax.servlet.http.HttpSession session)
      This method is called at the end of the session creation process.
      void removeHttpSessionAttributeListener​(javax.servlet.http.HttpSessionAttributeListener listener)
      Sign off the specified listener so it no longer will receive HttpSessionBindingEvent objects.
      void removeHttpSessionListener​(javax.servlet.http.HttpSessionListener listener)
      Sign off the specified listener so it no longer will receive HttpSessionEvent objects.
      void setSerializer​(Serializer serializer)
      Set the serializer used to serialize and deserialize session attributes.
      void shutdown()
      Notify the session collection that it is being shut down.

    • Method Detail

      • create

        HttpSessionModel create​(javax.servlet.http.HttpSession session)
        This method creates a new session, returning the session model for the new session.

        The session is created with the default timeout, and has an ID that is unique within the domain that the session management layer is configured for (e.g. within the JVM, or within the cluster.)

        When the session model is returned, the session state is exists, owned, active. Note that the responsibilities associated with the enter() method are included as part of the session creation process.

        The model will retain the reference to the HttpSession object until it is passivated or destroyed.

        Parameters:
        session - the HttpSession object to bind the session model to; used for issuing events; must not be null
        Returns:
        the HttpSessionModel object for the new session

      • create

        HttpSessionModel create​(javax.servlet.http.HttpSession session,
                        String sId)
        This method attempts to create a new session with a specific ID, returning the session model for the new session. It is assumed that the specified ID isn't used by any existing session.

        The session is created with the default timeout.

        When the session model is returned, the session state is exists, owned, active. Note that the responsibilities associated with the enter() method are included as part of the session creation process.

        The model will retain the reference to the HttpSession object until it is passivated or destroyed.

        Parameters:
        session - the HttpSession object to bind the session model to; used for issuing events; must not be null
        sId - the session ID
        Returns:
        the HttpSessionModel object for the new session, or null if a session with the passed in sessionID already exists.

      • postCreate

        void postCreate​(javax.servlet.http.HttpSession session)
        This method is called at the end of the session creation process.

        When this method is called, the session state is exists, owned, active.

        Parameters:
        session - the HttpSession object; must not be null

      • isExistent

        boolean isExistent​(String sId)
        Determine if the specified session ID identifies a session that exists.

        The notion of ownership will affect whether or not the answer can be trusted once the method has returned it. If the ownership state is owned (the current thread called enter(sId)), then the caller should assume that session still exists. Otherwise, the caller can only assume that the session did exist at the point in time that the call to this method was made.

        Parameters:
        sId - the session ID to check for existence
        Returns:
        true if the session exists; false otherwise

      • destroy

        void destroy​(String sId)
        Destroy the specified session.

        This method may only be called on a session that is exists, owned, active.

        Session attributes will receive HttpSessionBindingListener as per the Servlet specification.

        At the return point from this method, the session state is does not exist. Note that the responsibilities associated with the exit(sId) method are included as part of the session destruction process.

        After this method completes, the model's HttpSession reference will be null.

        Parameters:
        sId - the session ID; must not be null

      • getSerializer

        Serializer getSerializer()
        Get the serializer used to serialize and deserialize session attributes.
        Returns:
        a serializer; never null

      • setSerializer

        void setSerializer​(Serializer serializer)
        Set the serializer used to serialize and deserialize session attributes.
        Parameters:
        serializer - a serializer; must not be null

      • enter

        boolean enter​(String sId,
              boolean fWait)
        Obtain any necessary ownership for the specified session. Ownership requirements are expected to be declarative, so this method may be a no-op, or it may involve thread-level, application-level, or even cluster-wide locking.

        If the session specified by the session ID does not exist, then this method has no effect; no exception is thrown.

        This method must support Multiple Possession Semantics, meaning that this method may be invoked multiple times, and each invocation will require a corresponding call to the exit(sId) method in order to release the ownership.

        Parameters:
        sId - the session ID; must not be null
        fWait - true if the thread should block until the session becomes available; false otherwise
        Returns:
        true if the session is now owned by the calling thread

      • enter

        boolean enter​(String sId,
              boolean fWait,
              boolean fExclusive)
        Obtain any necessary ownership for the specified session. Ownership requirements are expected to be declarative, so this method may be a no-op, or it may involve thread-level, application-level, or even cluster-wide locking.

        If the session specified by the session ID does not exist, then this method has no effect; no exception is thrown.

        This method must support Multiple Possession Semantics, meaning that this method may be invoked multiple times, and each invocation will require a corresponding call to the exit(sId) method in order to release the ownership.

        Parameters:
        sId - the session ID; must not be null
        fWait - true if the thread should block until the session becomes available; false otherwise
        fExclusive - if true, prevent other threads from entering the specified session until a corresponding call to exit(String, boolean, boolean) is made by the calling thread
        Returns:
        true if the session is now owned by the calling thread

      • isOwned

        boolean isOwned​(String sId)
        Determine if the specified session ID identifies a session that exists and that this thread has ownership for, either by a call to enter(sId) or create() without a corresponding call to exit(sId). NOTE! Since an asynchronous exit task could have been scheduled by SessionHelper.requestAsyncOwnership(String), this method should not be used to determine if exit should be called or not.
        Parameters:
        sId - the session ID; must not be null
        Returns:
        true if the session is owned; false otherwise.

      • exit

        void exit​(String sId,
          boolean fFlush)
        Release ownership for the specified session. This method must be called exactly once for each call to enter(sId), with the only exceptions being:
        • If the session no longer exists, exit should not be called.
        • If the session was created as part of the HTTP request processing, this method must be invoked even though the corresponding enter(sId) method was never invoked.

        When ownership state of a new session changes from owned to not owned, the session will no longer be considered new.

        If the session specified by the session ID does not exist, then this method has no effect; no exception is thrown.

        Parameters:
        sId - the session ID; must not be null
        fFlush - pass true if the session has been potentially modified; even then, there's no guarantee that the session state will be flushed if there is another thread that is using the session concurrently. In this case, the last exiting thread will flush

      • exit

        void exit​(String sId,
          boolean fFlush,
          boolean fExclusive)
        Release ownership for the specified session. This method must be called exactly once for each call to enter(sId), with the only exceptions being:
        • If the session no longer exists, exit should not be called.
        • If the session was created as part of the HTTP request processing, this method must be invoked even though the corresponding enter(sId) method was never invoked.

        When ownership state of a new session changes from owned to not owned, the session will no longer be considered new.

        If the session specified by the session ID does not exist, then this method has no effect; no exception is thrown.

        Parameters:
        sId - the session ID; must not be null
        fFlush - pass true if the session has been potentially modified; even then, there's no guarantee that the session state will be flushed if there is another thread that is using the session concurrently. In this case, the last exiting thread will flush
        fExclusive - if true, a previous call to enter(String, boolean, boolean) should have been made where the fExclusive was set to true

      • activate

        void activate​(String sId,
              javax.servlet.http.HttpSession session)
        Move the session into an active state, if it is not already. The active state is defined as the state in which the session is considered to be "live" in a particular JVM. This primarily relates to the optional event interfce (HttpSessionActivationListener) that session attributes can implement to find out when the session is passivated and activated.

        Invoking this method will issue activation events for session attributes that implement the HttpSessionActivationListener interface. The model will retain the reference to the HttpSession object until it is passivated or destroyed.

        Parameters:
        sId - the session ID; must not be null
        session - the HttpSession object to bind the session model to; used for issuing events; must not be null

      • isActive

        boolean isActive​(String sId)
        Determine if the specified session ID identifies a session that is in the active state.

        This method may only be called within the bounds of a call to enter(sId) and exit(sId).

        Parameters:
        sId - the session ID to check for the active state
        Returns:
        true if the session exists and is active; false otherwise

      • passivate

        void passivate​(String sId)
        Move the session into a passive state, if it is not already.

        Invoking this method will issue passivation events for session attributes that implement the HttpSessionActivationListener interface.

        After this method completes, the model's HttpSession reference will be null.

        Parameters:
        sId - the session ID; must not be null

      • deleteExpiredSessions

        Set<String> deleteExpiredSessions()
        Delete the sessions in the session-cache which have timed out, using an EntryProcessor and return the ids of deleted sessions.
        Returns:
        the set of ids of sessions that are deleted

      • deleteExpiredLocalSessions

        Set<String> deleteExpiredLocalSessions()
        Deletes the locally opened sessions in the session-cache which have timed out, using an EntryProcessor and return the ids of the deleted sessions.
        Returns:
        the set of ids of sessions that are deleted

      • iterateIds

        Iterator iterateIds()
        Obtain an iterator of the session IDs.

        The list of IDs is completely dynamic because of the nature of multi-threaded and distributed systems. The fact that an ID is returned from an iterator is no guarantee that the ID is still valid.

        Returns:
        an iterator that iterates over all String session IDs

      • iteratePotentiallyExpiredIds

        Iterator iteratePotentiallyExpiredIds()
        Obtain an iterator of the session IDs that this JVM is responsible for invalidating when the sessions for those IDs have timed out.

        This may return an iterator with the same contents as the one returned by the iterateIds() method, or it may return an iterator that iterates over a subset of those contents.

        The list of IDs is completely dynamic because of the nature of multi-threaded and distributed systems. The fact that an ID is returned from an iterator is no guarantee that the ID is still valid, or that it has expired.

        Returns:
        an iterator that iterates over the session IDs that this JVM is responsible for periodically checking for expiry
        Since:
        Coherence 3.5 replaced iterateLocalIds()

      • iteratePotentiallyExpiredLocalIds

        Iterator iteratePotentiallyExpiredLocalIds()
        Obtain an iterator of the locally opened session IDs that are opened in this web application instance and have timed out. Ideally, an implementation should use an EntryProcessor to filter the local session set and return only timed out sessions
        Returns:
        an iterator that iterates over the session IDs that are local to this web application instance and has timed out

      • get

        HttpSessionModel get​(String sId)
        Obtain the HttpSessionModel for the specified session, or null if it does not exist.

        This method may only be called within the bounds of a call to enter(sId) and exit(sId).

        Parameters:
        sId - the session ID; must not be null
        Returns:
        the HttpSessionModel for the requested session or null

      • addHttpSessionListener

        void addHttpSessionListener​(javax.servlet.http.HttpSessionListener listener)
        Sign up the specified listener to receive HttpSessionEvent objects.
        Parameters:
        listener - the HttpSessionListener to sign up for events

      • removeHttpSessionListener

        void removeHttpSessionListener​(javax.servlet.http.HttpSessionListener listener)
        Sign off the specified listener so it no longer will receive HttpSessionEvent objects.
        Parameters:
        listener - the HttpSessionListener that was previously signed up for events

      • addHttpSessionAttributeListener

        void addHttpSessionAttributeListener​(javax.servlet.http.HttpSessionAttributeListener listener)
        Sign up the specified listener to receive HttpSessionBindingEvent objects.
        Parameters:
        listener - the HttpSessionAttributeListener to sign up for events

      • removeHttpSessionAttributeListener

        void removeHttpSessionAttributeListener​(javax.servlet.http.HttpSessionAttributeListener listener)
        Sign off the specified listener so it no longer will receive HttpSessionBindingEvent objects.
        Parameters:
        listener - the HttpSessionAttributeListener that was previously signed up for events

      • shutdown

        void shutdown()
        Notify the session collection that it is being shut down. After this method invocation has been made, the session collection may throw IllegalStateException for any subsequent method invocation made to it.