https://tomcat.apache.org/: Tomcat Servlet Engine Core Classes and Standard implementations 
/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */


package org.apache.catalina;


import java.security.Principal;
import java.util.Iterator;

import javax.servlet.http.HttpSession;



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
/**
 * A <b>Session</b> is the Catalina-internal facade for an
 * <code>HttpSession</code> that is used to maintain state information
 * between requests for a particular user of a web application.
 *
 * @author Craig R. McClanahan
 */
public interface Session {


    // ----------------------------------------------------- Manifest Constants


    
The SessionEvent event type when a session is created.

/**
     * The SessionEvent event type when a session is created.
     */
    public static final String SESSION_CREATED_EVENT = "createSession";


    
The SessionEvent event type when a session is destroyed.

/**
     * The SessionEvent event type when a session is destroyed.
     */
    public static final String SESSION_DESTROYED_EVENT = "destroySession";


    
The SessionEvent event type when a session is activated.

/**
     * The SessionEvent event type when a session is activated.
     */
    public static final String SESSION_ACTIVATED_EVENT = "activateSession";


    
The SessionEvent event type when a session is passivated.

/**
     * The SessionEvent event type when a session is passivated.
     */
    public static final String SESSION_PASSIVATED_EVENT = "passivateSession";


    // ------------------------------------------------------------- Properties


    
Returns:the authentication type used to authenticate our cached
Principal, if any.
/**
     * @return the authentication type used to authenticate our cached
     * Principal, if any.
     */
    public String getAuthType();


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

Params:
  • authType – The new cached authentication type
/**
     * Set the authentication type used to authenticate our cached
     * Principal, if any.
     *
     * @param authType The new cached authentication type
     */
    public void setAuthType(String authType);


    
Returns:the creation time for this session.
/**
     * @return the creation time for this session.
     */
    public long getCreationTime();


    
Returns:the creation time for this session, bypassing the session validity
checks.
/**
     * @return the creation time for this session, bypassing the session validity
     * checks.
     */
    public long getCreationTimeInternal();


    
Set the creation time for this session.  This method is called by the
Manager when an existing Session instance is reused.

Params:
  • time – The new creation time
/**
     * Set the creation time for this session.  This method is called by the
     * Manager when an existing Session instance is reused.
     *
     * @param time The new creation time
     */
    public void setCreationTime(long time);


    
Returns:the session identifier for this session.
/**
     * @return the session identifier for this session.
     */
    public String getId();


    
Returns:the session identifier for this session.
/**
     * @return the session identifier for this session.
     */
    public String getIdInternal();


    
Set the session identifier for this session and notifies any associated
listeners that a new session has been created.

Params:
  • id – The new session identifier
/**
     * Set the session identifier for this session and notifies any associated
     * listeners that a new session has been created.
     *
     * @param id The new session identifier
     */
    public void setId(String id);


    
Set the session identifier for this session and optionally notifies any
associated listeners that a new session has been created.

Params:
  • id –        The new session identifier
  • notify –    Should any associated listeners be notified that a new
                     session has been created?
/**
     * Set the session identifier for this session and optionally notifies any
     * associated listeners that a new session has been created.
     *
     * @param id        The new session identifier
     * @param notify    Should any associated listeners be notified that a new
     *                      session has been created?
     */
    public void setId(String id, boolean notify);


    
Returns: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.
/**
     * @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.
     */
    public long getThisAccessedTime();

    
See Also:
Returns:the last client access time without invalidation check
/**
     * @return the last client access time without invalidation check
     * @see #getThisAccessedTime()
     */
    public long getThisAccessedTimeInternal();

    
Returns: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.
/**
     * @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.
     */
    public long getLastAccessedTime();

    
See Also:
Returns:the last client access time without invalidation check
/**
     * @return the last client access time without invalidation check
     * @see #getLastAccessedTime()
     */
    public long getLastAccessedTimeInternal();

    
Returns:the idle time (in milliseconds) from last client access time.
/**
     * @return the idle time (in milliseconds) from last client access time.
     */
    public long getIdleTime();

    
See Also:
Returns:the idle time from last client access time without invalidation check
/**
     * @return the idle time from last client access time without invalidation check
     * @see #getIdleTime()
     */
    public long getIdleTimeInternal();

    
Returns:the Manager within which this Session is valid.
/**
     * @return the Manager within which this Session is valid.
     */
    public Manager getManager();


    
Set the Manager within which this Session is valid.

Params:
  • manager – The new Manager
/**
     * Set the Manager within which this Session is valid.
     *
     * @param manager The new Manager
     */
    public void setManager(Manager manager);


    
Returns: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.
/**
     * @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.
     */
    public int getMaxInactiveInterval();


    
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.

Params:
  • interval – The new maximum 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.
     *
     * @param interval The new maximum interval
     */
    public void setMaxInactiveInterval(int interval);


    
Set the isNew flag for this session.

Params:
  • isNew – The new value for the isNew flag
/**
     * Set the <code>isNew</code> flag for this session.
     *
     * @param isNew The new value for the <code>isNew</code> flag
     */
    public void setNew(boolean isNew);


    
Returns: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.
/**
     * @return the authenticated Principal that is associated with this Session.
     * This provides an <code>Authenticator</code> with a means to cache a
     * previously authenticated Principal, and avoid potentially expensive
     * <code>Realm.authenticate()</code> calls on every request.  If there
     * is no current associated Principal, return <code>null</code>.
     */
    public Principal getPrincipal();


    
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.

Params:
  • principal – The new Principal, or null if none
/**
     * Set the authenticated Principal that is associated with this Session.
     * This provides an <code>Authenticator</code> with a means to cache a
     * previously authenticated Principal, and avoid potentially expensive
     * <code>Realm.authenticate()</code> calls on every request.
     *
     * @param principal The new Principal, or <code>null</code> if none
     */
    public void setPrincipal(Principal principal);


    
Returns:the HttpSession for which this object
is the facade.
/**
     * @return the <code>HttpSession</code> for which this object
     * is the facade.
     */
    public HttpSession getSession();


    
Set the isValid flag for this session.

Params:
  • isValid – The new value for the isValid flag
/**
     * Set the <code>isValid</code> flag for this session.
     *
     * @param isValid The new value for the <code>isValid</code> flag
     */
    public void setValid(boolean isValid);


    
Returns:true if the session is still valid
/**
     * @return <code>true</code> if the session is still valid
     */
    public boolean isValid();


