/*
 * The contents of this file are subject to the Mozilla Public License Version 1.1
 * (the "License"); you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at <http://www.mozilla.org/MPL/>.
 * 
 * Software distributed under the License is distributed on an "AS IS" basis, WITHOUT
 * WARRANTY OF ANY KIND, either express or implied. See the License for the specific
 * language governing rights and limitations under the License.
 * 
 * The Original Code is the Venice Web Communities System.
 * 
 * The Initial Developer of the Original Code is Eric J. Bowersox <erbo@silcom.com>,
 * for Silverwrist Design Studios.  Portions created by Eric J. Bowersox are
 * Copyright (C) 2002-03 Eric J. Bowersox/Silverwrist Design Studios.  All Rights Reserved.
 * 
 * Contributor(s): 
 */
package com.silverwrist.dynamo.iface;

import com.silverwrist.dynamo.RequestType;

/**
 * Represents a <EM>session object</EM> that persists across requests on the same session.  The
 * <CODE>SessionInfo</CODE> object contains an instance of
 * {@link com.silverwrist.dynamo.iface.ObjectStore ObjectStore}, so it can hold arbitrary objects.
 * <p>Sessions are held in memory for a certain time between requests, and are discarded
 * if they are inactive longer than that.  The length of this time may be adjusted using the
 * {@link #setMaxInactiveInterval(int) setMaxInactiveInterval()} method, and may be retrieved using
 * {@link #getMaxInactiveInterval() getMaxInactiveInterval()}.  They may also be manually removed
 * at any time.
 * <p>When values are added to or removed from the <CODE>ObjectStore</CODE> associated with a
 * <CODE>Sessioninfo</CODE>, if they implement the interface
 * {@link com.silverwrist.dynamo.event.SessionValueBindListener SessionValueBindListener}, the methods
 * on that interface are called to indicate that the variable has been bound to or unbound from
 * a session.
 * <p>In an HTTP request environment, the <CODE>SessionInfo</CODE> is implemented by an object
 * which is referenced by the <CODE>HttpSession</CODE>.  XML-RPC requests use a "session ID" parameter
 * which is used to identify particular sessions.
 *
 * @author Eric J. Bowersox &lt;erbo@silcom.com&gt;
 * @version X
 */
public interface SessionInfo extends ObjectStore
{
  /**
   * Returns a value indicating the type of this session.  This will usually be the same as the type of the
   * {@link com.silverwrist.dynamo.iface.Request Request} objects that work with this session object.
   *
   * @return The type of this request.
   * @see com.silverwrist.dynamo.RequestType
   * @see com.silverwrist.dynamo.iface.Request#getType()
   */
  public RequestType getSessionType();

  /**
   * Returns the unique identifier for this session.
   *
   * @return The unique identifier for this session.
   */
  public String getID();

  /**
   * Returns the time at which this session was created.  This is expressed in the same units as
   * <CODE>System.currentTimeMillis()</CODE>.
   *
   * @return The time at which the session was created.
   */
  public long getCreationTime();

  /**
   * Returns the time at which this session was last accessed.  This is expressed in the same units as
   * <CODE>System.currentTimeMillis()</CODE>.
   *
   * @return The time at which the session was last accessed.
   */
  public long getLastAccessedTime();

  /**
   * Specifies the time, in seconds, between client requests before the framework will invalidate this
   * session. A negative value indicates the session should never timeout.
   *
   * @param interval An integer specifying the number of seconds.
   */
  public void setMaxInactiveInterval(int interval);

  /**
   * Returns the maximum time interval, in seconds, that the framework will keep this session open between
   * client accesses. After this interval, the framework will invalidate the session. The maximum time
   * interval can be set with the {@link #setMaxInactiveInterval(int) setMaxInactiveInterval} method. A negative
   * value indicates the session should never timeout.
   *
   * @return An integer specifying the number of seconds this session remains open between client requests.
   */
  public int getMaxInactiveInterval();

  /**
   * Causes the session to be invalidated, and any objects bound to it to be unbound.  Also invalidates
   * any underlying session attributes in the enclosing environment (such as the servlet container), if
   * present.
   */
  public void invalidate();

  /**
   * Causes the session to be invalidated, and any objects bound to it to be unbound.  If there are any
   * underlying session attributes in the enclosing environment (such as the servlet container), they are
   * unaffected.
   */
  public void detach();

} // end interface SessionInfo
