/*

  * 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.subject;

 import org.apache.shiro.authc.AuthenticationInfo;

 import org.apache.shiro.authc.AuthenticationToken;

 import org.apache.shiro.mgt.SecurityManager;

 import org.apache.shiro.session.Session;

 import java.io.Serializable;

 import java.util.Map;

 /**

  * A {@code SubjectContext} is a 'bucket' of data presented to a {@link SecurityManager} which interprets

  * this data to construct {@link org.apache.shiro.subject.Subject Subject} 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 {@link SecurityManager} or

  * {@link org.apache.shiro.mgt.SubjectFactory SubjectFactory} implementation to construct {@code Subject} instances.

  * <h2>Data Resolution</h2>

  * The {@link SubjectContext} interface also allows for heuristic resolution of data used to construct a subject

  * instance.  That is, if an attribute has not been explicitly provided via a setter method, the {@code resolve*}

  * methods can use heuristics to obtain that data in another way from other attributes.

  * <p/>

  * For example, if one calls {@link #getPrincipals()} and no principals are returned, perhaps the principals exist

  * in the {@link #getSession() session} or another attribute in the context.  The {@link #resolvePrincipals()} will know

  * how to resolve the principals based on heuristics.  If the {@code resolve*} methods return {@code null} then the

  * data could not be achieved by any heuristics and must be considered as not available in the context.

  * <p/>

  * The general idea is that the normal getters can be called to see if the value was explicitly set.  The

  * {@code resolve*} methods should be used when actually constructing the {@code Subject} instance to ensure the most

  * specific/accurate data can be used.

  * <p/>

  * <b>USAGE</b>: Most Shiro end-users will never use a {@code SubjectContext} instance directly and instead will use a

  * {@link Subject.Builder} (which internally uses a {@code SubjectContext}) and build {@code Subject} instances that

  * way.

  *

  * @see org.apache.shiro.mgt.SecurityManager#createSubject SecurityManager.createSubject

  * @see org.apache.shiro.mgt.SubjectFactory SubjectFactory

  * @since 1.0

  */

 public interface SubjectContext extends Map<String, Object> {

     /**

      * Returns the SecurityManager instance that should be used to back the constructed {@link Subject} instance or

      * {@code null} if one has not yet been provided to this context.

      *

      * @return the SecurityManager instance that should be used to back the constructed {@link Subject} instance or

      *         {@code null} if one has not yet been provided to this context.

      */

     SecurityManager getSecurityManager();

     /**

      * Sets the SecurityManager instance that should be used to back the constructed {@link Subject} instance

      * (typically used to support {@link org.apache.shiro.subject.support.DelegatingSubject DelegatingSubject} implementations).

      *

      * @param securityManager the SecurityManager instance that should be used to back the constructed {@link Subject}

      *                        instance.

      */

     void setSecurityManager(SecurityManager securityManager);

     /**

      * Resolves the {@code SecurityManager} instance that should be used to back the constructed {@link Subject}

      * instance (typically used to support {@link org.apache.shiro.subject.support.DelegatingSubject DelegatingSubject} implementations).

      *

      * @return the {@code SecurityManager} instance that should be used to back the constructed {@link Subject}

      *         instance

      */

     SecurityManager resolveSecurityManager();

     /**

      * Returns the session id of the session that should be associated with the constructed {@link Subject} instance.

      * <p/>

      * The construction process is expected to resolve the session with the specified id and then construct the Subject

      * instance based on the resolved session.

      *

      * @return the session id of the session that should be associated with the constructed {@link Subject} instance.

      */

     Serializable getSessionId();

     /**

      * Sets the session id of the session that should be associated with the constructed {@link Subject} instance.

      * <p/>

      * The construction process is expected to resolve the session with the specified id and then construct the Subject

      * instance based on the resolved session.

      *

      * @param sessionId the session id of the session that should be associated with the constructed {@link Subject}

      *                  instance.

      */

     void setSessionId(Serializable sessionId);

     /**

      * Returns any existing {@code Subject} that may be in use at the time the new {@code Subject} instance is

      * being created.

      * <p/>

      * This is typically used in the case where the existing {@code Subject} instance returned by

      * this method is unauthenticated and a new {@code Subject} instance is being created to reflect a successful

      * authentication - you want to return most of the state of the previous {@code Subject} instance when creating the

      * newly authenticated instance.

      *

      * @return any existing {@code Subject} that may be in use at the time the new {@code Subject} instance is

      *         being created.

      */

     Subject getSubject();

     /**

      * Sets the existing {@code Subject} that may be in use at the time the new {@code Subject} instance is

      * being created.

      * <p/>

      * This is typically used in the case where the existing {@code Subject} instance returned by

      * this method is unauthenticated and a new {@code Subject} instance is being created to reflect a successful

      * authentication - you want to return most of the state of the previous {@code Subject} instance when creating the

      * newly authenticated instance.

      *

      * @param subject the existing {@code Subject} that may be in use at the time the new {@code Subject} instance is

      *                being created.

      */

     void setSubject(Subject subject);

     /**

      * Returns the principals (aka identity) that the constructed {@code Subject} should reflect.

      *

      * @return the principals (aka identity) that the constructed {@code Subject} should reflect.

      */

     PrincipalCollection getPrincipals();

     PrincipalCollection resolvePrincipals();

     /**

      * Sets the principals (aka identity) that the constructed {@code Subject} should reflect.

      *

      * @param principals the principals (aka identity) that the constructed {@code Subject} should reflect.

      */

     void setPrincipals(PrincipalCollection principals);

     /**

      * Returns the {@code Session} to use when building the {@code Subject} instance.  Note that it is more

      * common to specify a {@link #setSessionId sessionId} to acquire the desired session rather than having to

      * construct a {@code Session} to be returned by this method.

      *

      * @return the {@code Session} to use when building the {@code Subject} instance.

      */

     Session getSession();

     /**

      * Sets the {@code Session} to use when building the {@code Subject} instance.  Note that it is more

      * common to specify a {@link #setSessionId sessionId} to automatically resolve the desired session rather than

      * constructing a {@code Session} to call this method.

      *

      * @param session the {@code Session} to use when building the {@code Subject} instance.

      */

     void setSession(Session session);

     Session resolveSession();

     /**

      * Returns {@code true} if the constructed {@code Subject} should be considered authenticated, {@code false}

      * otherwise.  Be careful setting this value to {@code true} - you should know what you are doing and have a good

      * reason for ignoring Shiro's default authentication state mechanisms.

      *

      * @return {@code true} if the constructed {@code Subject} should be considered authenticated, {@code false}

      *         otherwise.

      */

     boolean isAuthenticated();

     /**

      * Sets whether or not the constructed {@code Subject} instance should be considered as authenticated.  Be careful

      * when specifying {@code true} - you should know what you are doing and have a good reason for ignoring Shiro's

      * default authentication state mechanisms.

      *

      * @param authc whether or not the constructed {@code Subject} instance should be considered as authenticated.

      */

     void setAuthenticated(boolean authc);

     /**

      * Returns {@code true} if the constructed {@code Subject} should be allowed to create a session, {@code false}

      * otherwise.  Shiro's configuration defaults to {@code true} as most applications find value in Sessions.

      *

      * @return {@code true} if the constructed {@code Subject} should be allowed to create sessions, {@code false}

      * otherwise.

      * @since 1.2

      */

     boolean isSessionCreationEnabled();

     /**

      * Sets whether or not the constructed {@code Subject} instance should be allowed to create a session,

      * {@code false} otherwise.

      *

      * @param enabled whether or not the constructed {@code Subject} instance should be allowed to create a session,

      * {@code false} otherwise.

      * @since 1.2

      */

     void setSessionCreationEnabled(boolean enabled);

     boolean resolveAuthenticated();

     AuthenticationInfo getAuthenticationInfo();

     void setAuthenticationInfo(AuthenticationInfo info);

     AuthenticationToken getAuthenticationToken();

     void setAuthenticationToken(AuthenticationToken token);

     /**

      * Returns the host name or IP that should reflect the constructed {@code Subject}'s originating location.

      *

      * @return the host name or IP that should reflect the constructed {@code Subject}'s originating location.

      */

     String getHost();

     /**

      * Sets the host name or IP that should reflect the constructed {@code Subject}'s originating location.

      *

      * @param host the host name or IP that should reflect the constructed {@code Subject}'s originating location.

      */

     void setHost(String host);

     String resolveHost();

 }