javax.servlet.http
Interface HttpSession

public abstract 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.

HttpSession defines methods which store these types of data:

• Standard session properties, such as an identifier for the session, and the context for the session.
• Application layer data, accessed using this interface and stored using a dictionary-like interface.

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:

• the client does not yet know about the session
• the session has not yet begun
• the client chooses not to join the session. This case will occur if the client supports only cookies and chooses to reject any cookies sent by the server. If the server supports URL rewriting, this case will not commonly occur.

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);
 }

 

See Also:

HttpSessionBindingListener, HttpSessionContext

Method Summary

long	getCreationTime() Returns the time at which this session representation was created, in milliseconds since midnight, January 1, 1970 UTC.
java.lang.String	getId() Returns the identifier assigned to this session.
long	getLastAccessedTime() Returns the last time the client sent a request carrying the identifier assigned to the session.
int	getMaxInactiveInterval()
HttpSessionContext	getSessionContext() Deprecated.
java.lang.Object	getValue(java.lang.String name) Returns the object bound to the given name in the session's application layer data.
java.lang.String[]	getValueNames() Returns an array of the names of all the application layer data objects bound into the session.
void	invalidate() Causes this representation of the session to be invalidated and removed from its context.
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.
void	putValue(java.lang.String name, java.lang.Object value) Binds the specified object into the session's application layer data with the given name.
void	removeValue(java.lang.String name) Removes the object bound to the given name in the session's application layer data.
void	setMaxInactiveInterval(int interval) Sets the maximum interval between requests that this session will be kept by the host server.

Method Detail

getCreationTime

public 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

getId

public 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

getLastAccessedTime

public 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,

• a session manager could leave all sessions which have not been used in a long time in a given context.
• the sessions can be sorted according to age to optimize some task.

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

getMaxInactiveInterval

public int getMaxInactiveInterval()

getSessionContext

public HttpSessionContext getSessionContext()

Deprecated.

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

getValue

public java.lang.Object getValue(java.lang.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

getValueNames

public 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

invalidate

public 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

isNew

public 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

putValue

public void putValue(java.lang.String name,
                     java.lang.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

removeValue

public void removeValue(java.lang.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

setMaxInactiveInterval

public void setMaxInactiveInterval(int interval)

Sets the maximum interval between requests that this session will be kept by the host server.