Package ratpack.session

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 Summary

Modifier and Type	Method	Description
void	clear()	Remove all entries from the session data.
default <T> Optional<T>	get(Class<T> type)	Read the object with the given type, and no name, using the default serializer.
default <T> Optional<T>	get(Class<T> type, SessionSerializer serializer)	Read the object with the given type, and no name.
default Optional<?>	get(String name)	Read the object with the given name, using the default serializer.
default Optional<?>	get(String name, SessionSerializer serializer)	Read the object with the given name.
default <T> Optional<T>	get(SessionKey<T> key)	Fetch the object with the given key, using the default serializer.
<T> Optional<T>	get(SessionKey<T> key, SessionSerializer serializer)	Read the object with the given key.
default SessionSerializer	getDefaultSerializer()	See Session.getDefaultSerializer().
default JavaSessionSerializer	getJavaSerializer()	See Session.getJavaSerializer().
Set<SessionKey<?>>	getKeys()	The keys of all objects currently in the session.
Session	getSession()	The corresponding Session object.
default boolean	isDirty()	See Session.isDirty().
default void	remove(Class<?> type)	Removes the object with the given type and no name, if it exists.
default void	remove(String name)	Removes the object with the name, if it exists.
void	remove(SessionKey<?> key)	Removes the object with the given key, if it exists.
default <T> T	require(Class<T> type)	Like get(Class), but throws NoSuchElementException on the absence of a value.
default <T> T	require(Class<T> type, SessionSerializer serializer)	Like get(Class, SessionSerializer), but throws NoSuchElementException on the absence of a value.
default Object	require(String name)	Like get(String), but throws NoSuchElementException on the absence of a value.
default Object	require(String name, SessionSerializer serializer)	Like get(String, SessionSerializer), but throws NoSuchElementException on the absence of a value.
default <T> T	require(SessionKey<T> key)	Like get(SessionKey), but throws NoSuchElementException on the absence of a value.
default <T> T	require(SessionKey<T> key, SessionSerializer serializer)	Like get(SessionKey, SessionSerializer), but throws NoSuchElementException on the absence of a value.
default Operation	save()	See Session.save().
default <T> void	set(Class<T> type, T value)	Sets the value for the given type, using the default serializer.
default <T> void	set(Class<T> type, T value, SessionSerializer serializer)	Sets the value for the given type.
default <T> void	set(String name, T value)	Sets the value for the given name and type, using the runtime type of the value and the default serializer.
default <T> void	set(String name, T value, SessionSerializer serializer)	Sets the value for the given name and type, using the runtime type of the value.
default <T> void	set(SessionKey<T> key, T value)	Sets the value for the given key, using the default serializer.
<T> void	set(SessionKey<T> key, T value, SessionSerializer serializer)	Sets the value for the given key.
default <T> void	set(T value)	Sets the value for the type, using the runtime type of the value and the default serializer.
default <T> void	set(T value, SessionSerializer serializer)	Sets the value for the type, using the runtime type of the value.
default Operation	terminate()	See Session.terminate().

Method Detail

getKeys

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> Optional<T> get(SessionKey<T> key)
                     throws 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:

Exception

See Also:

require(SessionKey)

get

<T> Optional<T> get(SessionKey<T> key,
                    SessionSerializer serializer)
             throws 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:

Exception

See Also:

require(SessionKey, SessionSerializer)

get

default Optional<?> get(String name)
                 throws 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:

Exception

See Also:

require(String)

get

default Optional<?> get(String name,
                        SessionSerializer serializer)
                 throws 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:

Exception

See Also:

require(String, SessionSerializer)

get

default <T> Optional<T> get(Class<T> type)
                     throws 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:

Exception

See Also:

require(Class)

get

default <T> Optional<T> get(Class<T> type,
                            SessionSerializer serializer)
                     throws 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:

Exception

See Also:

require(Class, SessionSerializer)

require

default <T> T require(SessionKey<T> key)
               throws 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:

Exception

require

default <T> T require(SessionKey<T> key,
                      SessionSerializer serializer)
               throws 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:

Exception

require

default <T> T require(Class<T> type)
               throws 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:

Exception

require

default <T> T require(Class<T> type,
                      SessionSerializer serializer)
               throws 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:

Exception

require

default Object require(String name)
                throws 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:

Exception

require

default Object require(String name,
                       SessionSerializer serializer)
                throws 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:

Exception

set

default <T> void set(SessionKey<T> key,
                     T value)
              throws 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:

Exception

set

<T> void set(SessionKey<T> key,
             T value,
             SessionSerializer serializer)
      throws Exception

Sets the value for the given key.

Type Parameters:

T - the type

Parameters:

key - the key

value - the value

serializer - the serializer

Throws:

Exception

set

default <T> void set(Class<T> type,
                     T value)
              throws 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:

Exception

set

default <T> void set(Class<T> type,
                     T value,
                     SessionSerializer serializer)
              throws Exception

Sets the value for the given type.

Type Parameters:

T - the type

Parameters:

type - the type

value - the value

serializer - the serializer

Throws:

Exception

set

default <T> void set(String name,
                     T value)
              throws 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:

Exception

set

default <T> void set(String name,
                     T value,
                     SessionSerializer serializer)
              throws 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:

Exception

set

default <T> void set(T value)
              throws 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:

Exception

set

default <T> void set(T value,
                     SessionSerializer serializer)
              throws 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:

Exception

remove

void remove(SessionKey<?> key)

Removes the object with the given key, if it exists.

Parameters:

key - the key

remove

default void remove(Class<?> type)

Removes the object with the given type and no name, if it exists.

Parameters:

type - the type

remove

default void remove(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()

See Session.isDirty().

Returns:

whether or not any changes have been made to the session data since it was accessed

save

default Operation save()

See Session.save().

Returns:

the save operation

terminate

default Operation terminate()

See Session.terminate().

Returns:

the terminate operation

getDefaultSerializer

default SessionSerializer getDefaultSerializer()

See Session.getDefaultSerializer().

Returns:

the serializer to use by default

getJavaSerializer

default JavaSessionSerializer getJavaSerializer()

See Session.getJavaSerializer().

Returns:

a serializer for Serializable objects