/*
 * Copyright 2005-2008 Les Hazlewood
 *
 * Licensed under the Apache License, Version 2.0 (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.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.jsecurity.session.mgt;

import org.jsecurity.authz.HostUnauthorizedException;
import org.jsecurity.session.InvalidSessionException;

import java.io.Serializable;
import java.net.InetAddress;
import java.util.Collection;
import java.util.Date;

/**
 * A SessionManager manages the creation, maintenance, and clean-up of all application
 * {@link org.jsecurity.session.Session Session}s.
 *
 * @since 0.1
 * @author Les Hazlewood
 */
public interface SessionManager {

    /**
     * Starts a new session within the system for the host with the specified originating IP
     * address.
     *
     * <p><b>Note</b>: see the
     * {@link org.jsecurity.session.SessionFactory#start(java.net.InetAddress) SessionFactory.init(InetAddress)} method
     * about the implications of using <tt>InetAddress</tt>es in access control policies.
     *
     * @param originatingHost the originating host InetAddress of the external party
     * (user, 3rd party product, etc) that is attempting to interact with the system.
     * 
     * @return the system identifier of the newly created session.
     *
     * @see org.jsecurity.session.SessionFactory#start(InetAddress)
     * @throws IllegalArgumentException if the host specified is not valid.
     * @throws org.jsecurity.authz.HostUnauthorizedException if the host specified is not allowed to start sessions.
     */
    Serializable start( InetAddress originatingHost )
        throws HostUnauthorizedException, IllegalArgumentException;

    /**
     * Returns the time the Session identified by the specified <tt>sessionId</tt> was started
     * in the system.
     * @param sessionId the system identifier for the session of interest.
     * @return the system time the specified session was started (i.e. created).
     * @see org.jsecurity.session.Session#getStartTimestamp()
     */
    Date getStartTimestamp( Serializable sessionId );

    /**
     * Returns the time the <tt>Session</tt> identified by the specified <tt>sessionId</tt> was
     * stopped or expired in the system, or <tt>null</tt> if the session is still active. A
     * session could be stopped for a number of reasons.  See the
     * {@link org.jsecurity.session.Session#stop() Session.destroy()} method for more details.
     *
     * @param sessionId the session ID whose stop timestamp is being retrieved.
     * @return the system time the session stopped or expired, or <tt>null</tt> if the session
     * is still active.
     * @see org.jsecurity.session.Session#getStopTimestamp()
     */
    Date getStopTimestamp( Serializable sessionId );

    /**
     * Returns the time the <tt>Session</tt> identified by the specified <tt>sessionId</tt> last
     * interacted with the system.
     * @param sessionId the system identifier for the session of interest
     * @return tye time the session last accessed the system
     * @see org.jsecurity.session.Session#getLastAccessTime()
     * @see org.jsecurity.session.Session#touch()
     */
    Date getLastAccessTime( Serializable sessionId );

    /**
     * Returns <tt>true</tt> if the session with the specified <tt>sessionId</tt> has been
     * stopped, <tt>false</tt> otherwise.
     * @param sessionId the id of the session to check
     * @return <tt>true</tt> if the session has been stopped, <tt>false</tt> otherwise.
     */
    boolean isStopped( Serializable sessionId );

    /**
     * Returns whether or not the session identified by the given <tt>sessionId</tt> has expired
     * in the system.
     *
     * <p>This method can be used in conjunction with {@link #isStopped} to determine if the
     * user has logged out, depending upon an application's inference of business rules.
     * Assuming the only way for a session to be stopped (other than from
     * expiration) is due to an explicit user log-out you can infer that if the session
     * {@link #isStopped} but not {@link #isExpired}, then the user has logged-out.  Of course,
     * this is dependent upon the above assumption and may not be true for every application.
     *
     * @param sessionId the system identifier of the session of interest
     * @return true if the session has expired, false otherwise.
     */
    boolean isExpired( Serializable sessionId );

    /**
     * Returns the time in milliseconds that the specified session may remain idle before expiring.
     *
     * <ul>
     *     <li>A negative return value means the session will never expire.</li>
     *     <li>A non-negative return value (0 or greater) means the session expiration will occur if idle for that
     * length of time.</li>
     * </ul>
     *
     * @param sessionId the system identifier of the session of interest.
     * @return the time in milliseconds that the specified session may remain idle before expiring.
     * @throws org.jsecurity.session.InvalidSessionException if the session has been stopped or expired prior to calling this method.
     * @since 0.2
     */
    long getTimeout( Serializable sessionId ) throws InvalidSessionException;

