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 */
019package org.apache.shiro.session.mgt;
020
021import java.io.Serializable;
022import 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 * @see org.apache.shiro.session.mgt.SessionManager#start SessionManager.start(SessionContext)
039 * @see org.apache.shiro.session.mgt.SessionFactory SessionFactory
040 * @since 1.0
041 */
042public interface SessionContext extends Map<String, Object> {
043
044    /**
045     * Sets the originating host name or IP address (as a String) from where the {@code Subject} is initiating the
046     * {@code Session}.
047     * <p/>
048     * In web-based systems, this host can be inferred from the incoming request, e.g.
049     * {@code javax.servlet.ServletRequest#getRemoteAddr()} or {@code javax.servlet.ServletRequest#getRemoteHost()}
050     * methods, or in socket-based systems, it can be obtained via inspecting the socket
051     * initiator's host IP.
052     * <p/>
053     * Most secure environments <em>should</em> specify a valid, non-{@code null} {@code host}, since knowing the
054     * {@code host} allows for more flexibility when securing a system: by requiring an host, access control policies
055     * can also ensure access is restricted to specific client <em>locations</em> in addition to {@code Subject}
056     * principals, if so desired.
057     * <p/>
058     * <b>Caveat</b> - if clients to your system are on a
059     * public network (as would be the case for a public web site), odds are high the clients can be
060     * behind a NAT (Network Address Translation) router or HTTP proxy server.  If so, all clients
061     * accessing your system behind that router or proxy will have the same originating host.
062     * If your system is configured to allow only one session per host, then the next request from a
063     * different NAT or proxy client will fail and access will be denied for that client.  Just be
064     * aware that host-based security policies are best utilized in LAN or private WAN environments
065     * when you can be ensure clients will not share IPs or be behind such NAT routers or
066     * proxy servers.
067     *
068     * @param host the originating host name or IP address (as a String) from where the {@code Subject} is
069     *             initiating the {@code Session}.
070     * @since 1.0
071     */
072    void setHost(String host);
073
074    /**
075     * Returns the originating host name or IP address (as a String) from where the {@code Subject} is initiating the
076     * {@code Session}.
077     * <p/>
078     * See the {@link #setHost(String) setHost(String)} JavaDoc for more about security policies based on the
079     * {@code Session} host.
080     *
081     * @return the originating host name or IP address (as a String) from where the {@code Subject} is initiating the
082     * {@code Session}.
083     * @see #setHost(String) setHost(String)
084     */
085    String getHost();
086
087    Serializable getSessionId();
088
089    void setSessionId(Serializable sessionId);
090
091}