core/src/main/java/org/apache/shiro/session/mgt/SessionContext.java

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package org.apache.shiro.session.mgt;

import java.io.Serializable;
import java.util.Map;

/**
 * A {@code SessionContext} is a 'bucket' of data presented to a {@link SessionFactory SessionFactory} which interprets
 * this data to construct {@link org.apache.shiro.session.Session Session} instances.  It is essentially a Map of data
 * with a few additional type-safe methods for easy retrieval of objects commonly used to construct Subject instances.
 * <p/>
 * While this interface contains type-safe setters and getters for common data types, the map can contain anything
 * additional that might be needed by the {@code SessionFactory} implementation to construct {@code Session} instances.
 * <p/>
 * <b>USAGE</b>: Most Shiro end-users will never use a {@code SubjectContext} instance directly and instead will call
 * the {@code Subject.}{@link org.apache.shiro.subject.Subject#getSession() getSession()} or
 * {@code Subject.}{@link org.apache.shiro.subject.Subject#getSession(boolean) getSession(boolean)} methods (which
 * will usually use {@code SessionContext} instances to start a session with the application's
 * {@link SessionManager SessionManager}.
 *
 * @see org.apache.shiro.session.mgt.SessionManager#start SessionManager.start(SessionContext)
 * @see org.apache.shiro.session.mgt.SessionFactory SessionFactory
 * @since 1.0
 */
public interface SessionContext extends Map<String, Object> {

    /**
     * Sets the originating host name or IP address (as a String) from where the {@code Subject} is initiating the
     * {@code Session}.
     * <p/>
     * In web-based systems, this host can be inferred from the incoming request, e.g.
     * {@code javax.servlet.ServletRequest#getRemoteAddr()} or {@code javax.servlet.ServletRequest#getRemoteHost()}
     * methods, or in socket-based systems, it can be obtained via inspecting the socket
     * initiator's host IP.
     * <p/>
     * Most secure environments <em>should</em> specify a valid, non-{@code null} {@code host}, since knowing the
     * {@code host} allows for more flexibility when securing a system: by requiring an host, access control policies
     * can also ensure access is restricted to specific client <em>locations</em> in addition to {@code Subject}
     * principals, if so desired.
     * <p/>
     * <b>Caveat</b> - if clients to your system are on a
     * public network (as would be the case for a public web site), odds are high the clients can be
     * behind a NAT (Network Address Translation) router or HTTP proxy server.  If so, all clients
     * accessing your system behind that router or proxy will have the same originating host.
     * If your system is configured to allow only one session per host, then the next request from a
     * different NAT or proxy client will fail and access will be denied for that client.  Just be
     * aware that host-based security policies are best utilized in LAN or private WAN environments
     * when you can be ensure clients will not share IPs or be behind such NAT routers or
     * proxy servers.
     *
     * @param host the originating host name or IP address (as a String) from where the {@code Subject} is
     *             initiating the {@code Session}.
     * @since 1.0
     */
    void setHost(String host);

    /**
     * Returns the originating host name or IP address (as a String) from where the {@code Subject} is initiating the
     * {@code Session}.
     * <p/>
     * See the {@link #setHost(String) setHost(String)} JavaDoc for more about security policies based on the
     * {@code Session} host.
     *
     * @return the originating host name or IP address (as a String) from where the {@code Subject} is initiating the
     *         {@code Session}.
     * @see #setHost(String) setHost(String)
     */
    String getHost();

    Serializable getSessionId();

    void setSessionId(Serializable sessionId);

}