Interface javax.servlet.http.HttpSession
All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface javax.servlet.http.HttpSession

public interface HttpSession
The HttpSession interface is implemented by services to provide an association between an HTTP client and HTTP server. This association, or session, persists over multiple connections and/or requests during a given time period. Sessions are used to maintain state and user identity across multiple page requests.

A session can be maintained either by using cookies or by URL rewriting. To expose whether the client supports cookies, HttpSession defines an isCookieSupportDetermined method and an isUsingCookies method.

HttpSession defines methods which store these types of data:

The following code snippet illustrates getting and setting the the session data value.

       
 //Get the session object - "request" represents the HTTP servlet request
 HttpSession session = request.getSession(true);
 
//Get the session data value - an Integer object is read from //the session, incremented, then written back to the session. //sessiontest.counter identifies values in the session Integer ival = (Integer) session.getValue("sessiontest.counter"); if (ival==null) ival = new Integer(1); else ival = new Integer(ival.intValue() + 1); session.putValue("sessiontest.counter", ival);

When an application layer stores or removes data from the session, the session layer checks whether the object implements HttpSessionBindingListener. If it does, then the object is notified that it has been bound or unbound from the session.

An implementation of HttpSession represents the server's view of the session. The server considers a session to be new until it has been joined by the client. Until the client joins the session, the isNew method returns true. A value of true can indicate one of these three cases:

It is the responsibility of developers to design their applications to account for situations where a client has not joined a session. For example, in the following code snippet isNew is called to determine whether a session is new. If it is, the server will require the client to start a session by directing the client to a welcome page welcomeURL where a user might be required to enter some information and send it to the server before gaining access to subsequent pages.

 //Get the session object - "request" represents the HTTP servlet request
 HttpSession session = request.getSession(true);
 
//insist that the client starts a session //before access to data is allowed //"response" represents the HTTP servlet response if (session.isNew()) { response.sendRedirect (welcomeURL); }

Version:
1.15, 10/28/97
See Also:
HttpSessionBindingListener, HttpSessionContext

Method Index

 o getCreationTime()
Returns the time at which this session representation was created, in milliseconds since midnight, January 1, 1970 UTC.
 o getId()
Returns the identifier assigned to this session.
 o getLastAccessedTime()
Returns the last time the client sent a request carrying the identifier assigned to the session.
 o getSessionContext()
Returns the context in which this session is bound.
 o getValue(String)
Returns the object bound to the given name in the session's application layer data.
 o getValueNames()
Returns an array of the names of all the application layer data objects bound into the session.
 o invalidate()
Causes this representation of the session to be invalidated and removed from its context.
 o isNew()
A session is considered to be "new" if it has been created by the server, but the client has not yet acknowledged joining the session.
 o putValue(String, Object)
Binds the specified object into the session's application layer data with the given name.
 o removeValue(String)
Removes the object bound to the given name in the session's application layer data.

Methods

 o getCreationTime
public abstract long getCreationTime()
Returns the time at which this session representation was created, in milliseconds since midnight, January 1, 1970 UTC.

Returns:
the time when the session was created
Throws: IllegalStateException
if an attempt is made to access session data after the session has been invalidated
 o getId
public abstract java.lang.String getId()
Returns the identifier assigned to this session. An HttpSession's identifier is a unique string that is created and maintained by HttpSessionContext.

Returns:
the identifier assigned to this session
Throws: IllegalStateException
if an attempt is made to access session data after the session has been invalidated
 o getLastAccessedTime
public abstract long getLastAccessedTime()
Returns the last time the client sent a request carrying the identifier assigned to the session. Time is expressed as milliseconds since midnight, January 1, 1970 UTC. Application level operations, such as getting or setting a value associated with the session, does not affect the access time.

This information is particularly useful in session management policies. For example,

Returns:
the last time the client sent a request carrying the identifier assigned to the session
Throws: IllegalStateException
if an attempt is made to access session data after the session has been invalidated
 o getSessionContext
public abstract javax.servlet.http.HttpSessionContext getSessionContext()
Returns the context in which this session is bound.

Returns:
the name of the context in which this session is bound
Throws: IllegalStateException
if an attempt is made to access session data after the session has been invalidated
 o getValue
public abstract java.lang.Object getValue(String name)
Returns the object bound to the given name in the session's application layer data. Returns null if there is no such binding.

Parameters:
name - the name of the binding to find
Returns:
the value bound to that name, or null if the binding does not exist.
Throws: IllegalStateException
if an attempt is made to access HttpSession's session data after it has been invalidated
 o getValueNames
public abstract java.lang.String[] getValueNames()
Returns an array of the names of all the application layer data objects bound into the session. For example, if you want to delete all of the data objects bound into the session, use this method to obtain their names.

Returns:
an array containing the names of all of the application layer data objects bound into the session
Throws: IllegalStateException
if an attempt is made to access session data after the session has been invalidated
 o invalidate
public abstract void invalidate()
Causes this representation of the session to be invalidated and removed from its context.

Throws: IllegalStateException
if an attempt is made to access session data after the session has been invalidated
 o isNew
public abstract boolean isNew()
A session is considered to be "new" if it has been created by the server, but the client has not yet acknowledged joining the session. For example, if the server supported only cookie-based sessions and the client had completely disabled the use of cookies, then calls to HttpServletRequest.getSession() would always return "new" sessions.

Returns:
true if the session has been created by the server but the client has not yet acknowledged joining the session; false otherwise
Throws: IllegalStateException
if an attempt is made to access session data after the session has been invalidated
 o putValue
public abstract void putValue(String name,
                              Object value)
Binds the specified object into the session's application layer data with the given name. Any existing binding with the same name is replaced. New (or existing) values that implement the HttpSessionBindingListener interface will call its valueBound() method.

Parameters:
name - the name to which the data object will be bound. This parameter cannot be null.
value - the data object to be bound. This parameter cannot be null.
Throws: IllegalStateException
if an attempt is made to access session data after the session has been invalidated
 o removeValue
public abstract void removeValue(String name)
Removes the object bound to the given name in the session's application layer data. Does nothing if there is no object bound to the given name. The value that implements the HttpSessionBindingListener interface will call its valueUnbound() method.

Parameters:
name - the name of the object to remove
Throws: IllegalStateException
if an attempt is made to access session data after the session has been invalidated

All Packages  Class Hierarchy  This Package  Previous  Next  Index