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 java.io.Serializable;
22 import java.util.Map;
23
24 /**
25 * A {@code SessionContext} is a 'bucket' of data presented to a {@link SessionFactory SessionFactory} which interprets
26 * this data to construct {@link org.apache.shiro.session.Session Session} instances. It is essentially a Map of data
27 * with a few additional type-safe methods for easy retrieval of objects commonly used to construct Subject instances.
28 * <p/>
29 * While this interface contains type-safe setters and getters for common data types, the map can contain anything
30 * additional that might be needed by the {@code SessionFactory} implementation to construct {@code Session} instances.
31 * <p/>
32 * <b>USAGE</b>: Most Shiro end-users will never use a {@code SubjectContext} instance directly and instead will call
33 * the {@code Subject.}{@link org.apache.shiro.subject.Subject#getSession() getSession()} or
34 * {@code Subject.}{@link org.apache.shiro.subject.Subject#getSession(boolean) getSession(boolean)} methods (which
35 * will usually use {@code SessionContext} instances to start a session with the application's
36 * {@link SessionManager SessionManager}.
37 *
38 * @see org.apache.shiro.session.mgt.SessionManager#start SessionManager.start(SessionContext)
39 * @see org.apache.shiro.session.mgt.SessionFactory SessionFactory
40 * @since 1.0
41 */
42 public interface SessionContext extends Map<String, Object> {
43
44 /**
45 * Sets the originating host name or IP address (as a String) from where the {@code Subject} is initiating the
46 * {@code Session}.
47 * <p/>
48 * In web-based systems, this host can be inferred from the incoming request, e.g.
49 * {@code javax.servlet.ServletRequest#getRemoteAddr()} or {@code javax.servlet.ServletRequest#getRemoteHost()}
50 * methods, or in socket-based systems, it can be obtained via inspecting the socket
51 * initiator's host IP.
52 * <p/>
53 * Most secure environments <em>should</em> specify a valid, non-{@code null} {@code host}, since knowing the
54 * {@code host} allows for more flexibility when securing a system: by requiring an host, access control policies
55 * can also ensure access is restricted to specific client <em>locations</em> in addition to {@code Subject}
56 * principals, if so desired.
57 * <p/>
58 * <b>Caveat</b> - if clients to your system are on a
59 * public network (as would be the case for a public web site), odds are high the clients can be
60 * behind a NAT (Network Address Translation) router or HTTP proxy server. If so, all clients
61 * accessing your system behind that router or proxy will have the same originating host.
62 * If your system is configured to allow only one session per host, then the next request from a
63 * different NAT or proxy client will fail and access will be denied for that client. Just be
64 * aware that host-based security policies are best utilized in LAN or private WAN environments
65 * when you can be ensure clients will not share IPs or be behind such NAT routers or
66 * proxy servers.
67 *
68 * @param host the originating host name or IP address (as a String) from where the {@code Subject} is
69 * initiating the {@code Session}.
70 * @since 1.0
71 */
72 void setHost(String host);
73
74 /**
75 * Returns the originating host name or IP address (as a String) from where the {@code Subject} is initiating the
76 * {@code Session}.
77 * <p/>
78 * See the {@link #setHost(String) setHost(String)} JavaDoc for more about security policies based on the
79 * {@code Session} host.
80 *
81 * @return the originating host name or IP address (as a String) from where the {@code Subject} is initiating the
82 * {@code Session}.
83 * @see #setHost(String) setHost(String)
84 */
85 String getHost();
86
87 Serializable getSessionId();
88
89 void setSessionId(Serializable sessionId);
90
91 }