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.subject;
020
021import org.apache.shiro.authc.AuthenticationInfo;
022import org.apache.shiro.authc.AuthenticationToken;
023import org.apache.shiro.mgt.SecurityManager;
024import org.apache.shiro.session.Session;
025
026import java.io.Serializable;
027import java.util.Map;
028
029/**
030 * A {@code SubjectContext} is a 'bucket' of data presented to a {@link SecurityManager} which interprets
031 * this data to construct {@link org.apache.shiro.subject.Subject Subject} instances.  It is essentially a Map of data
032 * with a few additional type-safe methods for easy retrieval of objects commonly used to construct Subject instances.
033 * <p/>
034 * While this interface contains type-safe setters and getters for common data types, the map can contain anything
035 * additional that might be needed by the {@link SecurityManager} or
036 * {@link org.apache.shiro.mgt.SubjectFactory SubjectFactory} implementation to construct {@code Subject} instances.
037 * <h2>Data Resolution</h2>
038 * The {@link SubjectContext} interface also allows for heuristic resolution of data used to construct a subject
039 * instance.  That is, if an attribute has not been explicitly provided via a setter method, the {@code resolve*}
040 * methods can use heuristics to obtain that data in another way from other attributes.
041 * <p/>
042 * For example, if one calls {@link #getPrincipals()} and no principals are returned, perhaps the principals exist
043 * in the {@link #getSession() session} or another attribute in the context.  The {@link #resolvePrincipals()} will know
044 * how to resolve the principals based on heuristics.  If the {@code resolve*} methods return {@code null} then the
045 * data could not be achieved by any heuristics and must be considered as not available in the context.
046 * <p/>
047 * The general idea is that the normal getters can be called to see if the value was explicitly set.  The
048 * {@code resolve*} methods should be used when actually constructing the {@code Subject} instance to ensure the most
049 * specific/accurate data can be used.
050 * <p/>
051 * <b>USAGE</b>: Most Shiro end-users will never use a {@code SubjectContext} instance directly and instead will use a
052 * {@link Subject.Builder} (which internally uses a {@code SubjectContext}) and build {@code Subject} instances that
053 * way.
054 *
055 * @see org.apache.shiro.mgt.SecurityManager#createSubject SecurityManager.createSubject
056 * @see org.apache.shiro.mgt.SubjectFactory SubjectFactory
057 * @since 1.0
058 */
059public interface SubjectContext extends Map<String, Object> {
060
061    /**
062     * Returns the SecurityManager instance that should be used to back the constructed {@link Subject} instance or
063     * {@code null} if one has not yet been provided to this context.
064     *
065     * @return the SecurityManager instance that should be used to back the constructed {@link Subject} instance or
066     * {@code null} if one has not yet been provided to this context.
067     */
068    SecurityManager getSecurityManager();
069
070    /**
071     * Sets the SecurityManager instance that should be used to back the constructed {@link Subject} instance
072     * (typically used to support {@link org.apache.shiro.subject.support.DelegatingSubject DelegatingSubject} implementations).
073     *
074     * @param securityManager the SecurityManager instance that should be used to back the constructed {@link Subject}
075     *                        instance.
076     */
077    void setSecurityManager(SecurityManager securityManager);
078
079    /**
080     * Resolves the {@code SecurityManager} instance that should be used to back the constructed {@link Subject}
081     * instance (typically used to support
082     * {@link org.apache.shiro.subject.support.DelegatingSubject DelegatingSubject} implementations).
083     *
084     * @return the {@code SecurityManager} instance that should be used to back the constructed {@link Subject}
085     * instance
086     */
087    SecurityManager resolveSecurityManager();
088
089    /**
090     * Returns the session id of the session that should be associated with the constructed {@link Subject} instance.
091     * <p/>
092     * The construction process is expected to resolve the session with the specified id and then construct the Subject
093     * instance based on the resolved session.
094     *
095     * @return the session id of the session that should be associated with the constructed {@link Subject} instance.
096     */
097    Serializable getSessionId();
098
099    /**
100     * Sets the session id of the session that should be associated with the constructed {@link Subject} instance.
101     * <p/>
102     * The construction process is expected to resolve the session with the specified id and then construct the Subject
103     * instance based on the resolved session.
104     *
105     * @param sessionId the session id of the session that should be associated with the constructed {@link Subject}
106     *                  instance.
107     */
108    void setSessionId(Serializable sessionId);
109
110    /**
111     * Returns any existing {@code Subject} that may be in use at the time the new {@code Subject} instance is
112     * being created.
113     * <p/>
114     * This is typically used in the case where the existing {@code Subject} instance returned by
115     * this method is unauthenticated and a new {@code Subject} instance is being created to reflect a successful
116     * authentication - you want to return most of the state of the previous {@code Subject} instance when creating the
117     * newly authenticated instance.
118     *
119     * @return any existing {@code Subject} that may be in use at the time the new {@code Subject} instance is
120     * being created.
121     */
122    Subject getSubject();
123
124    /**
125     * Sets the existing {@code Subject} that may be in use at the time the new {@code Subject} instance is
126     * being created.
127     * <p/>
128     * This is typically used in the case where the existing {@code Subject} instance returned by
129     * this method is unauthenticated and a new {@code Subject} instance is being created to reflect a successful
130     * authentication - you want to return most of the state of the previous {@code Subject} instance when creating the
131     * newly authenticated instance.
132     *
133     * @param subject the existing {@code Subject} that may be in use at the time the new {@code Subject} instance is
134     *                being created.
135     */
136    void setSubject(Subject subject);
137
138    /**
139     * Returns the principals (aka identity) that the constructed {@code Subject} should reflect.
140     *
141     * @return the principals (aka identity) that the constructed {@code Subject} should reflect.
142     */
143    PrincipalCollection getPrincipals();
144
145    PrincipalCollection resolvePrincipals();
146
147    /**
148     * Sets the principals (aka identity) that the constructed {@code Subject} should reflect.
149     *
150     * @param principals the principals (aka identity) that the constructed {@code Subject} should reflect.
151     */
152    void setPrincipals(PrincipalCollection principals);
153
154    /**
155     * Returns the {@code Session} to use when building the {@code Subject} instance.  Note that it is more
156     * common to specify a {@link #setSessionId sessionId} to acquire the desired session rather than having to
157     * construct a {@code Session} to be returned by this method.
158     *
159     * @return the {@code Session} to use when building the {@code Subject} instance.
160     */
161    Session getSession();
162
163    /**
164     * Sets the {@code Session} to use when building the {@code Subject} instance.  Note that it is more
165     * common to specify a {@link #setSessionId sessionId} to automatically resolve the desired session rather than
166     * constructing a {@code Session} to call this method.
167     *
168     * @param session the {@code Session} to use when building the {@code Subject} instance.
169     */
170    void setSession(Session session);
171
172    Session resolveSession();
173
174    /**
175     * Returns {@code true} if the constructed {@code Subject} should be considered authenticated, {@code false}
176     * otherwise.  Be careful setting this value to {@code true} - you should know what you are doing and have a good
177     * reason for ignoring Shiro's default authentication state mechanisms.
178     *
179     * @return {@code true} if the constructed {@code Subject} should be considered authenticated, {@code false}
180     * otherwise.
181     */
182    boolean isAuthenticated();
183
184    /**
185     * Sets whether or not the constructed {@code Subject} instance should be considered as authenticated.  Be careful
186     * when specifying {@code true} - you should know what you are doing and have a good reason for ignoring Shiro's
187     * default authentication state mechanisms.
188     *
189     * @param authc whether or not the constructed {@code Subject} instance should be considered as authenticated.
190     */
191    void setAuthenticated(boolean authc);
192
193    /**
194     * Returns {@code true} if the constructed {@code Subject} should be allowed to create a session, {@code false}
195     * otherwise.  Shiro's configuration defaults to {@code true} as most applications find value in Sessions.
196     *
197     * @return {@code true} if the constructed {@code Subject} should be allowed to create sessions, {@code false}
198     * otherwise.
199     * @since 1.2
200     */
201    boolean isSessionCreationEnabled();
202
203    /**
204     * Sets whether or not the constructed {@code Subject} instance should be allowed to create a session,
205     * {@code false} otherwise.
206     *
207     * @param enabled whether or not the constructed {@code Subject} instance should be allowed to create a session,
208     *                {@code false} otherwise.
209     * @since 1.2
210     */
211    void setSessionCreationEnabled(boolean enabled);
212
213    boolean resolveAuthenticated();
214
215    AuthenticationInfo getAuthenticationInfo();
216
217    void setAuthenticationInfo(AuthenticationInfo info);
218
219    AuthenticationToken getAuthenticationToken();
220
221    void setAuthenticationToken(AuthenticationToken token);
222
223    /**
224     * Returns the host name or IP that should reflect the constructed {@code Subject}'s originating location.
225     *
226     * @return the host name or IP that should reflect the constructed {@code Subject}'s originating location.
227     */
228    String getHost();
229
230    /**
231     * Sets the host name or IP that should reflect the constructed {@code Subject}'s originating location.
232     *
233     * @param host the host name or IP that should reflect the constructed {@code Subject}'s originating location.
234     */
235    void setHost(String host);
236
237    String resolveHost();
238}