    // --------------------------------------------------------- Public Methods


    
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.

/**
     * 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.
     */
    public void access();


    
Add a session event listener to this component.

Params:
  • listener – the SessionListener instance that should be notified
  for session events
/**
     * Add a session event listener to this component.
     *
     * @param listener the SessionListener instance that should be notified
     *   for session events
     */
    public void addSessionListener(SessionListener listener);


    
End access to the session.

/**
     * End access to the session.
     */
    public void endAccess();


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

/**
     * Perform the internal processing required to invalidate this session,
     * without triggering an exception if the session has already expired.
     */
    public void expire();


    
Params:
  • name – Name of the note to be returned
Returns:the object bound with the specified name to the internal notes
for this session, or null if no such binding exists.
/**
     * @return the object bound with the specified name to the internal notes
     * for this session, or <code>null</code> if no such binding exists.
     *
     * @param name Name of the note to be returned
     */
    public Object getNote(String name);


    
Returns:an Iterator containing the String names of all notes bindings
that exist for this session.
/**
     * @return an Iterator containing the String names of all notes bindings
     * that exist for this session.
     */
    public Iterator<String> getNoteNames();


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

/**
     * Release all object references, and initialize instance variables, in
     * preparation for reuse of this object.
     */
    public void recycle();


    
Remove any object bound to the specified name in the internal notes
for this session.

Params:
  • name – Name of the note to be removed
/**
     * Remove any object bound to the specified name in the internal notes
     * for this session.
     *
     * @param name Name of the note to be removed
     */
    public void removeNote(String name);


    
Remove a session event listener from this component.

Params:
  • listener – remove the session listener, which will no longer be
    notified
/**
     * Remove a session event listener from this component.
     *
     * @param listener remove the session listener, which will no longer be
     *     notified
     */
    public void removeSessionListener(SessionListener listener);


    
Bind an object to a specified name in the internal notes associated
with this session, replacing any existing binding for this name.

Params:
  • name – Name to which the object should be bound
  • value – Object to be bound to the specified name
/**
     * Bind an object to a specified name in the internal notes associated
     * with this session, replacing any existing binding for this name.
     *
     * @param name Name to which the object should be bound
     * @param value Object to be bound to the specified name
     */
    public void setNote(String name, Object value);


    
Inform the listeners about the change session ID.

Params:
  • newId –  new session ID
  • oldId –  old session ID
  • notifySessionListeners –  Should any associated sessionListeners be
       notified that session ID has been changed?
  • notifyContainerListeners –  Should any associated ContainerListeners
       be notified that session ID has been changed?
/**
     * Inform the listeners about the change session ID.
     *
     * @param newId  new session ID
     * @param oldId  old session ID
     * @param notifySessionListeners  Should any associated sessionListeners be
     *        notified that session ID has been changed?
     * @param notifyContainerListeners  Should any associated ContainerListeners
     *        be notified that session ID has been changed?
     */
    public void tellChangedSessionId(String newId, String oldId,
            boolean notifySessionListeners, boolean notifyContainerListeners);


    
Does the session implementation support the distributing of the given attribute? If the Manager is marked as distributable, then this method must be used to check attributes before adding them to a session and an IllegalArgumentException thrown if the proposed attribute is not distributable. 
 Note that the Manager implementation may further restrict which attributes are distributed but a Manager level restriction should not trigger an IllegalArgumentException in HttpSession.setAttribute(String, Object) 
Params:
  • name –  The attribute name
  • value – The attribute value
Returns:true if distribution is supported, otherwise 
        false
/**
     * Does the session implementation support the distributing of the given
     * attribute? If the Manager is marked as distributable, then this method
     * must be used to check attributes before adding them to a session and
     * an {@link IllegalArgumentException} thrown if the proposed attribute is
     * not distributable.
     * <p>
     * Note that the {@link Manager} implementation may further restrict which
     * attributes are distributed but a {@link Manager} level restriction should
     * not trigger an {@link IllegalArgumentException} in
     * {@link HttpSession#setAttribute(String, Object)}
     *
     * @param name  The attribute name
     * @param value The attribute value
     *
     * @return {@code true} if distribution is supported, otherwise {@code
     *         false}
     */
    public boolean isAttributeDistributable(String name, Object value);
}