php.java.bridge
Interface ISession

All Known Implementing Classes:
HttpSessionFacade, Session

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") || 1;
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.

When java_session() is called with a session name, the java_session() primitive does not set a cookie and the above restriction does not apply. If it is necessary that the client joins the session, the following code can be used:
session_start(); // set a cookie

// check if client has joined the session
function is_new() {
  return array_key_exists(session_name(), $_COOKIE);
}

// request the server session and automatically
// destroy an old session if is_new() returns true
$session=java_session(session_id(), is_new());
if($session->isNew()) {
   header("Location: http://".$_SERVER['HTTP_HOST'] .dirname($_SERVER['PHP_SELF']) ."/welcomeURL.html");
}


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 ob)
          Returns the object bound to the given name in the session's application layer data.
 java.util.Map getAll()
          Returns a map of all bindings maintained by this session.
 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 ob1, java.lang.Object ob2)
          Binds the specified object into the session's application layer data with the given name.
 void putAll(java.util.Map vars)
          Copies all bindings to the session's application layer data.
 java.lang.Object remove(java.lang.Object ob)
          Removes the object bound to the given name in the session's application layer data.
 void setTimeout(int timeout)
          Specifies the time, in seconds, between client requests before the servlet container will invalidate this session.
 

Method Detail

get

java.lang.Object get(java.lang.Object ob)
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:
java.lang.IllegalStateException - if an attempt is made to access session data after it has been invalidated

put

void put(java.lang.Object ob1,
         java.lang.Object ob2)
Binds the specified object into the session's application 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 ob)
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.

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

setTimeout

void setTimeout(int timeout)
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)

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 application 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