org.springframework.web.server

## Interface WebSession

- All Known Implementing Classes:
    MockWebSession

      public interface WebSession

  Main contract for using a server-side session that provides access to session attributes across HTTP requests.

  The creation of a `WebSession` instance does not automatically start a session thus causing the session id to be sent to the client (typically via a cookie). A session starts implicitly when session attributes are added. A session may also be created explicitly via `start()`.

  Since:
    5.0
  Author:
    Rossen Stoyanchev

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `reactor.core.publisher.Mono<Void>` | `changeSessionId()` Generate a new id for the session and update the underlying session storage to reflect the new id.
    `default <T> T` | `getAttribute(String name)` Return the session attribute value if present.
    `default <T> T` | `getAttributeOrDefault(String name, T defaultValue)` Return the session attribute value, or a default, fallback value.
    `Map<String,Object>` | `getAttributes()` Return a map that holds session attributes.
    `Instant` | `getCreationTime()` Return the time when the session was created.
    `String` | `getId()` Return a unique session identifier.
    `Instant` | `getLastAccessTime()` Return the last time of session access as a result of user activity such as an HTTP request.
    `Duration` | `getMaxIdleTime()` Return the maximum time after the `lastAccessTime` before a session expires.
    `default <T> T` | `getRequiredAttribute(String name)` Return the session attribute value or if not present raise an `IllegalArgumentException`.
    `reactor.core.publisher.Mono<Void>` | `invalidate()` Invalidate the current session and clear session storage.
    `boolean` | `isExpired()` Return `true` if the session expired after `maxIdleTime` elapsed.
    `boolean` | `isStarted()` Whether a session with the client has been started explicitly via `start()` or implicitly by adding session attributes.
    `reactor.core.publisher.Mono<Void>` | `save()` Save the session through the `WebSessionStore` as follows: If the session is new (i.e.
    `void` | `setMaxIdleTime(Duration maxIdleTime)` Configure the max amount of time that may elapse after the `lastAccessTime` before a session is considered expired.
    `void` | `start()` Force the creation of a session causing the session id to be sent when `save()` is called.

- - ### Method Detail

    - #### getId

          String getId()

      Return a unique session identifier.

    - #### getAttributes

          Map<String,Object> getAttributes()

      Return a map that holds session attributes.

    - #### getAttribute

          @Nullable
          default <T> T getAttribute(String name)

      Return the session attribute value if present.
      Type Parameters:
        `T` - the attribute type
      Parameters:
        `name` - the attribute name
      Returns:
        the attribute value

    - #### getRequiredAttribute

          default <T> T getRequiredAttribute(String name)

      Return the session attribute value or if not present raise an `IllegalArgumentException`.
      Type Parameters:
        `T` - the attribute type
      Parameters:
        `name` - the attribute name
      Returns:
        the attribute value

    - #### getAttributeOrDefault

          default <T> T getAttributeOrDefault(String name,
                                              T defaultValue)

      Return the session attribute value, or a default, fallback value.
      Type Parameters:
        `T` - the attribute type
      Parameters:
        `name` - the attribute name
        `defaultValue` - a default value to return instead
      Returns:
        the attribute value

    - #### start

          void start()

      Force the creation of a session causing the session id to be sent when `save()` is called.

    - #### isStarted

          boolean isStarted()

      Whether a session with the client has been started explicitly via `start()` or implicitly by adding session attributes. If "false" then the session id is not sent to the client and the `save()` method is essentially a no-op.

    - #### changeSessionId

          reactor.core.publisher.Mono<Void> changeSessionId()

      Generate a new id for the session and update the underlying session storage to reflect the new id. After a successful call `getId()` reflects the new session id.
      Returns:
        completion notification (success or error)

    - #### invalidate

          reactor.core.publisher.Mono<Void> invalidate()

      Invalidate the current session and clear session storage.
      Returns:
        completion notification (success or error)

    - #### save

          reactor.core.publisher.Mono<Void> save()

      Save the session through the `WebSessionStore` as follows:
      - If the session is new (i.e. created but never persisted), it must have been started explicitly via `start()` or implicitly by adding attributes, or otherwise this method should have no effect.
      - If the session was retrieved through the `WebSessionStore`, the implementation for this method must check whether the session was `invalidated` and if so return an error.

      Note that this method is not intended for direct use by applications. Instead it is automatically invoked just before the response is committed.

      Returns:
        `Mono` to indicate completion with success or error

    - #### isExpired

          boolean isExpired()

      Return `true` if the session expired after `maxIdleTime` elapsed.

      Typically expiration checks should be automatically made when a session is accessed, a new `WebSession` instance created if necessary, at the start of request processing so that applications don't have to worry about expired session by default.

    - #### getCreationTime

          Instant getCreationTime()

      Return the time when the session was created.

    - #### getLastAccessTime

          Instant getLastAccessTime()

      Return the last time of session access as a result of user activity such as an HTTP request. Together with `maxIdleTimeInSeconds` this helps to determine when a session is `expired`.

    - #### setMaxIdleTime

          void setMaxIdleTime(Duration maxIdleTime)

      Configure the max amount of time that may elapse after the `lastAccessTime` before a session is considered expired. A negative value indicates the session should not expire.

    - #### getMaxIdleTime

          Duration getMaxIdleTime()

      Return the maximum time after the `lastAccessTime` before a session expires. A negative time indicates the session doesn't expire.