public interface Session
Sessions are created on demand via: Request.session()
.
Sessions have a lot of uses cases but most commons are: auth, store information about current user, etc.
A session attribute must be String
or a primitive. Session doesn't allow to store
arbitrary objects. It is a simple mechanism to store basic data.
There is no timeout for sessions from server perspective. By default, a session will expire when the user close the browser (a.k.a session cookie).
A Session.Store
is responsible for saving session data. Sessions are kept in memory, by
default using the Session.Mem
store, which is useful for development, but wont scale well
on production environments. An redis, memcached, ehcache store will be a better option.
Sessions are persisted every time a request exit, if they are dirty. A session get dirty if an attribute is added or removed from it.
The session.saveInterval
property indicates how frequently a session will be
persisted (in millis).
In short, a session is persisted when: 1) it is dirty; or 2) save interval has expired it.
Next session describe the most important options:
The session.cookie.maxAge
sets the maximum age in seconds. A positive value
indicates that the cookie will expire after that many seconds have passed. Note that the value is
the maximum age when the cookie will expire, not the cookie's current age.
A negative value means that the cookie is not stored persistently and will be deleted when the
Web browser exits.
Default maxAge is: -1
.
If the application.secret
property has been set, then the session cookie will be
signed it with it.
The session.cookie.name
indicates the name of the cookie that hold the session ID,
by defaults: jooby.sid
. Cookie's name can be explicitly set with
Cookie.Definition.name(String)
on Session.Definition.cookie()
.
Modifier and Type | Interface and Description |
---|---|
static interface |
Session.Builder
Build or restore a session from a persistent storage.
|
static class |
Session.Definition
Hold session related configuration parameters.
|
static class |
Session.Destroyed
Throw when session access is required but the session has been destroyed.\
See
destroy() . |
static class |
Session.Mem
A keep in memory session store.
|
static interface |
Session.Store
Read, save and delete sessions from a persistent storage.
|
Modifier and Type | Field and Description |
---|---|
static String |
COOKIE_SESSION
Global/Shared id of cookie sessions.
|
Modifier and Type | Method and Description |
---|---|
long |
accessedAt()
The last time the client sent a request associated with this session, as the number of
milliseconds since midnight January 1, 1970 GMT, and marked by the time the container
received the request.
|
Map<String,String> |
attributes() |
long |
createdAt()
The time when this session was created, measured in milliseconds since midnight January 1, 1970
GMT for server side sessions.
|
void |
destroy()
Invalidates this session then unset any objects bound to it.
|
long |
expiryAt()
The time when this session is going to expire, measured in milliseconds since midnight
January 1, 1970 GMT.
|
Mutant |
get(String name)
Get a object from this session.
|
String |
id()
A session ID for server side sessions.
|
boolean |
isDestroyed()
True if the session was
destroy() . |
boolean |
isSet(String name)
Test if the var name exists inside the session local attributes.
|
Session |
renewId()
Assign a new ID to the existing session.
|
long |
savedAt()
Last time the session was save it as epoch millis or
-1 for client side sessions. |
default Session |
set(String name,
boolean value)
Set a session local using a the given name.
|
default Session |
set(String name,
byte value)
Set a session local using a the given name.
|
default Session |
set(String name,
char value)
Set a session local using a the given name.
|
default Session |
set(String name,
CharSequence value)
Set a session local using a the given name.
|
default Session |
set(String name,
double value)
Set a session local using a the given name.
|
default Session |
set(String name,
float value)
Set a session local using a the given name.
|
default Session |
set(String name,
int value)
Set a session local using a the given name.
|
default Session |
set(String name,
long value)
Set a session local using a the given name.
|
default Session |
set(String name,
short value)
Set a session local using a the given name.
|
Session |
set(String name,
String value)
Set a session local using a the given name.
|
Session |
unset()
Unset/remove all the session data.
|
Mutant |
unset(String name)
Remove a local value (if any) from session locals.
|
static final String COOKIE_SESSION
@Nonnull String id()
COOKIE_SESSION
for client side sessions.
Session ID on client sessions doesn't make sense because resolution of session is done via
cookie name.
Another reason of not saving the session ID inside the cookie, is the cookie size (up to 4kb).
If the session ID is persisted then users lost space to save business data.long createdAt()
-1
for client side sessions.-1
for client side sessions.long savedAt()
-1
for client side sessions.-1
for client side
sessions.long accessedAt()
-1
for client side sessions.
Actions that your application takes, such as getting or setting a value associated with the session, do not affect the access time.
-1
for client side sessions.long expiryAt()
-1
for client side sessions.-1
for client side sessions.@Nonnull Mutant get(String name)
name
- Attribute's name.boolean isSet(String name)
name
- A local var's name.@Nonnull default Session set(String name, byte value)
name
- Attribute's name.value
- Attribute's value.@Nonnull default Session set(String name, char value)
name
- Attribute's name.value
- Attribute's value.@Nonnull default Session set(String name, boolean value)
name
- Attribute's name.value
- Attribute's value.@Nonnull default Session set(String name, short value)
name
- Attribute's name.value
- Attribute's value.@Nonnull default Session set(String name, int value)
name
- Attribute's name.value
- Attribute's value.@Nonnull default Session set(String name, long value)
name
- Attribute's name.value
- Attribute's value.@Nonnull default Session set(String name, float value)
name
- Attribute's name.value
- Attribute's value.@Nonnull default Session set(String name, double value)
name
- Attribute's name.value
- Attribute's value.@Nonnull default Session set(String name, CharSequence value)
name
- Attribute's name.value
- Attribute's value.@Nonnull Session set(String name, String value)
name
- Attribute's name.value
- Attribute's value.@Nonnull Mutant unset(String name)
name
- Attribute's name.void destroy()
boolean isDestroyed()
destroy()
.destroy()
.Session renewId()
Copyright © 2020. All rights reserved.