Interface SessionData


  • public interface SessionData
    The data associated with the user session.

    The session data can be obtained via the Session.getData() method.

    Every item is stored with a SessionKey. A key is comprised of a type (as a Class) and an optional name. The combination of type and name identifies the value. Two keys with differing types but identical names are not considered to be equivalent.

    When writing session data, the values are serialized immediately. That is, all objects are treated as immutable value objects from the perspective of this object. Any changes made to an object after it has been written to this object will NOT be persisted. If such changes are to be persisted, the object must be written again.

    If a SessionSerializer is not provided for a given get/set, the getDefaultSerializer() will be used. The SessionModule provides a default implementation based on Java serialization. An alternative implementation can be used by overriding the Guice binding for SessionSerializer.

    The session data is held in memory for a given request until the Session.save() method is called on the corresponding session. However, this object internally holds the data in serialized form. Therefore, every read and write incurs the cost of serialization and deserialization.

    • Method Detail

      • getKeys

        java.util.Set<SessionKey<?>> getKeys()
        The keys of all objects currently in the session.
        Returns:
        the keys of all objects currently in the session
      • get

        default <T> java.util.Optional<T> get​(SessionKey<T> key)
                                       throws java.lang.Exception
        Fetch the object with the given key, using the default serializer.
        Type Parameters:
        T - the type of object
        Parameters:
        key - the key
        Returns:
        the value for the given key
        Throws:
        java.lang.Exception
        See Also:
        require(SessionKey)
      • get

        <T> java.util.Optional<T> get​(SessionKey<T> key,
                                      SessionSerializer serializer)
                               throws java.lang.Exception
        Read the object with the given key.
        Type Parameters:
        T - the type of object
        Parameters:
        key - the key
        serializer - the serializer
        Returns:
        the value for the given key
        Throws:
        java.lang.Exception
        See Also:
        require(SessionKey, SessionSerializer)
      • get

        default java.util.Optional<?> get​(java.lang.String name)
                                   throws java.lang.Exception
        Read the object with the given name, using the default serializer.

        This method will throw an IllegalArgumentException if there is more than one object who's key has the given name.

        Parameters:
        name - the object name
        Returns:
        the value for the given key
        Throws:
        java.lang.Exception
        See Also:
        require(String)
      • get

        default java.util.Optional<?> get​(java.lang.String name,
                                          SessionSerializer serializer)
                                   throws java.lang.Exception
        Read the object with the given name.

        This method will throw an IllegalArgumentException if there is more than one object who's key has the given name.

        Parameters:
        name - the object name
        serializer - the serializer
        Returns:
        the value for the given key
        Throws:
        java.lang.Exception
        See Also:
        require(String, SessionSerializer)
      • get

        default <T> java.util.Optional<T> get​(java.lang.Class<T> type)
                                       throws java.lang.Exception
        Read the object with the given type, and no name, using the default serializer.
        Type Parameters:
        T - the type
        Parameters:
        type - the type
        Returns:
        the value for the given key
        Throws:
        java.lang.Exception
        See Also:
        require(Class)
      • get

        default <T> java.util.Optional<T> get​(java.lang.Class<T> type,
                                              SessionSerializer serializer)
                                       throws java.lang.Exception
        Read the object with the given type, and no name.
        Type Parameters:
        T - the type
        Parameters:
        type - the type
        serializer - the serializer
        Returns:
        the value for the given key
        Throws:
        java.lang.Exception
        See Also:
        require(Class, SessionSerializer)
      • require

        default <T> T require​(SessionKey<T> key)
                       throws java.lang.Exception
        Like get(SessionKey), but throws NoSuchElementException on the absence of a value.
        Type Parameters:
        T - the type
        Parameters:
        key - the object key
        Returns:
        the value for the given key
        Throws:
        java.lang.Exception
      • require

        default <T> T require​(SessionKey<T> key,
                              SessionSerializer serializer)
                       throws java.lang.Exception
        Like get(SessionKey, SessionSerializer), but throws NoSuchElementException on the absence of a value.
        Type Parameters:
        T - the type
        Parameters:
        key - the object key
        serializer - the serializer
        Returns:
        the value for the given key
        Throws:
        java.lang.Exception
      • require

        default <T> T require​(java.lang.Class<T> type)
                       throws java.lang.Exception
        Like get(Class), but throws NoSuchElementException on the absence of a value.
        Type Parameters:
        T - the type
        Parameters:
        type - the type
        Returns:
        the value for the given key
        Throws:
        java.lang.Exception
      • require

        default <T> T require​(java.lang.Class<T> type,
                              SessionSerializer serializer)
                       throws java.lang.Exception
        Like get(Class, SessionSerializer), but throws NoSuchElementException on the absence of a value.
        Type Parameters:
        T - the type
        Parameters:
        type - the type
        serializer - the serializer
        Returns:
        the value for the given key
        Throws:
        java.lang.Exception
      • require

        default java.lang.Object require​(java.lang.String name)
                                  throws java.lang.Exception
        Like get(String), but throws NoSuchElementException on the absence of a value.

        This method will throw an IllegalArgumentException if there is more than one object who's key has the given name.

        Parameters:
        name - the object name
        Returns:
        the value for the given key
        Throws:
        java.lang.Exception
      • require

        default java.lang.Object require​(java.lang.String name,
                                         SessionSerializer serializer)
                                  throws java.lang.Exception
        Like get(String, SessionSerializer), but throws NoSuchElementException on the absence of a value.

        This method will throw an IllegalArgumentException if there is more than one object who's key has the given name.

        Parameters:
        name - the object name
        serializer - the serializer
        Returns:
        the value for the given key
        Throws:
        java.lang.Exception
      • set

        default <T> void set​(SessionKey<T> key,
                             T value)
                      throws java.lang.Exception
        Sets the value for the given key, using the default serializer.
        Type Parameters:
        T - the type
        Parameters:
        key - the key
        value - the value
        Throws:
        java.lang.Exception
      • set

        <T> void set​(SessionKey<T> key,
                     T value,
                     SessionSerializer serializer)
              throws java.lang.Exception
        Sets the value for the given key.
        Type Parameters:
        T - the type
        Parameters:
        key - the key
        value - the value
        serializer - the serializer
        Throws:
        java.lang.Exception
      • set

        default <T> void set​(java.lang.Class<T> type,
                             T value)
                      throws java.lang.Exception
        Sets the value for the given type, using the default serializer.
        Type Parameters:
        T - the type
        Parameters:
        type - the type
        value - the value
        Throws:
        java.lang.Exception
      • set

        default <T> void set​(java.lang.Class<T> type,
                             T value,
                             SessionSerializer serializer)
                      throws java.lang.Exception
        Sets the value for the given type.
        Type Parameters:
        T - the type
        Parameters:
        type - the type
        value - the value
        serializer - the serializer
        Throws:
        java.lang.Exception
      • set

        default <T> void set​(java.lang.String name,
                             T value)
                      throws java.lang.Exception
        Sets the value for the given name and type, using the runtime type of the value and the default serializer.
        Type Parameters:
        T - the type
        Parameters:
        name - the name
        value - the value
        Throws:
        java.lang.Exception
      • set

        default <T> void set​(java.lang.String name,
                             T value,
                             SessionSerializer serializer)
                      throws java.lang.Exception
        Sets the value for the given name and type, using the runtime type of the value.
        Type Parameters:
        T - the type
        Parameters:
        name - the name
        value - the value
        serializer - the serializer
        Throws:
        java.lang.Exception
      • set

        default <T> void set​(T value)
                      throws java.lang.Exception
        Sets the value for the type, using the runtime type of the value and the default serializer.
        Type Parameters:
        T - the type
        Parameters:
        value - the value
        Throws:
        java.lang.Exception
      • set

        default <T> void set​(T value,
                             SessionSerializer serializer)
                      throws java.lang.Exception
        Sets the value for the type, using the runtime type of the value.
        Type Parameters:
        T - the type
        Parameters:
        value - the value
        serializer - the serializer
        Throws:
        java.lang.Exception
      • remove

        void remove​(SessionKey<?> key)
        Removes the object with the given key, if it exists.
        Parameters:
        key - the key
      • remove

        default void remove​(java.lang.Class<?> type)
        Removes the object with the given type and no name, if it exists.
        Parameters:
        type - the type
      • remove

        default void remove​(java.lang.String name)
        Removes the object with the name, if it exists.

        This method will throw a NoSuchElementException if there are more than one entries with the given name.

        Parameters:
        name - the name
      • clear

        void clear()
        Remove all entries from the session data.
      • getSession

        Session getSession()
        The corresponding Session object.
        Returns:
        the session object
      • isDirty

        default boolean isDirty()
        Returns:
        whether or not any changes have been made to the session data since it was accessed