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     */
019    package org.apache.shiro.session.mgt;
020    
021    import org.apache.shiro.session.Session;
022    import 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     * @author Les Hazlewood
029     * @since 0.1
030     */
031    public interface SessionManager {
032    
033        /**
034         * Starts a new session based on the specified contextual initialization data, which can be used by the underlying
035         * implementation to determine how exactly to create the internal Session instance.
036         * <p/>
037         * This method is mainly used in framework development, as the implementation will often relay the argument
038         * to an underlying {@link SessionFactory} which could use the context to construct the internal Session
039         * instance in a specific manner.  This allows pluggable {@link org.apache.shiro.session.Session Session} creation
040         * logic by simply injecting a {@code SessionFactory} into the {@code SessionManager} instance.
041         *
042         * @param context the contextual initialization data that can be used by the implementation or underlying
043         *                {@link SessionFactory} when instantiating the internal {@code Session} instance.
044         * @return the newly created session.
045         * @see SessionFactory#createSession(SessionContext)
046         * @since 1.0
047         */
048        Session start(SessionContext context);
049    
050        /**
051         * Retrieves the session corresponding to the specified contextual data (such as a session ID if applicable), or
052         * {@code null} if no Session could be found.  If a session is found but invalid (stopped or expired), a
053         * {@link SessionException} will be thrown.
054         *
055         * @param key the Session key to use to look-up the Session
056         * @return the {@code Session} instance corresponding to the given lookup key or {@code null} if no session
057         *         could be acquired.
058         * @throws SessionException if a session was found but it was invalid (stopped/expired).
059         * @since 1.0
060         */
061        Session getSession(SessionKey key) throws SessionException;
062    }