1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.apache.shiro.session.mgt;
20
21 import org.apache.shiro.session.Session;
22 import org.apache.shiro.session.SessionException;
23
24 /**
25 * A SessionManager manages the creation, maintenance, and clean-up of all application
26 * {@link org.apache.shiro.session.Session Session}s.
27 *
28 * @since 0.1
29 */
30 public interface SessionManager {
31
32 /**
33 * Starts a new session based on the specified contextual initialization data, which can be used by the underlying
34 * implementation to determine how exactly to create the internal Session instance.
35 * <p/>
36 * This method is mainly used in framework development, as the implementation will often relay the argument
37 * to an underlying {@link SessionFactory} which could use the context to construct the internal Session
38 * instance in a specific manner. This allows pluggable {@link org.apache.shiro.session.Session Session} creation
39 * logic by simply injecting a {@code SessionFactory} into the {@code SessionManager} instance.
40 *
41 * @param context the contextual initialization data that can be used by the implementation or underlying
42 * {@link SessionFactory} when instantiating the internal {@code Session} instance.
43 * @return the newly created session.
44 * @see SessionFactory#createSession(SessionContext)
45 * @since 1.0
46 */
47 Session start(SessionContext context);
48
49 /**
50 * Retrieves the session corresponding to the specified contextual data (such as a session ID if applicable), or
51 * {@code null} if no Session could be found. If a session is found but invalid (stopped or expired), a
52 * {@link SessionException} will be thrown.
53 *
54 * @param key the Session key to use to look-up the Session
55 * @return the {@code Session} instance corresponding to the given lookup key or {@code null} if no session
56 * could be acquired.
57 * @throws SessionException if a session was found but it was invalid (stopped/expired).
58 * @since 1.0
59 */
60 Session getSession(SessionKey key) throws SessionException;
61 }