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
`static String` `SESSION_ACTIVATED_EVENT` The SessionEvent event type when a session is activated.
`static String` `SESSION_CREATED_EVENT` The SessionEvent event type when a session is created.
`static String` `SESSION_DESTROYED_EVENT` The SessionEvent event type when a session is destroyed.
`static String` `SESSION_PASSIVATED_EVENT` The SessionEvent event type when a session is passivated.

### Method Summary

Methods
`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.
`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.
`String` `getId()` Return the session identifier for this session.
`String` `getIdInternal()` Return the session identifier for this session.
`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.
`Object` `getNote(String name)` Return the object bound with the specified name to the internal notes for this session, or `null` if no such binding exists.
`Iterator<String>` `getNoteNames()` Return an Iterator containing the String names of all notes bindings that exist for this session.
`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(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(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(String id)` Set the session identifier for this session and notifies any associated listeners that a new session has been created.
`void` `setId(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(String name, 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(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 String SESSION_CREATED_EVENT

The SessionEvent event type when a session is created.

See Also:
  Constant Field Values

#### SESSION_DESTROYED_EVENT

    static final String SESSION_DESTROYED_EVENT

The SessionEvent event type when a session is destroyed.

See Also:
  Constant Field Values

#### SESSION_ACTIVATED_EVENT

    static final String SESSION_ACTIVATED_EVENT

The SessionEvent event type when a session is activated.

See Also:
  Constant Field Values

#### SESSION_PASSIVATED_EVENT

    static final String SESSION_PASSIVATED_EVENT

The SessionEvent event type when a session is passivated.

See Also:
  Constant Field Values

### Method Detail

#### getAuthType

    String getAuthType()

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

#### setAuthType

    void setAuthType(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

    String getId()

Return the session identifier for this session.

#### getIdInternal

    String getIdInternal()

Return the session identifier for this session.

#### setId

    void setId(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(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

    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

    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(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

    Object getNote(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

    Iterator<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(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(String name,
               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