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:

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