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.authc.AuthenticationException;
022import org.apache.shiro.authc.AuthenticationInfo;
023import org.apache.shiro.authc.AuthenticationToken;
024import org.apache.shiro.subject.PrincipalCollection;
025import org.apache.shiro.subject.Subject;
026import org.apache.shiro.subject.SubjectContext;
027
028/**
029 * A RememberMeManager is responsible for remembering a Subject's identity across that Subject's sessions with
030 * the application.
031 *
032 * @since 0.9
033 */
034public interface RememberMeManager {
035
036    /**
037     * Based on the specified subject context map being used to build a Subject instance, returns any previously
038     * remembered principals for the subject for automatic identity association (aka 'Remember Me').
039     * <p/>
040     * The context map is usually populated by a {@link Subject.Builder} implementation.
041     * See the {@link SubjectFactory} class constants for Shiro's known map keys.
042     *
043     * @param subjectContext the contextual data, usually provided by a {@link Subject.Builder} implementation, that
044     *                       is being used to construct a {@link Subject} instance.
045     * @return he remembered principals or {@code null} if none could be acquired.
046     * @since 1.0
047     */
048    PrincipalCollection getRememberedPrincipals(SubjectContext subjectContext);
049
050    /**
051     * Forgets any remembered identity corresponding to the subject context map being used to build a subject instance.
052     * <p/>
053     * The context map is usually populated by a {@link Subject.Builder} implementation.
054     * See the {@link SubjectFactory} class constants for Shiro's known map keys.
055     *
056     * @param subjectContext the contextual data, usually provided by a {@link Subject.Builder} implementation, that
057     *                       is being used to construct a {@link Subject} instance.
058     * @since 1.0
059     */
060    void forgetIdentity(SubjectContext subjectContext);
061
062    /**
063     * Reacts to a successful authentication attempt, typically saving the principals to be retrieved ('remembered')
064     * for future system access.
065     *
066     * @param subject the subject that executed a successful authentication attempt
067     * @param token   the authentication token submitted resulting in a successful authentication attempt
068     * @param info    the authenticationInfo returned as a result of the successful authentication attempt
069     * @since 1.0
070     */
071    void onSuccessfulLogin(Subject subject, AuthenticationToken token, AuthenticationInfo info);
072
073    /**
074     * Reacts to a failed authentication attempt, typically by forgetting any previously remembered principals for the
075     * Subject.
076     *
077     * @param subject the subject that executed the failed authentication attempt
078     * @param token   the authentication token submitted resulting in the failed authentication attempt
079     * @param ae      the authentication exception thrown as a result of the failed authentication attempt
080     * @since 1.0
081     */
082    void onFailedLogin(Subject subject, AuthenticationToken token, AuthenticationException ae);
083
084    /**
085     * Reacts to a Subject logging out of the application, typically by forgetting any previously remembered
086     * principals for the Subject.
087     *
088     * @param subject the subject logging out.
089     * @since 1.0
090     */
091    void onLogout(Subject subject);
092}