View Javadoc

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 }