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.SecurityUtils;
022    import org.apache.shiro.authc.AuthenticationException;
023    import org.apache.shiro.authc.AuthenticationToken;
024    import org.apache.shiro.authz.AuthorizationException;
025    import org.apache.shiro.authz.Permission;
026    import org.apache.shiro.mgt.SecurityManager;
027    import org.apache.shiro.mgt.SubjectFactory;
028    import org.apache.shiro.session.Session;
029    import org.apache.shiro.subject.support.DefaultSubjectContext;
030    import org.apache.shiro.util.CollectionUtils;
031    import org.apache.shiro.util.StringUtils;
032    
033    import java.io.Serializable;
034    import java.util.Collection;
035    import java.util.List;
036    import java.util.concurrent.Callable;
037    
038    /**
039     * A {@code Subject} represents state and security operations for a <em>single</em> application user.
040     * These operations include authentication (login/logout), authorization (access control), and
041     * session access. It is Shiro's primary mechanism for single-user security functionality.
042     * <h3>Acquiring a Subject</h3>
043     * To acquire the currently-executing {@code Subject}, application developers will almost always use
044     * {@code SecurityUtils}:
045     * <pre>
046     * {@link SecurityUtils SecurityUtils}.{@link org.apache.shiro.SecurityUtils#getSubject() getSubject()}</pre>
047     * Almost all security operations should be performed with the {@code Subject} returned from this method.
048     * <h3>Permission methods</h3>
049     * Note that there are many *Permission methods in this interface overloaded to accept String arguments instead of
050     * {@link Permission Permission} instances. They are a convenience allowing the caller to use a String representation of
051     * a {@link Permission Permission} if desired.  The underlying Authorization subsystem implementations will usually
052     * simply convert these String values to {@link Permission Permission} instances and then just call the corresponding
053     * type-safe method.  (Shiro's default implementations do String-to-Permission conversion for these methods using
054     * {@link org.apache.shiro.authz.permission.PermissionResolver PermissionResolver}s.)
055     * <p/>
056     * These overloaded *Permission methods forgo type-saftey for the benefit of convenience and simplicity,
057     * so you should choose which ones to use based on your preferences and needs.
058     *
059     * @since 0.1
060     */
061    public interface Subject {
062    
063        /**
064         * Returns this Subject's application-wide uniquely identifying principal, or {@code null} if this
065         * Subject is anonymous because it doesn't yet have any associated account data (for example,
066         * if they haven't logged in).
067         * <p/>
068         * The term <em>principal</em> is just a fancy security term for any identifying attribute(s) of an application
069         * user, such as a username, or user id, or public key, or anything else you might use in your application to
070         * identify a user.
071         * <h4>Uniqueness</h4>
072         * Although given names and family names (first/last) are technically considered principals as well,
073         * Shiro expects the object returned from this method to be an identifying attribute unique across
074         * your entire application.
075         * <p/>
076         * This implies that things like given names and family names are usually poor
077         * candidates as return values since they are rarely guaranteed to be unique;  Things often used for this value:
078         * <ul>
079         * <li>A {@code long} RDBMS surrogate primary key</li>
080         * <li>An application-unique username</li>
081         * <li>A {@link java.util.UUID UUID}</li>
082         * <li>An LDAP Unique ID</li>
083         * </ul>
084         * or any other similar suitable unique mechanism valuable to your application.
085         * <p/>
086         * Most implementations will simply return
087         * <code>{@link #getPrincipals()}.{@link org.apache.shiro.subject.PrincipalCollection#getPrimaryPrincipal() getPrimaryPrincipal()}</code>
088         *
089         * @return this Subject's application-specific unique identity.
090         * @see org.apache.shiro.subject.PrincipalCollection#getPrimaryPrincipal()
091         */
092        Object getPrincipal();
093    
094        /**
095         * Returns this Subject's principals (identifying attributes) in the form of a {@code PrincipalCollection} or
096         * {@code null} if this Subject is anonymous because it doesn't yet have any associated account data (for example,
097         * if they haven't logged in).
098         * <p/>
099         * The word &quot;principals&quot; is nothing more than a fancy security term for identifying attributes associated
100         * with a Subject, aka, application user.  For example, user id, a surname (family/last name), given (first) name,
101         * social security number, nickname, username, etc, are all examples of a principal.
102         *
103         * @return all of this Subject's principals (identifying attributes).
104         * @see #getPrincipal()
105         * @see org.apache.shiro.subject.PrincipalCollection#getPrimaryPrincipal()
106         */
107        PrincipalCollection getPrincipals();
108    
109        /**
110         * Returns {@code true} if this Subject is permitted to perform an action or access a resource summarized by the
111         * specified permission string.
112         * <p/>
113         * This is an overloaded method for the corresponding type-safe {@link Permission Permission} variant.
114         * Please see the class-level JavaDoc for more information on these String-based permission methods.
115         *
116         * @param permission the String representation of a Permission that is being checked.
117         * @return true if this Subject is permitted, false otherwise.
118         * @see #isPermitted(Permission permission)
119         * @since 0.9
120         */
121        boolean isPermitted(String permission);
122    
123        /**
124         * Returns {@code true} if this Subject is permitted to perform an action or access a resource summarized by the
125         * specified permission.
126         * <p/>
127         * More specifically, this method determines if any {@code Permission}s associated
128         * with the subject {@link Permission#implies(Permission) imply} the specified permission.
129         *
130         * @param permission the permission that is being checked.
131         * @return true if this Subject is permitted, false otherwise.
132         */
133        boolean isPermitted(Permission permission);
134    
135        /**
136         * Checks if this Subject implies the given permission strings and returns a boolean array indicating which
137         * permissions are implied.
138         * <p/>
139         * This is an overloaded method for the corresponding type-safe {@link Permission Permission} variant.
140         * Please see the class-level JavaDoc for more information on these String-based permission methods.
141         *
142         * @param permissions the String representations of the Permissions that are being checked.
143         * @return a boolean array where indices correspond to the index of the
144         *         permissions in the given list.  A true value at an index indicates this Subject is permitted for
145         *         for the associated {@code Permission} string in the list.  A false value at an index
146         *         indicates otherwise.
147         * @since 0.9
148         */
149        boolean[] isPermitted(String... permissions);
150    
151        /**
152         * Checks if this Subject implies the given Permissions and returns a boolean array indicating which permissions
153         * are implied.
154         * <p/>
155         * More specifically, this method should determine if each {@code Permission} in
156         * the array is {@link Permission#implies(Permission) implied} by permissions
157         * already associated with the subject.
158         * <p/>
159         * This is primarily a performance-enhancing method to help reduce the number of
160         * {@link #isPermitted} invocations over the wire in client/server systems.
161         *
162         * @param permissions the permissions that are being checked.
163         * @return a boolean array where indices correspond to the index of the
164         *         permissions in the given list.  A true value at an index indicates this Subject is permitted for
165         *         for the associated {@code Permission} object in the list.  A false value at an index
166         *         indicates otherwise.
167         */
168        boolean[] isPermitted(List<Permission> permissions);
169    
170        /**
171         * Returns {@code true} if this Subject implies all of the specified permission strings, {@code false} otherwise.
172         * <p/>
173         * This is an overloaded method for the corresponding type-safe {@link org.apache.shiro.authz.Permission Permission}
174         * variant.  Please see the class-level JavaDoc for more information on these String-based permission methods.
175         *
176         * @param permissions the String representations of the Permissions that are being checked.
177         * @return true if this Subject has all of the specified permissions, false otherwise.
178         * @see #isPermittedAll(Collection)
179         * @since 0.9
180         */
181        boolean isPermittedAll(String... permissions);
182    
183        /**
184         * Returns {@code true} if this Subject implies all of the specified permissions, {@code false} otherwise.
185         * <p/>
186         * More specifically, this method determines if all of the given {@code Permission}s are
187         * {@link Permission#implies(Permission) implied by} permissions already associated with this Subject.
188         *
189         * @param permissions the permissions to check.
190         * @return true if this Subject has all of the specified permissions, false otherwise.
191         */
192        boolean isPermittedAll(Collection<Permission> permissions);
193    
194        /**
195         * Ensures this Subject implies the specified permission String.
196         * <p/>
197         * If this subject's existing associated permissions do not {@link Permission#implies(Permission)} imply}
198         * the given permission, an {@link org.apache.shiro.authz.AuthorizationException} will be thrown.
199         * <p/>
200         * This is an overloaded method for the corresponding type-safe {@link Permission Permission} variant.
201         * Please see the class-level JavaDoc for more information on these String-based permission methods.
202         *
203         * @param permission the String representation of the Permission to check.
204         * @throws org.apache.shiro.authz.AuthorizationException
205         *          if the user does not have the permission.
206         * @since 0.9
207         */
208        void checkPermission(String permission) throws AuthorizationException;
209    
210        /**
211         * Ensures this Subject {@link Permission#implies(Permission) implies} the specified {@code Permission}.
212         * <p/>
213         * If this subject's existing associated permissions do not {@link Permission#implies(Permission) imply}
214         * the given permission, an {@link org.apache.shiro.authz.AuthorizationException} will be thrown.
215         *
216         * @param permission the Permission to check.
217         * @throws org.apache.shiro.authz.AuthorizationException
218         *          if this Subject does not have the permission.
219         */
220        void checkPermission(Permission permission) throws AuthorizationException;
221    
222        /**
223         * Ensures this Subject
224         * {@link org.apache.shiro.authz.Permission#implies(org.apache.shiro.authz.Permission) implies} all of the
225         * specified permission strings.
226         * <p/>
227         * If this subject's existing associated permissions do not
228         * {@link org.apache.shiro.authz.Permission#implies(org.apache.shiro.authz.Permission) imply} all of the given permissions,
229         * an {@link org.apache.shiro.authz.AuthorizationException} will be thrown.
230         * <p/>
231         * This is an overloaded method for the corresponding type-safe {@link Permission Permission} variant.
232         * Please see the class-level JavaDoc for more information on these String-based permission methods.
233         *
234         * @param permissions the string representations of Permissions to check.
235         * @throws AuthorizationException if this Subject does not have all of the given permissions.
236         * @since 0.9
237         */
238        void checkPermissions(String... permissions) throws AuthorizationException;
239    
240        /**
241         * Ensures this Subject
242         * {@link org.apache.shiro.authz.Permission#implies(org.apache.shiro.authz.Permission) implies} all of the
243         * specified permission strings.
244         * <p/>
245         * If this subject's existing associated permissions do not
246         * {@link org.apache.shiro.authz.Permission#implies(org.apache.shiro.authz.Permission) imply} all of the given permissions,
247         * an {@link org.apache.shiro.authz.AuthorizationException} will be thrown.
248         *
249         * @param permissions the Permissions to check.
250         * @throws AuthorizationException if this Subject does not have all of the given permissions.
251         */
252        void checkPermissions(Collection<Permission> permissions) throws AuthorizationException;
253    
254        /**
255         * Returns {@code true} if this Subject has the specified role, {@code false} otherwise.
256         *
257         * @param roleIdentifier the application-specific role identifier (usually a role id or role name).
258         * @return {@code true} if this Subject has the specified role, {@code false} otherwise.
259         */
260        boolean hasRole(String roleIdentifier);
261    
262        /**
263         * Checks if this Subject has the specified roles, returning a boolean array indicating
264         * which roles are associated.
265         * <p/>
266         * This is primarily a performance-enhancing method to help reduce the number of
267         * {@link #hasRole} invocations over the wire in client/server systems.
268         *
269         * @param roleIdentifiers the application-specific role identifiers to check (usually role ids or role names).
270         * @return a boolean array where indices correspond to the index of the
271         *         roles in the given identifiers.  A true value indicates this Subject has the
272         *         role at that index.  False indicates this Subject does not have the role at that index.
273         */
274        boolean[] hasRoles(List<String> roleIdentifiers);
275    
276        /**
277         * Returns {@code true} if this Subject has all of the specified roles, {@code false} otherwise.
278         *
279         * @param roleIdentifiers the application-specific role identifiers to check (usually role ids or role names).
280         * @return true if this Subject has all the roles, false otherwise.
281         */
282        boolean hasAllRoles(Collection<String> roleIdentifiers);
283    
284        /**
285         * Asserts this Subject has the specified role by returning quietly if they do or throwing an
286         * {@link org.apache.shiro.authz.AuthorizationException} if they do not.
287         *
288         * @param roleIdentifier the application-specific role identifier (usually a role id or role name ).
289         * @throws org.apache.shiro.authz.AuthorizationException
290         *          if this Subject does not have the role.
291         */
292        void checkRole(String roleIdentifier) throws AuthorizationException;
293    
294        /**
295         * Asserts this Subject has all of the specified roles by returning quietly if they do or throwing an
296         * {@link org.apache.shiro.authz.AuthorizationException} if they do not.
297         *
298         * @param roleIdentifiers the application-specific role identifiers to check (usually role ids or role names).
299         * @throws org.apache.shiro.authz.AuthorizationException
300         *          if this Subject does not have all of the specified roles.
301         */
302        void checkRoles(Collection<String> roleIdentifiers) throws AuthorizationException;
303    
304        /**
305         * Same as {@link #checkRoles(Collection<String> roleIdentifiers) checkRoles(Collection<String> roleIdentifiers)} but
306         * doesn't require a collection as a an argument.
307         * Asserts this Subject has all of the specified roles by returning quietly if they do or throwing an
308         * {@link org.apache.shiro.authz.AuthorizationException} if they do not.
309         *
310         * @param roleIdentifiers roleIdentifiers the application-specific role identifiers to check (usually role ids or role names).
311         * @throws AuthorizationException org.apache.shiro.authz.AuthorizationException
312         *          if this Subject does not have all of the specified roles.
313         * @since 1.1.0
314         */
315        void checkRoles(String... roleIdentifiers) throws AuthorizationException;
316    
317        /**
318         * Performs a login attempt for this Subject/user.  If unsuccessful,
319         * an {@link AuthenticationException} is thrown, the subclass of which identifies why the attempt failed.
320         * If successful, the account data associated with the submitted principals/credentials will be
321         * associated with this {@code Subject} and the method will return quietly.
322         * <p/>
323         * Upon returning quietly, this {@code Subject} instance can be considered
324         * authenticated and {@link #getPrincipal() getPrincipal()} will be non-null and
325         * {@link #isAuthenticated() isAuthenticated()} will be {@code true}.
326         *
327         * @param token the token encapsulating the subject's principals and credentials to be passed to the
328         *              Authentication subsystem for verification.
329         * @throws org.apache.shiro.authc.AuthenticationException
330         *          if the authentication attempt fails.
331         * @since 0.9
332         */
333        void login(AuthenticationToken token) throws AuthenticationException;
334    
335        /**
336         * Returns {@code true} if this Subject/user proved their identity <em>during their current session</em>
337         * by providing valid credentials matching those known to the system, {@code false} otherwise.
338         * <p/>
339         * Note that even if this Subject's identity has been remembered via 'remember me' services, this method will
340         * still return {@code false} unless the user has actually logged in with proper credentials <em>during their
341         * current session</em>.  See the {@link #isRemembered() isRemembered()} method JavaDoc for more.
342         *
343         * @return {@code true} if this Subject proved their identity during their current session
344         *         by providing valid credentials matching those known to the system, {@code false} otherwise.
345         * @since 0.9
346         */
347        boolean isAuthenticated();
348    
349    
350        /**
351         * Returns {@code true} if this {@code Subject} has an identity (it is not anonymous) and the identity
352         * (aka {@link #getPrincipals() principals}) is remembered from a successful authentication during a previous
353         * session.
354         * <p/>
355         * Although the underlying implementation determines exactly how this method functions, most implementations have
356         * this method act as the logical equivalent to this code:
357         * <pre>
358         * {@link #getPrincipal() getPrincipal()} != null && !{@link #isAuthenticated() isAuthenticated()}</pre>
359         * <p/>
360         * Note as indicated by the above code example, if a {@code Subject} is remembered, they are
361         * <em>NOT</em> considered authenticated.  A check against {@link #isAuthenticated() isAuthenticated()} is a more
362         * strict check than that reflected by this method.  For example, a check to see if a subject can access financial
363         * information should almost always depend on {@link #isAuthenticated() isAuthenticated()} to <em>guarantee</em> a
364         * verified identity, and not this method.
365         * <p/>
366         * Once the subject is authenticated, they are no longer considered only remembered because their identity would
367         * have been verified during the current session.
368         * <h4>Remembered vs Authenticated</h4>
369         * Authentication is the process of <em>proving</em> you are who you say you are.  When a user is only remembered,
370         * the remembered identity gives the system an idea who that user probably is, but in reality, has no way of
371         * absolutely <em>guaranteeing</em> if the remembered {@code Subject} represents the user currently
372         * using the application.
373         * <p/>
374         * So although many parts of the application can still perform user-specific logic based on the remembered
375         * {@link #getPrincipals() principals}, such as customized views, it should never perform highly-sensitive
376         * operations until the user has legitimately verified their identity by executing a successful authentication
377         * attempt.
378         * <p/>
379         * We see this paradigm all over the web, and we will use <a href="http://www.amazon.com">Amazon.com</a> as an
380         * example:
381         * <p/>
382         * When you visit Amazon.com and perform a login and ask it to 'remember me', it will set a cookie with your
383         * identity.  If you don't log out and your session expires, and you come back, say the next day, Amazon still knows
384         * who you <em>probably</em> are: you still see all of your book and movie recommendations and similar user-specific
385         * features since these are based on your (remembered) user id.
386         * <p/>
387         * BUT, if you try to do something sensitive, such as access your account's billing data, Amazon forces you
388         * to do an actual log-in, requiring your username and password.
389         * <p/>
390         * This is because although amazon.com assumed your identity from 'remember me', it recognized that you were not
391         * actually authenticated.  The only way to really guarantee you are who you say you are, and therefore allow you
392         * access to sensitive account data, is to force you to perform an actual successful authentication.  You can
393         * check this guarantee via the {@link #isAuthenticated() isAuthenticated()} method and not via this method.
394         *
395         * @return {@code true} if this {@code Subject}'s identity (aka {@link #getPrincipals() principals}) is
396         *         remembered from a successful authentication during a previous session, {@code false} otherwise.
397         * @since 1.0
398         */
399        boolean isRemembered();
400    
401        /**
402         * Returns the application {@code Session} associated with this Subject.  If no session exists when this
403         * method is called, a new session will be created, associated with this Subject, and then returned.
404         *
405         * @return the application {@code Session} associated with this Subject.
406         * @see #getSession(boolean)
407         * @since 0.2
408         */
409        Session getSession();
410    
411        /**
412         * Returns the application {@code Session} associated with this Subject.  Based on the boolean argument,
413         * this method functions as follows:
414         * <ul>
415         * <li>If there is already an existing session associated with this {@code Subject}, it is returned and
416         * the {@code create} argument is ignored.</li>
417         * <li>If no session exists and {@code create} is {@code true}, a new session will be created, associated with
418         * this {@code Subject} and then returned.</li>
419         * <li>If no session exists and {@code create} is {@code false}, {@code null} is returned.</li>
420         * </ul>
421         *
422         * @param create boolean argument determining if a new session should be created or not if there is no existing session.
423         * @return the application {@code Session} associated with this {@code Subject} or {@code null} based
424         *         on the above described logic.
425         * @since 0.2
426         */
427        Session getSession(boolean create);
428    
429        /**
430         * Logs out this Subject and invalidates and/or removes any associated entities,
431         * such as a {@link Session Session} and authorization data.  After this method is called, the Subject is
432         * considered 'anonymous' and may continue to be used for another log-in if desired.
433         * <h3>Web Environment Warning</h3>
434         * Calling this method in web environments will usually remove any associated session cookie as part of
435         * session invalidation.  Because cookies are part of the HTTP header, and headers can only be set before the
436         * response body (html, image, etc) is sent, this method in web environments must be called before <em>any</em>
437         * content has been rendered.
438         * <p/>
439         * The typical approach most applications use in this scenario is to redirect the user to a different
440         * location (e.g. home page) immediately after calling this method.  This is an effect of the HTTP protocol
441         * itself and not a reflection of Shiro's implementation.
442         * <p/>
443         * Non-HTTP environments may of course use a logged-out subject for login again if desired.
444         */
445        void logout();
446    
447        /**
448         * Associates the specified {@code Callable} with this {@code Subject} instance and then executes it on the
449         * currently running thread.  If you want to execute the {@code Callable} on a different thread, it is better to
450         * use the {@link #associateWith(Callable)} method instead.
451         *
452         * @param callable the Callable to associate with this subject and then execute.
453         * @param <V>      the type of return value the {@code Callable} will return
454         * @return the resulting object returned by the {@code Callable}'s execution.
455         * @throws ExecutionException if the {@code Callable}'s {@link Callable#call call} method throws an exception.
456         * @since 1.0
457         */
458        <V> V execute(Callable<V> callable) throws ExecutionException;
459    
460        /**
461         * Associates the specified {@code Runnable} with this {@code Subject} instance and then executes it on the
462         * currently running thread.  If you want to execute the {@code Runnable} on a different thread, it is better to
463         * use the {@link #associateWith(Runnable)} method instead.
464         * <p/>
465         * <b>Note</b>: This method is primarily provided to execute existing/legacy Runnable implementations.  It is better
466         * for new code to use {@link #execute(Callable)} since that supports the ability to return values and catch
467         * exceptions.
468         *
469         * @param runnable the {@code Runnable} to associate with this {@code Subject} and then execute.
470         * @since 1.0
471         */
472        void execute(Runnable runnable);
473    
474        /**
475         * Returns a {@code Callable} instance matching the given argument while additionally ensuring that it will
476         * retain and execute under this Subject's identity.  The returned object can be used with an
477         * {@link java.util.concurrent.ExecutorService ExecutorService} to execute as this Subject.
478         * <p/>
479         * This will effectively ensure that any calls to
480         * {@code SecurityUtils}.{@link SecurityUtils#getSubject() getSubject()} and related functionality will continue
481         * to function properly on any thread that executes the returned {@code Callable} instance.
482         *
483         * @param callable the callable to execute as this {@code Subject}
484         * @param <V>      the {@code Callable}s return value type
485         * @return a {@code Callable} that can be run as this {@code Subject}.
486         * @since 1.0
487         */
488        <V> Callable<V> associateWith(Callable<V> callable);
489    
490        /**
491         * Returns a {@code Runnable} instance matching the given argument while additionally ensuring that it will
492         * retain and execute under this Subject's identity.  The returned object can be used with an
493         * {@link java.util.concurrent.Executor Executor} or another thread to execute as this Subject.
494         * <p/>
495         * This will effectively ensure that any calls to
496         * {@code SecurityUtils}.{@link SecurityUtils#getSubject() getSubject()} and related functionality will continue
497         * to function properly on any thread that executes the returned {@code Runnable} instance.
498         * <p/>
499         * *Note that if you need a return value to be returned as a result of the runnable's execution or if you need to
500         * react to any Exceptions, it is highly recommended to use the
501         * {@link #associateWith(java.util.concurrent.Callable) createCallable} method instead of this one.
502         *
503         * @param runnable the runnable to execute as this {@code Subject}
504         * @return a {@code Runnable} that can be run as this {@code Subject} on another thread.
505         * @see #associateWith (java.util.concurrent.Callable)
506         * @since 1.0
507         */
508        Runnable associateWith(Runnable runnable);
509    
510        /**
511         * Allows this subject to 'run as' or 'assume' another identity indefinitely.  This can only be
512         * called when the {@code Subject} instance already has an identity (i.e. they are remembered from a previous
513         * log-in or they have authenticated during their current session).
514         * <p/>
515         * Some notes about {@code runAs}:
516         * <ul>
517         * <li>You can tell if a {@code Subject} is 'running as' another identity by calling the
518         * {@link #isRunAs() isRunAs()} method.</li>
519         * <li>If running as another identity, you can determine what the previous 'pre run as' identity
520         * was by calling the {@link #getPreviousPrincipals() getPreviousPrincipals()} method.</li>
521         * <li>When you want a {@code Subject} to stop running as another identity, you can return to its previous
522         * 'pre run as' identity by calling the {@link #releaseRunAs() releaseRunAs()} method.</li>
523         * </ul>
524         *
525         * @param principals the identity to 'run as', aka the identity to <em>assume</em> indefinitely.
526         * @throws NullPointerException  if the specified principals collection is {@code null} or empty.
527         * @throws IllegalStateException if this {@code Subject} does not yet have an identity of its own.
528         * @since 1.0
529         */
530        void runAs(PrincipalCollection principals) throws NullPointerException, IllegalStateException;
531    
532        /**
533         * Returns {@code true} if this {@code Subject} is 'running as' another identity other than its original one or
534         * {@code false} otherwise (normal {@code Subject} state).  See the {@link #runAs runAs} method for more
535         * information.
536         *
537         * @return {@code true} if this {@code Subject} is 'running as' another identity other than its original one or
538         *         {@code false} otherwise (normal {@code Subject} state).
539         * @see #runAs
540         * @since 1.0
541         */
542        boolean isRunAs();
543    
544        /**
545         * Returns the previous 'pre run as' identity of this {@code Subject} before assuming the current
546         * {@link #runAs runAs} identity, or {@code null} if this {@code Subject} is not operating under an assumed
547         * identity (normal state). See the {@link #runAs runAs} method for more information.
548         *
549         * @return the previous 'pre run as' identity of this {@code Subject} before assuming the current
550         *         {@link #runAs runAs} identity, or {@code null} if this {@code Subject} is not operating under an assumed
551         *         identity (normal state).
552         * @see #runAs
553         * @since 1.0
554         */
555        PrincipalCollection getPreviousPrincipals();
556    
557        /**
558         * Releases the current 'run as' (assumed) identity and reverts back to the previous 'pre run as'
559         * identity that existed before {@code #runAs runAs} was called.
560         * <p/>
561         * This method returne 'run as' (assumed) identity being released or {@code null} if this {@code Subject} is not
562         * operating under an assumed identity.
563         *
564         * @return the 'run as' (assumed) identity being released or {@code null} if this {@code Subject} is not operating
565         *         under an assumed identity.
566         * @see #runAs
567         * @since 1.0
568         */
569        PrincipalCollection releaseRunAs();
570    
571        /**
572         * Builder design pattern implementation for creating {@link Subject} instances in a simplified way without
573         * requiring knowledge of Shiro's construction techniques.
574         * <p/>
575         * <b>NOTE</b>: This is provided for framework development support only and should typically never be used by
576         * application developers.  {@code Subject} instances should generally be acquired by using
577         * <code>SecurityUtils.{@link SecurityUtils#getSubject() getSubject()}</code>
578         * <h4>Usage</h4>
579         * The simplest usage of this builder is to construct an anonymous, session-less {@code Subject} instance:
580         * <pre>
581         * Subject subject = new Subject.{@link #Builder() Builder}().{@link #buildSubject() buildSubject()};</pre>
582         * The default, no-arg {@code Subject.Builder()} constructor shown above will use the application's
583         * currently accessible {@code SecurityManager} via
584         * <code>SecurityUtils.{@link SecurityUtils#getSecurityManager() getSecurityManager()}</code>.  You may also
585         * specify the exact {@code SecurityManager} instance to be used by the additional
586         * <code>Subject.{@link #Builder(org.apache.shiro.mgt.SecurityManager) Builder(securityManager)}</code>
587         * constructor if desired.
588         * <p/>
589         * All other methods may be called before the {@link #buildSubject() buildSubject()} method to
590         * provide context on how to construct the {@code Subject} instance.  For example, if you have a session id and
591         * want to acquire the {@code Subject} that 'owns' that session (assuming the session exists and is not expired):
592         * <pre>
593         * Subject subject = new Subject.Builder().sessionId(sessionId).buildSubject();</pre>
594         * <p/>
595         * Similarly, if you want a {@code Subject} instance reflecting a certain identity:
596         * <pre>
597         * PrincipalCollection principals = new SimplePrincipalCollection("username", <em>yourRealmName</em>);
598         * Subject subject = new Subject.Builder().principals(principals).build();</pre>
599         * <p/>
600         * <b>Note*</b> that the returned {@code Subject} instance is <b>not</b> automatically bound to the application (thread)
601         * for further use.  That is,
602         * {@link org.apache.shiro.SecurityUtils SecurityUtils}.{@link org.apache.shiro.SecurityUtils#getSubject() getSubject()}
603         * will not automatically return the same instance as what is returned by the builder.  It is up to the framework
604         * developer to bind the built {@code Subject} for continued use if desired.
605         *
606         * @since 1.0
607         */
608        public static class Builder {
609    
610            /**
611             * Hold all contextual data via the Builder instance's method invocations to be sent to the
612             * {@code SecurityManager} during the {@link #buildSubject} call.
613             */
614            private final SubjectContext subjectContext;
615    
616            /**
617             * The SecurityManager to invoke during the {@link #buildSubject} call.
618             */
619            private final SecurityManager securityManager;
620    
621            /**
622             * Constructs a new {@link Subject.Builder} instance, using the {@code SecurityManager} instance available
623             * to the calling code as determined by a call to {@link org.apache.shiro.SecurityUtils#getSecurityManager()}
624             * to build the {@code Subject} instance.
625             */
626            public Builder() {
627                this(SecurityUtils.getSecurityManager());
628            }
629    
630            /**
631             * Constructs a new {@link Subject.Builder} instance which will use the specified {@code SecurityManager} when
632             * building the {@code Subject} instance.
633             *
634             * @param securityManager the {@code SecurityManager} to use when building the {@code Subject} instance.
635             */
636            public Builder(SecurityManager securityManager) {
637                if (securityManager == null) {
638                    throw new NullPointerException("SecurityManager method argument cannot be null.");
639                }
640                this.securityManager = securityManager;
641                this.subjectContext = newSubjectContextInstance();
642                if (this.subjectContext == null) {
643                    throw new IllegalStateException("Subject instance returned from 'newSubjectContextInstance' " +
644                            "cannot be null.");
645                }
646                this.subjectContext.setSecurityManager(securityManager);
647            }
648    
649            /**
650             * Creates a new {@code SubjectContext} instance to be used to populate with subject contextual data that
651             * will then be sent to the {@code SecurityManager} to create a new {@code Subject} instance.
652             *
653             * @return a new {@code SubjectContext} instance
654             */
655            protected SubjectContext newSubjectContextInstance() {
656                return new DefaultSubjectContext();
657            }
658    
659            /**
660             * Returns the backing context used to build the {@code Subject} instance, available to subclasses
661             * since the {@code context} class attribute is marked as {@code private}.
662             *
663             * @return the backing context used to build the {@code Subject} instance, available to subclasses.
664             */
665            protected SubjectContext getSubjectContext() {
666                return this.subjectContext;
667            }
668    
669            /**
670             * Enables building a {@link Subject Subject} instance that owns the {@link Session Session} with the
671             * specified {@code sessionId}.
672             * <p/>
673             * Usually when specifying a {@code sessionId}, no other {@code Builder} methods would be specified because
674             * everything else (principals, inet address, etc) can usually be reconstructed based on the referenced
675             * session alone.  In other words, this is almost always sufficient:
676             * <pre>
677             * new Subject.Builder().sessionId(sessionId).buildSubject();</pre>
678             * <p/>
679             * <b>Although simple in concept, this method provides very powerful functionality previously absent in almost
680             * all Java environments:</b>
681             * <p/>
682             * The ability to reference a {@code Subject} and their server-side session
683             * <em>across clients of different mediums</em> such as web applications, Java applets,
684             * standalone C# clients over XML-RPC and/or SOAP, and many others. This is a <em>huge</em>
685             * benefit in heterogeneous enterprise applications.
686             * <p/>
687             * To maintain session integrity across client mediums, the {@code sessionId} <b>must</b> be transmitted
688             * to all client mediums securely (e.g. over SSL) to prevent man-in-the-middle attacks.  This
689             * is nothing new - all web applications are susceptible to the same problem when transmitting
690             * {@code Cookie}s or when using URL rewriting.  As long as the
691             * {@code sessionId} is transmitted securely, session integrity can be maintained.
692             *
693             * @param sessionId the id of the session that backs the desired Subject being acquired.
694             * @return this {@code Builder} instance for method chaining.
695             */
696            public Builder sessionId(Serializable sessionId) {
697                if (sessionId != null) {
698                    this.subjectContext.setSessionId(sessionId);
699                }
700                return this;
701            }
702    
703            /**
704             * Ensures the {@code Subject} being built will reflect the specified host name or IP as its originating
705             * location.
706             *
707             * @param host the host name or IP address to use as the {@code Subject}'s originating location.
708             * @return this {@code Builder} instance for method chaining.
709             */
710            public Builder host(String host) {
711                if (StringUtils.hasText(host)) {
712                    this.subjectContext.setHost(host);
713                }
714                return this;
715            }
716    
717            /**
718             * Ensures the {@code Subject} being built will use the specified {@link Session} instance.  Note that it is
719             * more common to use the {@link #sessionId sessionId} builder method rather than having to construct a
720             * {@code Session} instance for this method.
721             *
722             * @param session the session to use as the {@code Subject}'s {@link Session}
723             * @return this {@code Builder} instance for method chaining.
724             */
725            public Builder session(Session session) {
726                if (session != null) {
727                    this.subjectContext.setSession(session);
728                }
729                return this;
730            }
731    
732            /**
733             * Ensures the {@code Subject} being built will reflect the specified principals (aka identity).
734             * <p/>
735             * For example, if your application's unique identifier for users is a {@code String} username, and you wanted
736             * to create a {@code Subject} instance that reflected a user whose username is
737             * '{@code jsmith}', and you knew the Realm that could acquire {@code jsmith}'s principals based on the username
738             * was named &quot;{@code myRealm}&quot;, you might create the '{@code jsmith} {@code Subject} instance this
739             * way:
740             * <pre>
741             * PrincipalCollection identity = new {@link org.apache.shiro.subject.SimplePrincipalCollection#SimplePrincipalCollection(Object, String) SimplePrincipalCollection}(&quot;jsmith&quot;, &quot;myRealm&quot;);
742             * Subject jsmith = new Subject.Builder().principals(identity).buildSubject();</pre>
743             * <p/>
744             * Similarly, if your application's unique identifier for users is a {@code long} value (such as might be used
745             * as a primary key in a relational database) and you were using a {@code JDBC}
746             * {@code Realm} named, (unimaginatively) &quot;jdbcRealm&quot;, you might create the Subject
747             * instance this way:
748             * <pre>
749             * long userId = //get user ID from somewhere
750             * PrincipalCollection userIdentity = new {@link org.apache.shiro.subject.SimplePrincipalCollection#SimplePrincipalCollection(Object, String) SimplePrincipalCollection}(<em>userId</em>, &quot;jdbcRealm&quot;);
751             * Subject user = new Subject.Builder().principals(identity).buildSubject();</pre>
752             *
753             * @param principals the principals to use as the {@code Subject}'s identity.
754             * @return this {@code Builder} instance for method chaining.
755             */
756            public Builder principals(PrincipalCollection principals) {
757                if (!CollectionUtils.isEmpty(principals)) {
758                    this.subjectContext.setPrincipals(principals);
759                }
760                return this;
761            }
762    
763            /**
764             * Configures whether or not the created Subject instance can create a new {@code Session} if one does not
765             * already exist.  If set to {@code false}, any application calls to
766             * {@code subject.getSession()} or {@code subject.getSession(true))} will result in a SessionException.
767             * <p/>
768             * This setting is {@code true} by default, as most applications find value in sessions.
769             *
770             * @param enabled whether or not the created Subject instance can create a new {@code Session} if one does not
771             *                already exist.
772             * @return this {@code Builder} instance for method chaining.
773             * @since 1.2
774             */
775            public Builder sessionCreationEnabled(boolean enabled) {
776                this.subjectContext.setSessionCreationEnabled(enabled);
777                return this;
778            }
779    
780            /**
781             * Ensures the {@code Subject} being built will be considered
782             * {@link org.apache.shiro.subject.Subject#isAuthenticated() authenticated}.  Per the
783             * {@link org.apache.shiro.subject.Subject#isAuthenticated() isAuthenticated()} JavaDoc, be careful
784             * when specifying {@code true} - you should know what you are doing and have a good reason for ignoring Shiro's
785             * default authentication state mechanisms.
786             *
787             * @param authenticated whether or not the built {@code Subject} will be considered authenticated.
788             * @return this {@code Builder} instance for method chaining.
789             * @see org.apache.shiro.subject.Subject#isAuthenticated()
790             */
791            public Builder authenticated(boolean authenticated) {
792                this.subjectContext.setAuthenticated(authenticated);
793                return this;
794            }
795    
796            /**
797             * Allows custom attributes to be added to the underlying context {@code Map} used to construct the
798             * {@link Subject} instance.
799             * <p/>
800             * A {@code null} key throws an {@link IllegalArgumentException}. A {@code null} value effectively removes
801             * any previously stored attribute under the given key from the context map.
802             * <p/>
803             * <b>*NOTE*:</b> This method is only useful when configuring Shiro with a custom {@link SubjectFactory}
804             * implementation.  This method allows end-users to append additional data to the context map which the
805             * {@code SubjectFactory} implementation can use when building custom Subject instances. As such, this method
806             * is only useful when a custom {@code SubjectFactory} implementation has been configured.
807             *
808             * @param attributeKey   the key under which the corresponding value will be stored in the context {@code Map}.
809             * @param attributeValue the value to store in the context map under the specified {@code attributeKey}.
810             * @return this {@code Builder} instance for method chaining.
811             * @throws IllegalArgumentException if the {@code attributeKey} is {@code null}.
812             * @see SubjectFactory#createSubject(SubjectContext)
813             */
814            public Builder contextAttribute(String attributeKey, Object attributeValue) {
815                if (attributeKey == null) {
816                    String msg = "Subject context map key cannot be null.";
817                    throw new IllegalArgumentException(msg);
818                }
819                if (attributeValue == null) {
820                    this.subjectContext.remove(attributeKey);
821                } else {
822                    this.subjectContext.put(attributeKey, attributeValue);
823                }
824                return this;
825            }
826    
827            /**
828             * Creates and returns a new {@code Subject} instance reflecting the cumulative state acquired by the
829             * other methods in this class.
830             * <p/>
831             * This {@code Builder} instance will still retain the underlying state after this method is called - it
832             * will not clear it; repeated calls to this method will return multiple {@link Subject} instances, all
833             * reflecting the exact same state.  If a new (different) {@code Subject} is to be constructed, a new
834             * {@code Builder} instance must be created.
835             * <p/>
836             * <b>Note</b> that the returned {@code Subject} instance is <b>not</b> automatically bound to the application
837             * (thread) for further use.  That is,
838             * {@link org.apache.shiro.SecurityUtils SecurityUtils}.{@link org.apache.shiro.SecurityUtils#getSubject() getSubject()}
839             * will not automatically return the same instance as what is returned by the builder.  It is up to the
840             * framework developer to bind the returned {@code Subject} for continued use if desired.
841             *
842             * @return a new {@code Subject} instance reflecting the cumulative state acquired by the
843             *         other methods in this class.
844             */
845            public Subject buildSubject() {
846                return this.securityManager.createSubject(this.subjectContext);
847            }
848        }
849    
850    }