Class Session


public class Session extends StorableObject
An active client session.
Version:
1.0
  • Field Details

    • PATH

      public static final Path PATH
      The session object storage path.
    • KEY_USER

      public static final String KEY_USER
      The dictionary key for the user id.
      See Also:
    • KEY_CREATE_TIME

      public static final String KEY_CREATE_TIME
      The dictionary key for the creation timestamp.
      See Also:
    • KEY_DESTROY_TIME

      public static final String KEY_DESTROY_TIME
      The dictionary key for the destruction timestamp.
      See Also:
    • KEY_ACCESS_TIME

      public static final String KEY_ACCESS_TIME
      The dictionary key for the last access timestamp.
      See Also:
    • KEY_IP

      public static final String KEY_IP
      The dictionary key for the source IP address.
      See Also:
    • KEY_CLIENT

      public static final String KEY_CLIENT
      The dictionary key for the user agent string of the web browser.
      See Also:
    • KEY_FILES

      public static final String KEY_FILES
      The dictionary key for the temporary session files. All these files will be deleted when the session instance is destroyed (removed from in-memory storage).
      See Also:
    • EXPIRY_ANON_MILLIS

      public static final long EXPIRY_ANON_MILLIS
      The expiry timeout (after last access) for anonymous users (30 minutes).
      See Also:
    • EXPIRY_AUTH_MILLIS

      public static final long EXPIRY_AUTH_MILLIS
      The expiry timeout (after last access) for logged in users (30 days).
      See Also:
    • MAX_AGE_MILLIS

      public static final long MAX_AGE_MILLIS
      The maximum session age (90 days).
      See Also:
    • ACTIVE_MILLIS

      public static final long ACTIVE_MILLIS
      The default active session time (5 minutes).
      See Also:
    • activeSession

      public static ThreadLocal<Session> activeSession
      The currently active session (for the current thread).
  • Constructor Details

    • Session

      public Session(String id, String type, Dict dict)
      Creates a new session from a serialized representation.
      Parameters:
      id - the object identifier
      type - the object type name
      dict - the serialized representation
    • Session

      public Session(String userId, String ip, String client)
      Creates a new session for the specified user.
      Parameters:
      userId - the user id
      ip - the source IP address
      client - the browser user agent string
  • Method Details

    • all

      public static Stream<Session> all(Storage storage)
      Returns a stream of all sessions found in the storage.
      Parameters:
      storage - the storage to search
      Returns:
      a stream of session instances found
    • find

      public static Session find(Storage storage, String id)
      Searches for a specific session in the storage.
      Parameters:
      storage - the storage to search in
      id - the session identifier
      Returns:
      the session found, or null if not found
    • store

      public static void store(Storage storage, Session session) throws StorageException
      Stores the specified session in the provided storage.
      Parameters:
      storage - the storage to use
      session - the session to store
      Throws:
      StorageException - if the session couldn't be stored
    • remove

      public static void remove(Storage storage, String id)
      Removes the specified session id from the provided storage.
      Parameters:
      storage - the storage to use
      id - the session id to remove
    • removeExpired

      public static void removeExpired(Storage storage)
      Removes all expired sessions from the provided storage. This method will load and examine sessions that have not been modified in 30 minutes.
      Parameters:
      storage - the storage to use
    • isActive

      protected boolean isActive()
      Checks if this object is in active use. This method returns true during some minutes after the last access, thereafter false.
      Overrides:
      isActive in class StorableObject
      Returns:
      true if the object is active, or false otherwise
      See Also:
    • isModified

      protected boolean isModified()
      Checks if this object has been modified since initialized from storage.
      Overrides:
      isModified in class StorableObject
      Returns:
      true if the object has been modified, or false otherwise
    • destroy

      protected void destroy()
      Destroys this session. This method is used to free resources used when the session is no longer in active use. It is called when the session instance is removed from in-memory storage (the object cache).
      Overrides:
      destroy in class StorableObject
    • passivate

      protected void passivate()
      Discards the modified flag for this object.
      Overrides:
      passivate in class StorableObject
    • isNew

      public boolean isNew()
      Checks if this session is new (hasn't been stored).
      Returns:
      true if the session is new, or false otherwise
    • isAuthenticated

      public boolean isAuthenticated()
      Checks if this session is authenticated (by a user).
      Returns:
      true if the session is authenticated, or false otherwise
    • isExpired

      public boolean isExpired()
      Checks if this session has expired.
      Returns:
      true if the session has expired, or false otherwise
    • userId

      public String userId()
      Returns the session user identifier.
      Returns:
      the session user identifier.
    • setUserId

      public void setUserId(String userId)
      Sets the session user identifier if it was previously blank. Once a session has been bound to a user, it cannot be bound to another user (or reset to a blank user).
      Parameters:
      userId - the new session user identifier
      Throws:
      SecurityException - if the session couldn't be bound to the specified user identifier
    • createTime

      public Date createTime()
      Returns the session creation timestamp.
      Returns:
      the session creation timestamp.
    • destroyTime

      public Date destroyTime()
      Returns the scheduled session destruction timestamp.
      Returns:
      the session destruction timestamp.
    • setDestroyTime

      public void setDestroyTime(Date date)
      Sets the scheduled session destruction timestamp.
      Parameters:
      date - the destruction timestamp, or null for default
    • accessTime

      public Date accessTime()
      Returns the session last access timestamp.
      Returns:
      the session last access timestamp.
    • updateAccessTime

      public void updateAccessTime()
      Updates the session last access timestamp to the current system time.
    • ip

      public String ip()
      Returns the session source IP address. May be in either IPv4 or IPv6 format.
      Returns:
      the session source IP address.
    • setIp

      public void setIp(String ip)
      Sets the session source IP address. May be in either IPv4 or IPv6 format.
      Parameters:
      ip - the new session source IP address.
    • client

      public String client()
      Returns the session user agent string of the web browser.
      Returns:
      the session user agent string.
    • setClient

      public void setClient(String client)
      Sets the session user agent string of the web browser.
      Parameters:
      client - the session user agent string.
    • files

      public Dict files()
      Returns a dictionary of all session files. The files are indexed by their unique id.
      Returns:
      a dictionary of all files
    • file

      public File file(String id)
      Returns a session file with the specified unique id.
      Parameters:
      id - the file id
      Returns:
      the session file, or null if no such file was found
    • addFile

      public void addFile(String id, File file)
      Adds a file to the session. The file will be automatically deleted when the session expires or is removed from in-memory cache.
      Parameters:
      id - the file id
      file - the file to add
    • removeFile

      public void removeFile(String id)
      Removes and deletes a session file. If the file has been moved from its original location, it wont be deleted.
      Parameters:
      id - the file id
    • removeAllFiles

      public void removeAllFiles()
      Removes and deletes all session files. If the files have been moved from their original location, they wont be deleted.
    • authenticate

      public User authenticate() throws SecurityException
      Validates this session and authenticates the user. If the session has expired or is no longer valid, a security exception is thrown. Note that this method may succeed also if no user is linked to the session.
      Returns:
      the authenticated user, i.e. SecurityContext.currentUser()
      Throws:
      SecurityException - if the session wasn't valid
    • invalidate

      public void invalidate()
      Invalidates this session by marking it as expired. This operation is irreversible and will eventually cause the removal of the session in the storage.
    • serialize

      public Dict serialize()
      Returns a serialized representation of this object. Used when persisting to permanent storage or when accessing the object from outside pure Java. Returns a shallow copy of the contained dictionary.
      Overrides:
      serialize in class StorableObject
      Returns:
      the serialized representation of this object