View Javadoc

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  }