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 java.io.Serializable;
022 import java.util.Map;
023
024 /**
025 * A {@code SessionContext} is a 'bucket' of data presented to a {@link SessionFactory SessionFactory} which interprets
026 * this data to construct {@link org.apache.shiro.session.Session Session} instances. It is essentially a Map of data
027 * with a few additional type-safe methods for easy retrieval of objects commonly used to construct Subject instances.
028 * <p/>
029 * While this interface contains type-safe setters and getters for common data types, the map can contain anything
030 * additional that might be needed by the {@code SessionFactory} implementation to construct {@code Session} instances.
031 * <p/>
032 * <b>USAGE</b>: Most Shiro end-users will never use a {@code SubjectContext} instance directly and instead will call
033 * the {@code Subject.}{@link org.apache.shiro.subject.Subject#getSession() getSession()} or
034 * {@code Subject.}{@link org.apache.shiro.subject.Subject#getSession(boolean) getSession(boolean)} methods (which
035 * will usually use {@code SessionContext} instances to start a session with the application's
036 * {@link SessionManager SessionManager}.
037 *
038 * @author Les Hazlewood
039 * @see org.apache.shiro.session.mgt.SessionManager#start SessionManager.start(SessionContext)
040 * @see org.apache.shiro.session.mgt.SessionFactory SessionFactory
041 * @since 1.0
042 */
043 public interface SessionContext extends Map<String, Object> {
044
045 /**
046 * Sets the originating host name or IP address (as a String) from where the {@code Subject} is initiating the
047 * {@code Session}.
048 * <p/>
049 * In web-based systems, this host can be inferred from the incoming request, e.g.
050 * {@code javax.servlet.ServletRequest#getRemoteAddr()} or {@code javax.servlet.ServletRequest#getRemoteHost()}
051 * methods, or in socket-based systems, it can be obtained via inspecting the socket
052 * initiator's host IP.
053 * <p/>
054 * Most secure environments <em>should</em> specify a valid, non-{@code null} {@code host}, since knowing the
055 * {@code host} allows for more flexibility when securing a system: by requiring an host, access control policies
056 * can also ensure access is restricted to specific client <em>locations</em> in addition to {@code Subject}
057 * principals, if so desired.
058 * <p/>
059 * <b>Caveat</b> - if clients to your system are on a
060 * public network (as would be the case for a public web site), odds are high the clients can be
061 * behind a NAT (Network Address Translation) router or HTTP proxy server. If so, all clients
062 * accessing your system behind that router or proxy will have the same originating host.
063 * If your system is configured to allow only one session per host, then the next request from a
064 * different NAT or proxy client will fail and access will be denied for that client. Just be
065 * aware that host-based security policies are best utilized in LAN or private WAN environments
066 * when you can be ensure clients will not share IPs or be behind such NAT routers or
067 * proxy servers.
068 *
069 * @param host the originating host name or IP address (as a String) from where the {@code Subject} is
070 * initiating the {@code Session}.
071 * @since 1.0
072 */
073 void setHost(String host);
074
075 /**
076 * Returns the originating host name or IP address (as a String) from where the {@code Subject} is initiating the
077 * {@code Session}.
078 * <p/>
079 * See the {@link #setHost(String) setHost(String)} JavaDoc for more about security policies based on the
080 * {@code Session} host.
081 *
082 * @return the originating host name or IP address (as a String) from where the {@code Subject} is initiating the
083 * {@code Session}.
084 * @see #setHost(String) setHost(String)
085 */
086 String getHost();
087
088 Serializable getSessionId();
089
090 void setSessionId(Serializable sessionId);
091
092 }