io.vertx.ext.web.handler

## Interface SessionHandler

- All Superinterfaces:
    Handler<RoutingContext>

      public interface SessionHandler
      extends Handler<RoutingContext>

  A handler that maintains a `Session` for each browser session.

  It looks up the session for each request based on a session cookie which contains a session ID. It stores the session when the response is ended in the session store.

  The session is available on the routing context with `RoutingContext.session()`.

  Author:
    Tim Fox

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static boolean` | `DEFAULT_COOKIE_HTTP_ONLY_FLAG` Default of whether the cookie has the HttpOnly flag set More info: https://www.owasp.org/index.php/HttpOnly
    `static boolean` | `DEFAULT_COOKIE_SECURE_FLAG` Default of whether the cookie has the 'secure' flag set to allow transmission over https only.
    `static boolean` | `DEFAULT_LAZY_SESSION` Default of whether the session should be created lazily.
    `static boolean` | `DEFAULT_NAG_HTTPS` Default of whether a nagging log warning should be written if the session handler is accessed over HTTP, not HTTPS
    `static String` | `DEFAULT_SESSION_COOKIE_NAME` Default name of session cookie
    `static String` | `DEFAULT_SESSION_COOKIE_PATH` Default path of session cookie
    `static long` | `DEFAULT_SESSION_TIMEOUT` Default time, in ms, that a session lasts for without being accessed before expiring.
    `static int` | `DEFAULT_SESSIONID_MIN_LENGTH` Default min length for a session id.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `static SessionHandler` | `create(SessionStore sessionStore)` Create a session handler
    `default Future<Void>` | `flush(RoutingContext ctx)` Promisified flush.
    `default Future<Void>` | `flush(RoutingContext ctx, boolean ignoreStatus)` Promisified flush.
    `SessionHandler` | `flush(RoutingContext ctx, boolean ignoreStatus, Handler<AsyncResult<Void>> handler)` Flush a context session earlier to the store, this will allow the end user to have full control on the event of a failure at the store level.
    `SessionHandler` | `flush(RoutingContext ctx, Handler<AsyncResult<Void>> handler)` Flush a context session earlier to the store, this will allow the end user to have full control on the event of a failure at the store level.
    `Session` | `newSession(RoutingContext context)` Create a new session
    `SessionHandler` | `setCookieHttpOnlyFlag(boolean httpOnly)` Sets whether the 'HttpOnly' flag should be set for the session cookie.
    `SessionHandler` | `setCookieless(boolean cookieless)` Use sessions based on url paths instead of cookies.
    `SessionHandler` | `setCookieMaxAge(long cookieMaxAge)` Set a Cookie max-age to the session cookie.
    `SessionHandler` | `setCookieSameSite(CookieSameSite policy)` Set the session cookie SameSite policy to use.
    `SessionHandler` | `setCookieSecureFlag(boolean secure)` Sets whether the 'secure' flag should be set for the session cookie.
    `SessionHandler` | `setLazySession(boolean lazySession)` Use a lazy session creation mechanism.
    `SessionHandler` | `setMinLength(int minLength)` Set expected session id minimum length.
    `SessionHandler` | `setNagHttps(boolean nag)` Set whether a nagging log warning should be written if the session handler is accessed over HTTP, not HTTPS
    `SessionHandler` | `setSessionCookieName(String sessionCookieName)` Set the session cookie name
    `SessionHandler` | `setSessionCookiePath(String sessionCookiePath)` Set the session cookie path
    `SessionHandler` | `setSessionTimeout(long timeout)` Set the session timeout
    `Future<Void>` | `setUser(RoutingContext context, User user)` Set the user for the session
    `default SessionHandler` | `setUser(RoutingContext context, User user, Handler<AsyncResult<Void>> handler)` Set the user for the session

    - ### Methods inherited from interface io.vertx.core.Handler

      `handle`

- - ### Field Detail

    - #### DEFAULT_SESSION_COOKIE_NAME

          static final String DEFAULT_SESSION_COOKIE_NAME

      Default name of session cookie
      See Also:
        Constant Field Values

    - #### DEFAULT_SESSION_COOKIE_PATH

          static final String DEFAULT_SESSION_COOKIE_PATH

      Default path of session cookie
      See Also:
        Constant Field Values

    - #### DEFAULT_SESSION_TIMEOUT

          static final long DEFAULT_SESSION_TIMEOUT

      Default time, in ms, that a session lasts for without being accessed before expiring.
      See Also:
        Constant Field Values

    - #### DEFAULT_NAG_HTTPS

          static final boolean DEFAULT_NAG_HTTPS

      Default of whether a nagging log warning should be written if the session handler is accessed over HTTP, not HTTPS
      See Also:
        Constant Field Values

    - #### DEFAULT_COOKIE_HTTP_ONLY_FLAG

          static final boolean DEFAULT_COOKIE_HTTP_ONLY_FLAG

      Default of whether the cookie has the HttpOnly flag set More info: https://www.owasp.org/index.php/HttpOnly
      See Also:
        Constant Field Values

    - #### DEFAULT_COOKIE_SECURE_FLAG

          static final boolean DEFAULT_COOKIE_SECURE_FLAG

      Default of whether the cookie has the 'secure' flag set to allow transmission over https only. More info: https://www.owasp.org/index.php/SecureFlag
      See Also:
        Constant Field Values

    - #### DEFAULT_SESSIONID_MIN_LENGTH

          static final int DEFAULT_SESSIONID_MIN_LENGTH

      Default min length for a session id. More info: https://www.owasp.org/index.php/Session_Management_Cheat_Sheet
      See Also:
        Constant Field Values

    - #### DEFAULT_LAZY_SESSION

          static final boolean DEFAULT_LAZY_SESSION

      Default of whether the session should be created lazily.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### create

          static SessionHandler create(SessionStore sessionStore)

      Create a session handler
      Parameters:
        `sessionStore` - the session store
      Returns:
        the handler

    - #### setSessionTimeout

          SessionHandler setSessionTimeout(long timeout)

      Set the session timeout
      Parameters:
        `timeout` - the timeout, in ms.
      Returns:
        a reference to this, so the API can be used fluently

    - #### setNagHttps

          SessionHandler setNagHttps(boolean nag)

      Set whether a nagging log warning should be written if the session handler is accessed over HTTP, not HTTPS
      Parameters:
        `nag` - true to nag
      Returns:
        a reference to this, so the API can be used fluently

    - #### setCookieSecureFlag

          SessionHandler setCookieSecureFlag(boolean secure)

      Sets whether the 'secure' flag should be set for the session cookie. When set this flag instructs browsers to only send the cookie over HTTPS. Note that this will probably stop your sessions working if used without HTTPS (e.g. in development).
      Parameters:
        `secure` - true to set the secure flag on the cookie
      Returns:
        a reference to this, so the API can be used fluently

    - #### setCookieHttpOnlyFlag

          SessionHandler setCookieHttpOnlyFlag(boolean httpOnly)

      Sets whether the 'HttpOnly' flag should be set for the session cookie. When set this flag instructs browsers to prevent Javascript access to the the cookie. Used as a line of defence against the most common XSS attacks.
      Parameters:
        `httpOnly` - true to set the HttpOnly flag on the cookie
      Returns:
        a reference to this, so the API can be used fluently

    - #### setSessionCookieName

          SessionHandler setSessionCookieName(String sessionCookieName)

      Set the session cookie name
      Parameters:
        `sessionCookieName` - the session cookie name
      Returns:
        a reference to this, so the API can be used fluently

    - #### setSessionCookiePath

          SessionHandler setSessionCookiePath(String sessionCookiePath)

      Set the session cookie path
      Parameters:
        `sessionCookiePath` - the session cookie path
      Returns:
        a reference to this, so the API can be used fluently

    - #### setMinLength

          SessionHandler setMinLength(int minLength)

      Set expected session id minimum length.
      Parameters:
        `minLength` - the session id minimal length
      Returns:
        a reference to this, so the API can be used fluently

    - #### setCookieSameSite

          SessionHandler setCookieSameSite(CookieSameSite policy)

      Set the session cookie SameSite policy to use.
      Parameters:
        `policy` - to use, `null` for no policy.
      Returns:
        a reference to this, so the API can be used fluently

    - #### setLazySession

          SessionHandler setLazySession(boolean lazySession)

      Use a lazy session creation mechanism. The session will only be created when accessed from the context. Thus the session cookie is set only if the session was accessed.
      Parameters:
        `lazySession` - true to have a lazy session creation.
      Returns:
        a reference to this, so the API can be used fluently

    - #### setCookieMaxAge

          SessionHandler setCookieMaxAge(long cookieMaxAge)

      Set a Cookie max-age to the session cookie. When doing this the Cookie will be persistent across browser restarts. This can be dangerous as closing a browser windows does not invalidate the session. For more information refer to https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html#Expire_and_Max-Age_Attributes
      Parameters:
        `cookieMaxAge` - a non negative max-age, note that 0 means expire now.
      Returns:
        a reference to this, so the API can be used fluently

    - #### flush

          SessionHandler flush(RoutingContext ctx,
                               Handler<AsyncResult<Void>> handler)

      Flush a context session earlier to the store, this will allow the end user to have full control on the event of a failure at the store level. Once a session is flushed no automatic save will be performed at end of request.
      Parameters:
        `ctx` - the current context
        `handler` - the event handler to signal a asynchronous response.
      Returns:
        fluent self

    - #### flush

          SessionHandler flush(RoutingContext ctx,
                               boolean ignoreStatus,
                               Handler<AsyncResult<Void>> handler)

      Flush a context session earlier to the store, this will allow the end user to have full control on the event of a failure at the store level. Once a session is flushed no automatic save will be performed at end of request.
      Parameters:
        `ctx` - the current context
        `ignoreStatus` - flush regardless of response status code
        `handler` - the event handler to signal a asynchronous response.
      Returns:
        fluent self

    - #### flush

          default Future<Void> flush(RoutingContext ctx)

      Promisified flush. See `flush(RoutingContext, Handler)`.

    - #### flush

          default Future<Void> flush(RoutingContext ctx,
                                     boolean ignoreStatus)

      Promisified flush. See `flush(RoutingContext, boolean, Handler)`.

    - #### setCookieless

          SessionHandler setCookieless(boolean cookieless)

      Use sessions based on url paths instead of cookies. This is an potential less safe alternative to cookies but offers an alternative when Cookies are not desired, for example, to avoid showing banners on a website due to cookie laws, or doing machine to machine operations where state is required to maintain.
      Parameters:
        `cookieless` - true if a cookieless session should be used
      Returns:
        a reference to this, so the API can be used fluently

    - #### newSession

          Session newSession(RoutingContext context)

      Create a new session
      Parameters:
        `context` - the routing context
      Returns:
        the session

    - #### setUser

          Future<Void> setUser(RoutingContext context,
                               User user)

      Set the user for the session
      Parameters:
        `context` - the routing context
        `user` - the user
      Returns:
        future that will be called when complete, or a failure

    - #### setUser

          default SessionHandler setUser(RoutingContext context,
                                         User user,
                                         Handler<AsyncResult<Void>> handler)

      Set the user for the session
      Parameters:
        `context` - the routing context
        `user` - the user
        `handler` - the event handler to signal a asynchronous response.
      Returns:
        a reference to this, so the API can be used fluently

Copyright © 2021 Eclipse. All rights reserved.