001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied.  See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019package org.apache.shiro.session.mgt;
020
021import org.apache.shiro.session.Session;
022import org.apache.shiro.session.SessionException;
023
024/**
025 * A SessionManager manages the creation, maintenance, and clean-up of all application
026 * {@link org.apache.shiro.session.Session Session}s.
027 *
028 * @since 0.1
029 */
030public interface SessionManager {
031
032    /**
033     * Starts a new session based on the specified contextual initialization data, which can be used by the underlying
034     * implementation to determine how exactly to create the internal Session instance.
035     * <p/>
036     * This method is mainly used in framework development, as the implementation will often relay the argument
037     * to an underlying {@link SessionFactory} which could use the context to construct the internal Session
038     * instance in a specific manner.  This allows pluggable {@link org.apache.shiro.session.Session Session} creation
039     * logic by simply injecting a {@code SessionFactory} into the {@code SessionManager} instance.
040     *
041     * @param context the contextual initialization data that can be used by the implementation or underlying
042     *                {@link SessionFactory} when instantiating the internal {@code Session} instance.
043     * @return the newly created session.
044     * @see SessionFactory#createSession(SessionContext)
045     * @since 1.0
046     */
047    Session start(SessionContext context);
048
049    /**
050     * Retrieves the session corresponding to the specified contextual data (such as a session ID if applicable), or
051     * {@code null} if no Session could be found.  If a session is found but invalid (stopped or expired), a
052     * {@link SessionException} will be thrown.
053     *
054     * @param key the Session key to use to look-up the Session
055     * @return the {@code Session} instance corresponding to the given lookup key or {@code null} if no session
056     *         could be acquired.
057     * @throws SessionException if a session was found but it was invalid (stopped/expired).
058     * @since 1.0
059     */
060    Session getSession(SessionKey key) throws SessionException;
061}