1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.apache.shiro.subject;
20
21 import org.apache.shiro.authc.AuthenticationInfo;
22 import org.apache.shiro.authc.AuthenticationToken;
23 import org.apache.shiro.mgt.SecurityManager;
24 import org.apache.shiro.session.Session;
25
26 import java.io.Serializable;
27 import java.util.Map;
28
29 /**
30 * A {@code SubjectContext} is a 'bucket' of data presented to a {@link SecurityManager} which interprets
31 * this data to construct {@link org.apache.shiro.subject.Subject Subject} instances. It is essentially a Map of data
32 * with a few additional type-safe methods for easy retrieval of objects commonly used to construct Subject instances.
33 * <p/>
34 * While this interface contains type-safe setters and getters for common data types, the map can contain anything
35 * additional that might be needed by the {@link SecurityManager} or
36 * {@link org.apache.shiro.mgt.SubjectFactory SubjectFactory} implementation to construct {@code Subject} instances.
37 * <h2>Data Resolution</h2>
38 * The {@link SubjectContext} interface also allows for heuristic resolution of data used to construct a subject
39 * instance. That is, if an attribute has not been explicitly provided via a setter method, the {@code resolve*}
40 * methods can use heuristics to obtain that data in another way from other attributes.
41 * <p/>
42 * For example, if one calls {@link #getPrincipals()} and no principals are returned, perhaps the principals exist
43 * in the {@link #getSession() session} or another attribute in the context. The {@link #resolvePrincipals()} will know
44 * how to resolve the principals based on heuristics. If the {@code resolve*} methods return {@code null} then the
45 * data could not be achieved by any heuristics and must be considered as not available in the context.
46 * <p/>
47 * The general idea is that the normal getters can be called to see if the value was explicitly set. The
48 * {@code resolve*} methods should be used when actually constructing the {@code Subject} instance to ensure the most
49 * specific/accurate data can be used.
50 * <p/>
51 * <b>USAGE</b>: Most Shiro end-users will never use a {@code SubjectContext} instance directly and instead will use a
52 * {@link Subject.Builder} (which internally uses a {@code SubjectContext}) and build {@code Subject} instances that
53 * way.
54 *
55 * @see org.apache.shiro.mgt.SecurityManager#createSubject SecurityManager.createSubject
56 * @see org.apache.shiro.mgt.SubjectFactory SubjectFactory
57 * @since 1.0
58 */
59 public interface SubjectContext extends Map<String, Object> {
60
61 /**
62 * Returns the SecurityManager instance that should be used to back the constructed {@link Subject} instance or
63 * {@code null} if one has not yet been provided to this context.
64 *
65 * @return the SecurityManager instance that should be used to back the constructed {@link Subject} instance or
66 * {@code null} if one has not yet been provided to this context.
67 */
68 SecurityManager getSecurityManager();
69
70 /**
71 * Sets the SecurityManager instance that should be used to back the constructed {@link Subject} instance
72 * (typically used to support {@link org.apache.shiro.subject.support.DelegatingSubject DelegatingSubject} implementations).
73 *
74 * @param securityManager the SecurityManager instance that should be used to back the constructed {@link Subject}
75 * instance.
76 */
77 void setSecurityManager(SecurityManager securityManager);
78
79 /**
80 * Resolves the {@code SecurityManager} instance that should be used to back the constructed {@link Subject}
81 * instance (typically used to support {@link org.apache.shiro.subject.support.DelegatingSubject DelegatingSubject} implementations).
82 *
83 * @return the {@code SecurityManager} instance that should be used to back the constructed {@link Subject}
84 * instance
85 */
86 SecurityManager resolveSecurityManager();
87
88 /**
89 * Returns the session id of the session that should be associated with the constructed {@link Subject} instance.
90 * <p/>
91 * The construction process is expected to resolve the session with the specified id and then construct the Subject
92 * instance based on the resolved session.
93 *
94 * @return the session id of the session that should be associated with the constructed {@link Subject} instance.
95 */
96 Serializable getSessionId();
97
98 /**
99 * 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 }