php.java.bridge
Interface ISession

public interface ISession

The ISession 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.
Example:
$session=java_session();
$val=$session->get("i");
if(!$val) val = 0; echo $val++;
$session->put("i", new java("java.lang.Integer", $val));

An implementation of ISession represents the server's view of the session. When java_session() is called without a session name, 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.

$session=java_session();
if($session->isNew()) {
header("Location: http://".$_SERVER['HTTP_HOST'] .dirname($_SERVER['PHP_SELF']) ."/welcomeURL.html");
}

Field Summary

static short	SESSION_CREATE_NEW Create a new session
static short	SESSION_GET Get an existing session
static short	SESSION_GET_OR_CREATE Get an existing session or create one

Method Summary

void	destroy() Causes this representation of the session to be invalidated an removed from its context.
java.lang.Object	get(java.lang.Object name) Returns the object bound to the given name in the session's context layer data.
java.util.Map	getAll() Returns a map of all bindings maintained by this session.
long	getCreationTime() Returns the time when this session was created, measured in milliseconds since midnight January 1, 1970 GMT.
long	getLastAccessedTime() Returns the last time the client sent a request associated with this session, as the number of milliseconds since midnight January 1, 1970 GMT.
int	getSessionCount() Returns the number of active sessions.
int	getTimeout() Returns the maximum time interval, in seconds, that the servlet container will keep this session open between client accesses.
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	put(java.lang.Object name, java.lang.Object value) Binds the specified object into the session's context layer data with the given name.
void	putAll(java.util.Map vars) Copies all bindings to the session's context layer data.
java.lang.Object	remove(java.lang.Object name) Removes the object bound to the given name in the session's context layer data.
void	setTimeout(int interval) Specifies the time, in seconds, between client requests before the servlet container will invalidate this session.

Field Detail

SESSION_GET_OR_CREATE

static final short SESSION_GET_OR_CREATE

Get an existing session or create one

See Also:

Constant Field Values

SESSION_CREATE_NEW

static final short SESSION_CREATE_NEW

Create a new session

See Also:

Constant Field Values

SESSION_GET

static final short SESSION_GET

Get an existing session

See Also:

Constant Field Values

Method Detail

get

java.lang.Object get(java.lang.Object name)

Returns the object bound to the given name in the session's context 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:

java.lang.IllegalStateException - if an attempt is made to access session data after it has been invalidated

put

void put(java.lang.Object name,
         java.lang.Object value)

Binds the specified object into the session's context layer data with the given name. Any existing binding with the same name is replaced.

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:

java.lang.IllegalStateException - if an attempt is made to access session data after the session has been invalidated.

remove

java.lang.Object remove(java.lang.Object name)

Removes the object bound to the given name in the session's context layer data. Does nothing if there is no object bound to the given name.

Parameters:

name - the name of the object to remove

Returns:

The old object

Throws:

java.lang.IllegalStateException - if an attempt is made to access session data after the session has been invalidated.

setTimeout

void setTimeout(int interval)

Specifies the time, in seconds, between client requests before the servlet container will invalidate this session. A negative time indicates the session should never timeout.

Parameters:

interval - An integer specifying the number of seconds

getTimeout

int getTimeout()

Returns the maximum time interval, in seconds, that the servlet container will keep this session open between client accesses. After this interval, the servlet container will invalidate the session. The maximum time interval can be set with the setTimeout method. A negative time indicates the session should never timeout.

Returns:

an integer specifying the number of seconds this session remains open between client requests

See Also:

setTimeout(int)

getCreationTime

long getCreationTime()

Returns the time when this session was created, measured in milliseconds since midnight January 1, 1970 GMT.

Returns:

a long specifying when this session was created, expressed in milliseconds since 1/1/1970 GMT

Throws:

java.lang.IllegalStateException - if this method is called on an invalidated session

getLastAccessedTime

long getLastAccessedTime()

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.

Returns:

a long representing the last time the client sent a request associated with this session, expressed in milliseconds since 1/1/1970 GMT

Throws:

java.lang.IllegalStateException - if this method is called on an invalidated session

getSessionCount

int getSessionCount()

Returns the number of active sessions.

Returns:

# of active sessions.

isNew

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 JavaBridge.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:

java.lang.IllegalStateException - if an attempt is made to access session data after the session has been invalidated

destroy

void destroy()

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

Throws:

java.lang.IllegalStateException - if an attempt is made to access session data after the session has been invalidated

putAll

void putAll(java.util.Map vars)

Copies all bindings to the session's context layer data. Any existing binding with the same name is replaced.

Parameters:

vars - the map parameter cannot be null.

Throws:

java.lang.IllegalStateException - if an attempt is made to access session data after the session has been invalidated.

getAll

java.util.Map getAll()

Returns a map of all bindings maintained by this session.

Returns:

the map

Throws:

java.lang.IllegalStateException - if an attempt is made to access session data after it has been invalidated