/*
 * Created on 2004-8-11
 *
 * To change the template for this generated file go to
 * Window - Preferences - Java - Code Generation - Code and Comments
 */
package workflow.services;

import workflow.wfmc.pm.Participant;

/**
 * @author reic
 *
 * To change the template for this generated type comment go to
 * Window - Preferences - Java - Code Generation - Code and Comments
 */
public interface WorkflowSession
{
	/**
	 *
	 * Returns the time when this session was created, measured
	 * in milliseconds since midnight January 1, 1970 GMT.
	 *
	 * @return				a <code>long</code> specifying
	 * 					when this session was created,
	 *					expressed in 
	 *					milliseconds since 1/1/1970 GMT
	 *
	 * @exception IllegalStateException	if this method is called on an
	 *					invalidated session
	 *
	 */

	public long getCreationTime();

	/**
	 *
	 * Returns a string containing the unique identifier assigned 
	 * to this session. The identifier is assigned 
	 * by the servlet container and is implementation dependent.
	 * 
	 * @return				a string specifying the identifier
	 *					assigned to this session
	 *
	 * @exception IllegalStateException	if this method is called on an
	 *					invalidated session
	 *
	 */

	public String getId();

	/**
	 *
	 * Returns the last time the client sent a request associated with
	 * this session, as the number of milliseconds since midnight
	 * January 1, 1970 GMT, and marked by the time the container received the request. 
	 *
	 * <p>Actions that your application takes, such as getting or setting
	 * a value associated with the session, do not affect the access
	 * time.
	 *
	 * @return				a <code>long</code>
	 *					representing the last time 
	 *					the client sent a request associated
	 *					with this session, expressed in 
	 *					milliseconds since 1/1/1970 GMT
	 *
	 * @exception IllegalStateException	if this method is called on an
	 *					invalidated session
	 *
	 */

	public long getLastAccessedTime();

	/**
	 *
	 * 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.
	 *
	 * @param interval		An integer specifying the number
	 * 				of seconds 
	 *
	 */

	public void setMaxInactiveInterval(int interval);

	/**
		* 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 <code>setMaxInactiveInterval</code> method.
		* A negative time indicates the session should never timeout.
		*  
		*
		* @return		an integer specifying the number of
		*			seconds this session remains open
		*			between client requests
		*
		* @see		#setMaxInactiveInterval
		*
		*
		*/

	public int getMaxInactiveInterval();

	/**
	 *
	 * Invalidates this session then unbinds any objects bound
	 * to it. 
	 *
	 * @exception IllegalStateException	if this method is called on an
	 *					already invalidated session
	 *
	 */

	public void invalidate();

	/**
	 *
	 * Returns <code>true</code> if the client does not yet know about the
	 * session or if the client chooses not to join the session.  For 
	 * example, if the server used only cookie-based sessions, and
	 * the client had disabled the use of cookies, then a session would
	 * be new on each request.
	 *
	 * @return 				<code>true</code> if the 
	 *					server has created a session, 
	 *					but the client has not yet joined
	 *
	 * @exception IllegalStateException	if this method is called on an
	 *					already invalidated session
	 *
	 */

	public boolean isNew();

	/**
	 * Return the authenticated Participant that is associated with this Session.
	 * This provides an <code>Authenticator</code> with a means to cache a
	 * previously authenticated Participant, and avoid potentially expensive
	 * <code>Realm.authenticate()</code> calls on every request.  If there
	 * is no current associated Participant, return <code>null</code>.
	 */
	public Participant getParticipant();

	/**
	 * Set the authenticated Participant that is associated with this Session.
	 *
	 * @param participant The new Participant, or <code>null</code> if none
	 */
	public void setParticipant(Participant participant);
}
