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.mgt;
020    
021    import 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     */
030    public 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    }