org.apache.catalina

## Interface Session

- All Known Subinterfaces:
    ClusterSession
  All Known Implementing Classes:
    DeltaSession, DummyProxySession, StandardSession

      public interface Session

  A Session is the Catalina-internal facade for an `HttpSession` that is used to maintain state information between requests for a particular user of a web application.
  Author:
    Craig R. McClanahan

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `SESSION_ACTIVATED_EVENT` The SessionEvent event type when a session is activated.
    `static java.lang.String` | `SESSION_CREATED_EVENT` The SessionEvent event type when a session is created.
    `static java.lang.String` | `SESSION_DESTROYED_EVENT` The SessionEvent event type when a session is destroyed.
    `static java.lang.String` | `SESSION_PASSIVATED_EVENT` The SessionEvent event type when a session is passivated.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `access()` Update the accessed time information for this session.
    `void` | `addSessionListener(SessionListener listener)` Add a session event listener to this component.
    `void` | `endAccess()` End access to the session.
    `void` | `expire()` Perform the internal processing required to invalidate this session, without triggering an exception if the session has already expired.
    `java.lang.String` | `getAuthType()` Return the authentication type used to authenticate our cached Principal, if any.
    `long` | `getCreationTime()` Return the creation time for this session.
    `long` | `getCreationTimeInternal()` Return the creation time for this session, bypassing the session validity checks.
    `java.lang.String` | `getId()` Return the session identifier for this session.
    `java.lang.String` | `getIdInternal()` Return the session identifier for this session.
    `java.lang.String` | `getInfo()` Return descriptive information about this Session implementation and the corresponding version number, in the format `<description>/<version>`.
    `long` | `getLastAccessedTime()` Return the last time the client sent a request associated with this session, as the number of milliseconds since midnight, January 1, 1970 GMT.
    `long` | `getLastAccessedTimeInternal()` Return the last client access time without invalidation check
    `Manager` | `getManager()` Return the Manager within which this Session is valid.
    `int` | `getMaxInactiveInterval()` Return the maximum time interval, in seconds, between client requests before the servlet container will invalidate the session.
    `java.lang.Object` | `getNote(java.lang.String name)` Return the object bound with the specified name to the internal notes for this session, or `null` if no such binding exists.
    `java.util.Iterator<java.lang.String>` | `getNoteNames()` Return an Iterator containing the String names of all notes bindings that exist for this session.
    `java.security.Principal` | `getPrincipal()` Return the authenticated Principal that is associated with this Session.
    `HttpSession` | `getSession()` Return the `HttpSession` for which this object is the facade.
    `long` | `getThisAccessedTime()` Return the last time the client sent a request associated with this session, as the number of milliseconds since midnight, January 1, 1970 GMT.
    `long` | `getThisAccessedTimeInternal()` Return the last client access time without invalidation check
    `boolean` | `isValid()` Return the `isValid` flag for this session.
    `void` | `recycle()` Release all object references, and initialize instance variables, in preparation for reuse of this object.
    `void` | `removeNote(java.lang.String name)` Remove any object bound to the specified name in the internal notes for this session.
    `void` | `removeSessionListener(SessionListener listener)` Remove a session event listener from this component.
    `void` | `setAuthType(java.lang.String authType)` Set the authentication type used to authenticate our cached Principal, if any.
    `void` | `setCreationTime(long time)` Set the creation time for this session.
    `void` | `setId(java.lang.String id)` Set the session identifier for this session and notifies any associated listeners that a new session has been created.
    `void` | `setId(java.lang.String id, boolean notify)` Set the session identifier for this session and optionally notifies any associated listeners that a new session has been created.
    `void` | `setManager(Manager manager)` Set the Manager within which this Session is valid.
    `void` | `setMaxInactiveInterval(int interval)` Set the maximum time interval, in seconds, between client requests before the servlet container will invalidate the session.
    `void` | `setNew(boolean isNew)` Set the `isNew` flag for this session.
    `void` | `setNote(java.lang.String name, java.lang.Object value)` Bind an object to a specified name in the internal notes associated with this session, replacing any existing binding for this name.
    `void` | `setPrincipal(java.security.Principal principal)` Set the authenticated Principal that is associated with this Session.
    `void` | `setValid(boolean isValid)` Set the `isValid` flag for this session.