    /**
     * Sets the time in milliseconds that the specified session may remain idle before expiring.
     *
     * <ul>
     *     <li>A negative return value means the session will never expire.</li>
     *     <li>A non-negative return value (0 or greater) means the session expiration will occur if idle for that
     * length of time.</li>
     * </ul>
     *
     * @param sessionId the system identifier of the session of interest.
     * @param maxIdleTimeInMillis the time in milliseconds that the specified session may remain idle before expiring.
     * @throws org.jsecurity.session.InvalidSessionException if the session has been stopped or expired prior to calling this method.
     * @since 0.2
     */
    void setTimeout( Serializable sessionId, long maxIdleTimeInMillis ) throws InvalidSessionException;

    /**
     * Updates the last accessed time of the session identified by <code>sessionId</code>.  This
     * can be used to explicitly ensure that a session does not time out.
     *
     * @see org.jsecurity.session.Session#touch
     *
     * @param sessionId the id of the session to update.
     * @throws org.jsecurity.session.InvalidSessionException if the session has been stopped or expired prior to calling this method.
     */
    void touch( Serializable sessionId ) throws InvalidSessionException;


    /**
     * Returns the IP address of the host where the session was started, if known.  If
     * no IP was specified when starting the session, this method returns <code>null</code>
     * @param sessionId the id of the session to query.
     *
     * @return the ip address of the host where the session originated, if known.  If unknown,
     * this method returns <code>null</code>.
     *
     * @see #start( InetAddress originatingHost ) init( InetAddress originatingHost )
     */
    InetAddress getHostAddress( Serializable sessionId );

    /**
     * Explicitly stops the session identified by <tt>sessionId</tt>, thereby releasing all
     * associated resources.
     * @param sessionId the system identfier of the system to destroy.
     * @throws InvalidSessionException if the session has stopped or expired prior to calling
     * this method.
     * @see org.jsecurity.session.Session#stop
     */
    void stop( Serializable sessionId ) throws InvalidSessionException;

    /**
     * Returns the keys of all the attributes stored under the session identified by <tt>sessionId</tt>.
     * If there are no attributes, this returns an empty collection.
     * @param sessionId the system identifier of the system to access.
     * @return the keys of all attributes stored under the specified session, or an empty collection if
     * there are no session attributes.
     * @throws InvalidSessionException if the specified session has stopped or expired prior to calling this method.
     * @see org.jsecurity.session.Session#getAttributeKeys()
     * @since 0.2
     */
    Collection<Object> getAttributeKeys( Serializable sessionId );

    /**
     * Returns the object bound to the specified session identified by the specified key.  If there
     * is noobject bound under the key for the given session, <tt>null</tt> is returned.
     * @param sessionId the system identifier of the session of interest
     * @param key the unique name of the object bound to the specified session
     * @return the object bound under the specified <tt>key</tt> name or <tt>null</tt> if there is
     * no object bound under that name.
     * @throws InvalidSessionException if the specified session has stopped or expired prior to calling this method.
     * @see org.jsecurity.session.Session#getAttribute(Object key)
     */
    Object getAttribute( Serializable sessionId, Object key ) throws InvalidSessionException;

    /**
     * Binds the specified <tt>value</tt> to the specified session uniquely identified by the
     * specifed <tt>key</tt> name.  If there is already an object bound under the <tt>key</tt>
     * name, that existing object will be replaced by the new <tt>value</tt>.
     *
     * <p>If the <tt>value</tt> parameter is null, it has the same effect as if the
     * {@link #removeAttribute(Serializable sessionId, Object key)} method was called.
     *
     * @param sessionId the system identifier of the session of interest
     * @param key the name under which the <tt>value</tt> object will be bound in this session
     * @param value the object to bind in this session.
     * @throws InvalidSessionException if the specified session has stopped or expired prior to calling this method.
     * @see org.jsecurity.session.Session#setAttribute(Object key, Object value)
     */
    void setAttribute( Serializable sessionId, Object key, Object value ) throws InvalidSessionException;

    /**
     * Removes (unbinds) the object bound to this session under the specified <tt>key</tt> name.
     * @param sessionId the system identifier of the session of interest
     * @param key the name uniquely identifying the object to remove
     * @return the object removed or <tt>null</tt> if there was no object bound under the specified 
     * <tt>key</tt> name.
     * @throws InvalidSessionException if the specified session has stopped or expired prior to calling this method.
     * @see org.jsecurity.session.Session#removeAttribute(Object key)
     */
    Object removeAttribute( Serializable sessionId, Object key ) throws InvalidSessionException;
}