HttpSession | Java Servlet Programming (Java Series)

Java Servlet Programming, 2nd Edition > B. HTTP Servlet API Quick Reference > HttpSession

< BACK

CONTINUE >

HttpSession

Synopsis

Interface Name: javax.servlet.http.HttpSession

Superinterface: None

Immediate Subinterfaces: None

Implemented By: None

Availability: Servlet API 2.0 and later

Description

The HttpSession interface provides a mechanism for holding temporary information about visitors to a web site. For a detailed introduction to session tracking, see Chapter 7. The HttpSession interface itself allows servlets to view and manipulate session-specific information, such as creation time and the unique session identifier. It also includes methods to bind objects to the session for later retrieval, allowing "shopping cart" and other applications to hold onto data between client requests.

A servlet obtains an HttpSession object from the getSession( ) method of HttpServletRequest. Session behavior, such as the amount of idle time before a session is destroyed, can be configured programmatically and via the web application deployment descriptor.

For sessions inside a nondistributed web application, any object may be bound to the session. Objects that implement java.io.Serializable may be written to disk to save memory and to persist between server restarts.

For sessions inside a distributed web application, objects placed into the session must implement java.io.Serializable. The server may throw an IllegalArgumentException when this requirement is not met. Servers use session affinity to efficiently manage sessions in a distributed environment where there are multiple backend servers. This means that all requests that are part of a single session from a particular user are handled by only one JVM at a time. This eliminates the need to constantly replicate session information across all the backend servers. Responsibility for the session can be moved to another server between user requests, and to enable the moving of a session all objects placed into a session must be Serializable.

Interface Declaration

public interface HttpSession {   // Methods   // Most methods may throw IllegalStateException   public abstract Object getAttribute(String name);         // New in 2.2   public abstract Enumeration getAttributeNames();          // New in 2.2   public abstract long getCreationTime();   public abstract String getId();   public abstract long getLastAccessedTime();   public abstract int getMaxInactiveInterval();             // New in 2.1   public abstract HttpSessionContext getSessionContext();   // Deprecated   public abstract Object getValue(String name);             // Deprecated   public abstract String[] getValueNames();                 // Deprecated   public abstract void invalidate();   public abstract boolean isNew();   public abstract void putValue(String name, Object value); // Deprecated   public abstract void removeAttribute(String name);        // New in 2.2   public abstract void removeValue(String name);            // Deprecated   public abstract void setAttribute(String name, Object value);// New in 2.2   public abstract void setMaxInactiveInterval(int secs);    // New in 2.1 }

Methods

getAttribute()

public abstract Object getAttribute(String name)   throws IllegalStateException

Description: Returns the object bound in the session under the specified name or null if there is no matching binding. Throws an IllegalStateException if the session is invalid.

getAttributeNames()

public abstract Enumeration getAttributeNames()   throws IllegalStateException

Description: Returns an Enumeration containing the names of all objects bound to this session as String objects or an empty Enumeration if there are no bindings. Throws an IllegalStateException if the session is invalid.

getCreationTime()

public abstract long getCreationTime()   throws IllegalStateException

Description: Returns the time at which the session was created, as a long representing the number of milliseconds since midnight, January 1, 1970, GMT. Throws an IllegalStateException if the session is invalid.

getId()

public abstract String getId()   throws IllegalStateException

Description: Returns the unique String identifier assigned to this session. The structure of the ID is implementation dependent; it should simply be difficult for anyone else to guess. For example, a Tomcat ID might be something like awj4qyhsn2. Throws an IllegalStateException if the session is invalid.

getLastAccessedTime()

public abstract long getLastAccessedTime()   throws IllegalStateException

Description: Returns the time at which the client last sent a request associated with this session (not including the current request), as a long representing the number of milliseconds since midnight, January 1, 1970, GMT. Throws an IllegalStateException if the session is invalid.

getMaxInactiveInterval()

public abstract int getMaxInactiveInterval()   throws IllegalStateException

Description: Returns the time, in seconds, between client requests before the servlet container will invalidate this session. A negative time indicates the session should never time out. The default timeout is set inside the web application's deployment descriptor. Throws an IllegalStateException if the session is invalid. This method was introduced in Servlet API 2.1.

getSessionContext()

public abstract HttpSessionContext getSessionContext()

Description: Returns an empty context for security reasons, as of Servlet API 2.1. Also deprecated as of Servlet API 2.1. See HttpSessionContext for more information.

getValue()

public abstract Object getValue(String name)   throws IllegalStateException

Description: Returns the object bound in the session under the specified name or null if there is no matching binding. Throws an IllegalStateException if the session is invalid. Deprecated as of Servlet API 2.2 in favor of getAttribute( ).

getValueNames()

public abstract String[] getValueNames()   throws IllegalStateException

Description: Returns an array containing the names of all objects bound to this session or an empty (zero length) array if there are no bindings. Throws an IllegalStateException if the session is invalid. Deprecated as of Servlet API 2.2 in favor of getAttributeNames( ).

invalidate()

public abstract void invalidate()   throws IllegalStateException

Description: Causes the session to be immediately invalidated. All objects stored in the session are unbound. Throws an IllegalStateException if the session is already invalid.

isNew()

public abstract boolean isNew()   throws IllegalStateException

Description: Returns whether the session is new. A session is considered new if it has been created by the server but the client has not yet acknowledged joining the session. For example, if a server supports only cookie-based sessions and a client has completely disabled the use of cookies, calls to getSession( ) always return new sessions. Throws an IllegalStateException if the session is invalid.

putValue()

public abstract void putValue(String name, Object value)   throws IllegalStateException

Description: Binds the specified object value under the specified name in the session. Any existing binding with the same name is replaced. Throws an IllegalStateException if the session is invalid. Deprecated as of Servlet API 2.2 in favor of setAttribute( ).

removeAttribute()

public abstract void removeAttribute(String name)   throws IllegalStateException

Description: Removes the object bound to the specified name or does nothing if there is no binding. Throws an IllegalStateException if the session is invalid.

removeValue()

public abstract void removeValue(String name)   throws IllegalStateException

Description: Removes the object bound to the specified name or does nothing if there is no binding. Throws an IllegalStateException if the session is invalid. Deprecated as of Servlet API 2.2 in favor of removeAttribute( ).

setAttribute()

public abstract void setAttribute(String name, Object value)   throws IllegalStateException

Description: Binds the specified object value under the specified name in the session. Any existing binding with the same name is replaced. Throws an IllegalStateException if the session is invalid. This method was introduced in Servlet API 2.2.

setMaxInactiveInterval()

public abstract void setMaxInactiveInterval(int secs)

Description: Specifies the time, in seconds, between client requests before the servlet container will invalidate this session. A negative time indicates the session should never time out. A default timeout can be set inside a web application's deployment descriptor. This method was introduced in Servlet API 2.1.

< BACK

CONTINUE >