/*
 * Copyright 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.apache.shiro.session.mgt;

import org.apache.shiro.session.InvalidSessionException;

import java.util.Collection;
import java.util.Date;

/**
 * A {@code Native} session manager is one that manages sessions natively - that is, it is directly responsible
 * for the creation, persistence and removal of {@link org.apache.shiro.session.Session Session} instances and their
 * lifecycles.
 *
 * @since 1.0
 */
public interface NativeSessionManager extends SessionManager {

    /**
     * Returns the time the associated {@code Session} started (was created).
     *
     * @param key the session key to use to look up the target session.
     * @return the time the specified {@code Session} started (was created).
     * @see org.apache.shiro.session.Session#getStartTimestamp()
     */
    Date getStartTimestamp(SessionKey key);

    /**
     * Returns the time the associated {@code Session} last interacted with the system.
     *
     * @param key the session key to use to look up the target session.
     * @return time the session last accessed the system
     * @see org.apache.shiro.session.Session#getLastAccessTime()
     * @see org.apache.shiro.session.Session#touch()
     */
    Date getLastAccessTime(SessionKey key);

    /**
     * Returns {@code true} if the associated session is valid (it exists and is not stopped nor expired),
     * {@code false} otherwise.
     *
     * @param key the session key to use to look up the target session.
     * @return {@code true} if the session is valid (exists and is not stopped or expired), {@code false} otherwise.
     */
    boolean isValid(SessionKey key);

    /**
     * Returns quietly if the associated session is valid (it exists and is not stopped or expired) or throws
     * an {@link org.apache.shiro.session.InvalidSessionException} indicating that the session id is invalid.  This
     * might be preferred to be used instead of {@link #isValid} since any exception thrown will definitively explain
     * the reason for invalidation.
     *
     * @param key the session key to use to look up the target session.
     * @throws org.apache.shiro.session.InvalidSessionException
     *          if the session id is invalid (it does not exist or it is stopped or expired).
     */
    void checkValid(SessionKey key) throws InvalidSessionException;

    /**
     * Returns the time in milliseconds that the associated 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 key the session key to use to look up the target session.
     * @return the time in milliseconds that the associated session may remain idle before expiring.
     * @throws org.apache.shiro.session.InvalidSessionException
     *          if the session has been stopped or expired prior to calling this method.
     */
    long getTimeout(SessionKey key) throws InvalidSessionException;

    /**
     * Sets the time in milliseconds that the associated 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 key                 the session key to use to look up the target session.
     * @param maxIdleTimeInMillis the time in milliseconds that the associated session may remain idle before expiring.
     * @throws org.apache.shiro.session.InvalidSessionException
     *          if the session has been stopped or expired prior to calling this method.
     */
    void setTimeout(SessionKey key, 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 key the session key to use to look up the target session.
     * @throws org.apache.shiro.session.InvalidSessionException
     *          if the session has been stopped or expired prior to calling this method.
     * @see org.apache.shiro.session.Session#touch
     */
    void touch(SessionKey key) throws InvalidSessionException;

    /**
     * Returns the host name or IP string of the host where the session was started, if known.  If
     * no host name or IP was specified when starting the session, this method returns {@code null}
     *
     * @param key the session key to use to look up the target session.
     * @return the host name or ip address of the host where the session originated, if known.  If unknown,
     *         this method returns {@code null}.
     */
    String getHost(SessionKey key);

    /**
     * Explicitly stops the associated session, thereby releasing all of its resources.
     *
     * @param key the session key to use to look up the target session.
     * @throws InvalidSessionException if the session has stopped or expired prior to calling this method.
     * @see org.apache.shiro.session.Session#stop
     */
    void stop(SessionKey key) throws InvalidSessionException;

    /**
     * Returns all attribute keys maintained by the target session or an empty collection if there are no attributes.
     *
     * @param sessionKey the session key to use to look up the target session.
     * @return all attribute keys maintained by the target session or an empty collection if there are no attributes.
     * @throws InvalidSessionException if the associated session has stopped or expired prior to calling this method.
     * @see org.apache.shiro.session.Session#getAttributeKeys()
     */
    Collection<Object> getAttributeKeys(SessionKey sessionKey);

    /**
     * Returns the object bound to the associated session identified by the specified attribute key.  If there
     * is no object bound under the attribute key for the given session, {@code null} is returned.
     *
     * @param sessionKey   session key to use to look up the target session.
     * @param attributeKey the unique name of the object bound to the associated session
     * @return the object bound under the {@code attributeKey} or {@code null} if there is no object bound.
     * @throws InvalidSessionException if the specified session has stopped or expired prior to calling this method.
     * @see org.apache.shiro.session.Session#getAttribute(Object key)
     */
    Object getAttribute(SessionKey sessionKey, Object attributeKey) throws InvalidSessionException;

    /**
     * Binds the specified {@code value} to the associated session uniquely identified by the {@code attributeKey}.
     * If there is already a session attribute bound under the {@code attributeKey}, that existing object will be
     * replaced by the new {@code value}.
     * <p/>
     * If the {@code value} parameter is null, it has the same effect as if the
     * {@link #removeAttribute(SessionKey sessionKey, Object attributeKey)} method was called.
     *
     * @param sessionKey   the session key to use to look up the target session.
     * @param attributeKey the key under which the {@code value} 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.shiro.session.Session#setAttribute(Object key, Object value)
     */
    void setAttribute(SessionKey sessionKey, Object attributeKey, Object value) throws InvalidSessionException;

    /**
     * Removes (unbinds) the object bound to associated {@code Session} under the given {@code attributeKey}.
     *
     * @param sessionKey   session key to use to look up the target session.
     * @param attributeKey the key uniquely identifying the object to remove
     * @return the object removed or {@code null} if there was no object bound under the specified {@code attributeKey}.
     * @throws InvalidSessionException if the specified session has stopped or expired prior to calling this method.
     * @see org.apache.shiro.session.Session#removeAttribute(Object key)
     */
    Object removeAttribute(SessionKey sessionKey, Object attributeKey) throws InvalidSessionException;

}