- - ### Field Detail

    - #### SESSION_CREATED_EVENT

          static final java.lang.String SESSION_CREATED_EVENT

      The SessionEvent event type when a session is created.
      See Also:
        Constant Field Values

    - #### SESSION_DESTROYED_EVENT

          static final java.lang.String SESSION_DESTROYED_EVENT

      The SessionEvent event type when a session is destroyed.
      See Also:
        Constant Field Values

    - #### SESSION_ACTIVATED_EVENT

          static final java.lang.String SESSION_ACTIVATED_EVENT

      The SessionEvent event type when a session is activated.
      See Also:
        Constant Field Values

    - #### SESSION_PASSIVATED_EVENT

          static final java.lang.String SESSION_PASSIVATED_EVENT

      The SessionEvent event type when a session is passivated.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getAuthType

          java.lang.String getAuthType()

      Return the authentication type used to authenticate our cached Principal, if any.

    - #### setAuthType

          void setAuthType(java.lang.String authType)

      Set the authentication type used to authenticate our cached Principal, if any.
      Parameters:
        `authType` - The new cached authentication type

    - #### getCreationTime

          long getCreationTime()

      Return the creation time for this session.

    - #### getCreationTimeInternal

          long getCreationTimeInternal()

      Return the creation time for this session, bypassing the session validity checks.

    - #### setCreationTime

          void setCreationTime(long time)

      Set the creation time for this session. This method is called by the Manager when an existing Session instance is reused.
      Parameters:
        `time` - The new creation time

    - #### getId

          java.lang.String getId()

      Return the session identifier for this session.

    - #### getIdInternal

          java.lang.String getIdInternal()

      Return the session identifier for this session.

    - #### setId

          void setId(java.lang.String id)

      Set the session identifier for this session and notifies any associated listeners that a new session has been created.
      Parameters:
        `id` - The new session identifier

    - #### setId

          void setId(java.lang.String id,
                   boolean notify)

      Set the session identifier for this session and optionally notifies any associated listeners that a new session has been created.
      Parameters:
        `id` - The new session identifier
        `notify` - Should any associated listeners be notified that a new session has been created?

    - #### getInfo

          java.lang.String getInfo()

      Return descriptive information about this Session implementation and the corresponding version number, in the format `<description>/<version>`.

    - #### getThisAccessedTime

          long getThisAccessedTime()

      Return the last time the client sent a request associated with this session, as the number of milliseconds since midnight, January 1, 1970 GMT. Actions that your application takes, such as getting or setting a value associated with the session, do not affect the access time. This one gets updated whenever a request starts.

    - #### getThisAccessedTimeInternal

          long getThisAccessedTimeInternal()

      Return the last client access time without invalidation check
      See Also:
        `getThisAccessedTime()`

    - #### getLastAccessedTime

          long getLastAccessedTime()

      Return the last time the client sent a request associated with this session, as the number of milliseconds since midnight, January 1, 1970 GMT. Actions that your application takes, such as getting or setting a value associated with the session, do not affect the access time. This one gets updated whenever a request finishes.

    - #### getLastAccessedTimeInternal

          long getLastAccessedTimeInternal()

      Return the last client access time without invalidation check
      See Also:
        `getLastAccessedTime()`

    - #### getManager

          Manager getManager()

      Return the Manager within which this Session is valid.

    - #### setManager

          void setManager(Manager manager)

      Set the Manager within which this Session is valid.
      Parameters:
        `manager` - The new Manager

    - #### getMaxInactiveInterval

          int getMaxInactiveInterval()

      Return the maximum time interval, in seconds, between client requests before the servlet container will invalidate the session. A negative time indicates that the session should never time out.

    - #### setMaxInactiveInterval

          void setMaxInactiveInterval(int interval)

      Set the maximum time interval, in seconds, between client requests before the servlet container will invalidate the session. A negative time indicates that the session should never time out.
      Parameters:
        `interval` - The new maximum interval

    - #### setNew

          void setNew(boolean isNew)

      Set the `isNew` flag for this session.
      Parameters:
        `isNew` - The new value for the `isNew` flag

    - #### getPrincipal

          java.security.Principal getPrincipal()

      Return the authenticated Principal that is associated with this Session. This provides an `Authenticator` with a means to cache a previously authenticated Principal, and avoid potentially expensive `Realm.authenticate()` calls on every request. If there is no current associated Principal, return `null`.

    - #### setPrincipal

          void setPrincipal(java.security.Principal principal)

      Set the authenticated Principal that is associated with this Session. This provides an `Authenticator` with a means to cache a previously authenticated Principal, and avoid potentially expensive `Realm.authenticate()` calls on every request.
      Parameters:
        `principal` - The new Principal, or `null` if none

    - #### getSession

          HttpSession getSession()

      Return the `HttpSession` for which this object is the facade.

    - #### setValid

          void setValid(boolean isValid)

      Set the `isValid` flag for this session.
      Parameters:
        `isValid` - The new value for the `isValid` flag

    - #### isValid

          boolean isValid()

      Return the `isValid` flag for this session.

    - #### access

          void access()

      Update the accessed time information for this session. This method should be called by the context when a request comes in for a particular session, even if the application does not reference it.

    - #### addSessionListener

          void addSessionListener(SessionListener listener)

      Add a session event listener to this component.

    - #### endAccess

          void endAccess()

      End access to the session.

    - #### expire

          void expire()

      Perform the internal processing required to invalidate this session, without triggering an exception if the session has already expired.

    - #### getNote

          java.lang.Object getNote(java.lang.String name)

      Return the object bound with the specified name to the internal notes for this session, or `null` if no such binding exists.
      Parameters:
        `name` - Name of the note to be returned

    - #### getNoteNames

          java.util.Iterator<java.lang.String> getNoteNames()

      Return an Iterator containing the String names of all notes bindings that exist for this session.

    - #### recycle

          void recycle()

      Release all object references, and initialize instance variables, in preparation for reuse of this object.

    - #### removeNote

          void removeNote(java.lang.String name)

      Remove any object bound to the specified name in the internal notes for this session.
      Parameters:
        `name` - Name of the note to be removed

    - #### removeSessionListener

          void removeSessionListener(SessionListener listener)

      Remove a session event listener from this component.

    - #### setNote

          void setNote(java.lang.String name,
                     java.lang.Object value)

      Bind an object to a specified name in the internal notes associated with this session, replacing any existing binding for this name.
      Parameters:
        `name` - Name to which the object should be bound
        `value` - Object to be bound to the specified name

Copyright © 2000-2015 Apache Software Foundation. All Rights Reserved.