All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface javax.servlet.http.HttpSession

public interface HttpSession

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:

• 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

getCreationTime()

Returns the time at which this session representation was created, in milliseconds since midnight, January 1, 1970 UTC.

getId()

Returns the identifier assigned to this session.

getLastAccessedTime()

Returns the last time the client sent a request carrying the identifier assigned to the session.

getSessionContext()

Returns the context in which this session is bound.

getValue(String)

Returns the object bound to the given name in the session's application layer data.

getValueNames()

Returns an array of the names of all the application layer data objects bound into the session.

invalidate()

Causes this representation of the session to be invalidated and removed from its context.

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.

putValue(String, Object)

Binds the specified object into the session's application layer data with the given name.

removeValue(String)

Removes the object bound to the given name in the session's application layer data.

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

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

 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

 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,

• 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

 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

 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

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

 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

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

 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

All Packages  Class Hierarchy  This Package  Previous  Next  Index