### php.java.bridge

# Interface ISession

Known Implementing Classes:
  HttpSessionFacade

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

## 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.

`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.

## Method Details

### destroy

    public 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

### get

    public 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

### getAll

    public 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

### getSessionCount

    public int getSessionCount()

> Returns the number of active sessions.

> Returns:
>   # of active sessions.

### getTimeout

    public 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)`

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

### put

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

### putAll

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

### remove

    public 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

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

### setTimeout

    public 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