core/src/main/java/org/apache/ki/session/mgt/SessionManager.java

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you 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.apache.ki.session.mgt;

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

import org.apache.ki.authz.HostUnauthorizedException;
import org.apache.ki.session.InvalidSessionException;


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

    /**
     * Starts a new session within the system for the host with the specified originating IP address.
     *
     * <p>An implementation of this interface may be configured to allow a <tt>null</tt> argument,
     * thereby indicating the originating IP is either unknown or has been
     * explicitly omitted by the caller.  However, if the implementation is configured to require
     * a valid <tt>hostAddress</tt> and the argument is <tt>null</tt>, an
     * {@link IllegalArgumentException IllegalArgumentException} will be thrown.
     *
     * <p>In web-based systems, this InetAddress can be inferred from the
     * {@link javax.servlet.ServletRequest#getRemoteAddr() javax.servlet.ServletRequest.getRemoteAddr()}
     * method, or in socket-based systems, it can be obtained via inspecting the socket
     * initiator's host IP.
     *
     * <p>Most secure environments <em>should</em> require that a valid, non-<tt>null</tt>
     * <tt>hostAddress</tt> be specified, since knowing the <tt>hostAddress</tt> allows for more
     * flexibility when securing a system: by requiring an InetAddress, access control policies
     * can also ensure access is restricted to specific client <em>locations</em> in
     * addition to user principals, if so desired.
     *
     * <p><b>Caveat</b> - if clients to your system are on a
     * public network (as would be the case for a public web site), odds are high the clients can be
     * behind a NAT (Network Address Translation) router or HTTP proxy server.  If so, all clients
     * accessing your system behind that router or proxy will have the same originating IP address.
     * If your system is configured to allow only one session per IP, then the next request from a
     * different NAT or proxy client will fail and access will be deny for that client.  Just be
     * aware that ip-based security policies are best utilized in LAN or private WAN environments
     * when you can be ensure clients will not share IPs or be behind such NAT routers or
     * proxy servers.
     *
     * @param originatingHost the originating host InetAddress of the external party
     *                        (user, 3rd party product, etc) that is attempting to interact with the system.
     * @return a handle to the newly created session.
     * @throws org.apache.ki.authz.HostUnauthorizedException if the system access control policy restricts access based
     *                                   on client location/IP and the specified hostAddress hasn't been enabled.
     * @throws IllegalArgumentException  if the system is configured to require a valid,
     *                                   non-<tt>null</tt> argument and the specified <tt>hostAddress</tt> is null.
     */
    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.apache.ki.session.Session#getStartTimestamp()
     */
    Date getStartTimestamp(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.apache.ki.session.Session#getLastAccessTime()
     * @see org.apache.ki.session.Session#touch()
     */
    Date getLastAccessTime(Serializable sessionId);


    /**
     * Returns <tt>true</tt> if the session is valid (it exists and is not stopped nor expired), <tt>false</tt> otherwise.
     *
     * @param sessionId the id of the session to check
     * @return <tt>true</tt> if the session is valid (exists and is not stopped or expired), <tt>false</tt> otherwise.
     */
    boolean isValid(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.apache.ki.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.apache.ki.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.
     *
     * @param sessionId the id of the session to update.
     * @throws org.apache.ki.session.InvalidSessionException
     *          if the session has been stopped or expired prior to calling this method.
     * @see org.apache.ki.session.Session#touch
     */
    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.apache.ki.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.apache.ki.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.apache.ki.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.apache.ki.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.apache.ki.session.Session#removeAttribute(Object key)
     */
    Object removeAttribute(Serializable sessionId, Object key) throws InvalidSessionException;
}