## php.java.bridge
Interface ISession

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

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