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.subject;
020    
021    import org.apache.shiro.authc.AuthenticationInfo;
022    import org.apache.shiro.authc.AuthenticationToken;
023    import org.apache.shiro.mgt.SecurityManager;
024    import org.apache.shiro.session.Session;
025    
026    import java.io.Serializable;
027    import 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     */
059    public 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 {@link org.apache.shiro.subject.support.DelegatingSubject DelegatingSubject} implementations).
082         *
083         * @return the {@code SecurityManager} instance that should be used to back the constructed {@link Subject}
084         *         instance
085         */
086        SecurityManager resolveSecurityManager();
087    
088        /**
089         * Returns the session id of the session that should be associated with the constructed {@link Subject} instance.
090         * <p/>
091         * The construction process is expected to resolve the session with the specified id and then construct the Subject
092         * instance based on the resolved session.
093         *
094         * @return the session id of the session that should be associated with the constructed {@link Subject} instance.
095         */
096        Serializable getSessionId();
097    
098        /**
099         * Sets the session id of the session that should be associated with the constructed {@link Subject} instance.
100         * <p/>
101         * The construction process is expected to resolve the session with the specified id and then construct the Subject
102         * instance based on the resolved session.
103         *
104         * @param sessionId the session id of the session that should be associated with the constructed {@link Subject}
105         *                  instance.
106         */
107        void setSessionId(Serializable sessionId);
108    
109        /**
110         * Returns any existing {@code Subject} that may be in use at the time the new {@code Subject} instance is
111         * being created.
112         * <p/>
113         * This is typically used in the case where the existing {@code Subject} instance returned by
114         * this method is unauthenticated and a new {@code Subject} instance is being created to reflect a successful
115         * authentication - you want to return most of the state of the previous {@code Subject} instance when creating the
116         * newly authenticated instance.
117         *
118         * @return any existing {@code Subject} that may be in use at the time the new {@code Subject} instance is
119         *         being created.
120         */
121        Subject getSubject();
122    
123        /**
124         * Sets the existing {@code Subject} that may be in use at the time the new {@code Subject} instance is
125         * being created.
126         * <p/>
127         * This is typically used in the case where the existing {@code Subject} instance returned by
128         * this method is unauthenticated and a new {@code Subject} instance is being created to reflect a successful
129         * authentication - you want to return most of the state of the previous {@code Subject} instance when creating the
130         * newly authenticated instance.
131         *
132         * @param subject the existing {@code Subject} that may be in use at the time the new {@code Subject} instance is
133         *                being created.
134         */
135        void setSubject(Subject subject);
136    
137        /**
138         * Returns the principals (aka identity) that the constructed {@code Subject} should reflect.
139         *
140         * @return the principals (aka identity) that the constructed {@code Subject} should reflect.
141         */
142        PrincipalCollection getPrincipals();
143    
144        PrincipalCollection resolvePrincipals();
145    
146        /**
147         * Sets the principals (aka identity) that the constructed {@code Subject} should reflect.
148         *
149         * @param principals the principals (aka identity) that the constructed {@code Subject} should reflect.
150         */
151        void setPrincipals(PrincipalCollection principals);
152    
153        /**
154         * Returns the {@code Session} to use when building the {@code Subject} instance.  Note that it is more
155         * common to specify a {@link #setSessionId sessionId} to acquire the desired session rather than having to
156         * construct a {@code Session} to be returned by this method.
157         *
158         * @return the {@code Session} to use when building the {@code Subject} instance.
159         */
160        Session getSession();
161    
162        /**
163         * Sets the {@code Session} to use when building the {@code Subject} instance.  Note that it is more
164         * common to specify a {@link #setSessionId sessionId} to automatically resolve the desired session rather than
165         * constructing a {@code Session} to call this method.
166         *
167         * @param session the {@code Session} to use when building the {@code Subject} instance.
168         */
169        void setSession(Session session);
170    
171        Session resolveSession();
172    
173        /**
174         * Returns {@code true} if the constructed {@code Subject} should be considered authenticated, {@code false}
175         * otherwise.  Be careful setting this value to {@code true} - you should know what you are doing and have a good
176         * reason for ignoring Shiro's default authentication state mechanisms.
177         *
178         * @return {@code true} if the constructed {@code Subject} should be considered authenticated, {@code false}
179         *         otherwise.
180         */
181        boolean isAuthenticated();
182    
183        /**
184         * Sets whether or not the constructed {@code Subject} instance should be considered as authenticated.  Be careful
185         * when specifying {@code true} - you should know what you are doing and have a good reason for ignoring Shiro's
186         * default authentication state mechanisms.
187         *
188         * @param authc whether or not the constructed {@code Subject} instance should be considered as authenticated.
189         */
190        void setAuthenticated(boolean authc);
191    
192        /**
193         * Returns {@code true} if the constructed {@code Subject} should be allowed to create a session, {@code false}
194         * otherwise.  Shiro's configuration defaults to {@code true} as most applications find value in Sessions.
195         *
196         * @return {@code true} if the constructed {@code Subject} should be allowed to create sessions, {@code false}
197         * otherwise.
198         * @since 1.2
199         */
200        boolean isSessionCreationEnabled();
201    
202        /**
203         * Sets whether or not the constructed {@code Subject} instance should be allowed to create a session,
204         * {@code false} otherwise.
205         *
206         * @param enabled whether or not the constructed {@code Subject} instance should be allowed to create a session,
207         * {@code false} otherwise.
208         * @since 1.2
209         */
210        void setSessionCreationEnabled(boolean enabled);
211    
212        boolean resolveAuthenticated();
213    
214        AuthenticationInfo getAuthenticationInfo();
215    
216        void setAuthenticationInfo(AuthenticationInfo info);
217    
218        AuthenticationToken getAuthenticationToken();
219    
220        void setAuthenticationToken(AuthenticationToken token);
221    
222        /**
223         * Returns the host name or IP that should reflect the constructed {@code Subject}'s originating location.
224         *
225         * @return the host name or IP that should reflect the constructed {@code Subject}'s originating location.
226         */
227        String getHost();
228    
229        /**
230         * Sets the host name or IP that should reflect the constructed {@code Subject}'s originating location.
231         *
232         * @param host the host name or IP that should reflect the constructed {@code Subject}'s originating location.
233         */
234        void setHost(String host);
235    
236        String resolveHost();
237    }