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 module hunt.shiro.session.mgt.SessionContext; 20 21 import hunt.util.Common; 22 import hunt.collection.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 hunt.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 hunt.shiro.subject.Subject#getSession() getSession()} or 34 * {@code Subject.}{@link hunt.shiro.subject.Subject#getSession(bool) getSession(bool)} methods (which 35 * will usually use {@code SessionContext} instances to start a session with the application's 36 * {@link SessionManager SessionManager}. 37 * 38 * @see hunt.shiro.session.mgt.SessionManager#start SessionManager.start(SessionContext) 39 * @see hunt.shiro.session.mgt.SessionFactory SessionFactory 40 */ 41 interface SessionContext { // : Map!(string, Object) 42 43 /** 44 * Sets the originating host name or IP address (as a string) from where the {@code Subject} is initiating the 45 * {@code Session}. 46 * <p/> 47 * In web-based systems, this host can be inferred from the incoming request, e.g. 48 * {@code javax.servlet.ServletRequest#getRemoteAddr()} or {@code javax.servlet.ServletRequest#getRemoteHost()} 49 * methods, or in socket-based systems, it can be obtained via inspecting the socket 50 * initiator's host IP. 51 * <p/> 52 * Most secure environments <em>should</em> specify a valid, non-{@code null} {@code host}, since knowing the 53 * {@code host} allows for more flexibility when securing a system: by requiring an host, access control policies 54 * can also ensure access is restricted to specific client <em>locations</em> in addition to {@code Subject} 55 * principals, if so desired. 56 * <p/> 57 * <b>Caveat</b> - if clients to your system are on a 58 * public network (as would be the case for a public web site), odds are high the clients can be 59 * behind a NAT (Network Address Translation) router or HTTP proxy server. If so, all clients 60 * accessing your system behind that router or proxy will have the same originating host. 61 * If your system is configured to allow only one session per host, then the next request from a 62 * different NAT or proxy client will fail and access will be denied for that client. Just be 63 * aware that host-based security policies are best utilized in LAN or private WAN environments 64 * when you can be ensure clients will not share IPs or be behind such NAT routers or 65 * proxy servers. 66 * 67 * @param host the originating host name or IP address (as a string) from where the {@code Subject} is 68 * initiating the {@code Session}. 69 */ 70 void setHost(string host); 71 72 /** 73 * Returns the originating host name or IP address (as a string) from where the {@code Subject} is initiating the 74 * {@code Session}. 75 * <p/> 76 * See the {@link #setHost(string) setHost(string)} JavaDoc for more about security policies based on the 77 * {@code Session} host. 78 * 79 * @return the originating host name or IP address (as a string) from where the {@code Subject} is initiating the 80 * {@code Session}. 81 * @see #setHost(string) setHost(string) 82 */ 83 string getHost(); 84 85 string getSessionId(); 86 87 void setSessionId(string sessionId); 88 89 }