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.mgt;
020
021import org.apache.shiro.subject.Subject;
022
023/**
024 * A Default {@code SessionStorageEvaluator} that provides reasonable control over if and how Sessions may be used for
025 * storing Subject state.  See the {@link #isSessionStorageEnabled(org.apache.shiro.subject.Subject)}
026 * method for exact behavior.
027 *
028 * @since 1.2
029 */
030public class DefaultSessionStorageEvaluator implements SessionStorageEvaluator {
031
032    /**
033     * Global policy determining if Subject sessions may be used to persist Subject state if the Subject's Session
034     * does not yet exist.
035     */
036    private boolean sessionStorageEnabled = true;
037
038    /**
039     * This implementation functions as follows:
040     * <ul>
041     * <li>If the specified Subject already has an existing {@code Session} (typically because an application developer
042     * has called {@code subject.getSession()} already), Shiro will use that existing session to store subject state.</li>
043     * <li>If a Subject does not yet have a Session, this implementation checks the
044     * {@link #isSessionStorageEnabled() sessionStorageEnabled} property:
045     * <ul>
046     * <li>If {@code sessionStorageEnabled} is true (the default setting), a new session may be created to persist
047     * Subject state if necessary.</li>
048     * <li>If {@code sessionStorageEnabled} is {@code false}, a new session will <em>not</em> be created to persist
049     * session state.</li>
050     * </ul></li>
051     * </ul>
052     * Most applications use Sessions and are OK with the default {@code true} setting for {@code sessionStorageEnabled}.
053     * <p/>
054     * However, if your application is a purely 100% stateless application that never uses sessions,
055     * you will want to set {@code sessionStorageEnabled} to {@code false}.  Realize that a {@code false} value will
056     * ensure that any subject login only retains the authenticated identity for the duration of a request.  Any other
057     * requests, invocations or messages will not be authenticated.
058     *
059     * @param subject the {@code Subject} for which session state persistence may be enabled
060     * @return the value of {@link #isSessionStorageEnabled()} and ignores the {@code Subject} argument.
061     */
062    public boolean isSessionStorageEnabled(Subject subject) {
063        return (subject != null && subject.getSession(false) != null) || isSessionStorageEnabled();
064    }
065
066    /**
067     * Returns {@code true} if any Subject's {@code Session} may be used to persist that {@code Subject}'s state,
068     * {@code false} otherwise.  The default value is {@code true}.
069     * <p/>
070     * <b>N.B.</b> This is a global configuration setting; setting this value to {@code false} will disable sessions
071     * to persist Subject state for all Subjects that do not already have a Session.  It should typically only be set
072     * to {@code false} for 100% stateless applications (e.g. when sessions aren't used or when remote clients
073     * authenticate on every request).
074     *
075     * @return {@code true} if any Subject's {@code Session} may be used to persist that {@code Subject}'s state,
076     *         {@code false} otherwise.
077     */
078    public boolean isSessionStorageEnabled() {
079        return sessionStorageEnabled;
080    }
081
082    /**
083     * Sets if any Subject's {@code Session} may be used to persist that {@code Subject}'s state.  The
084     * default value is {@code true}.
085     * <p/>
086     * <b>N.B.</b> This is a global configuration setting; setting this value to {@code false} will disable sessions
087     * to persist Subject state for all Subjects that do not already have a Session.  It should typically only be set
088     * to {@code false} for 100% stateless applications (e.g. when sessions aren't used or when remote clients
089     * authenticate on every request).
090     *
091     * @param sessionStorageEnabled if any Subject's {@code Session} may be used to persist that {@code Subject}'s state.
092     */
093    public void setSessionStorageEnabled(boolean sessionStorageEnabled) {
094        this.sessionStorageEnabled = sessionStorageEnabled;
095    }
096}