All Known Implementing Classes:

DelegatingSubject
```
public interface Subject
```
A Subject represents state and security operations for a single application user. These operations include authentication (login/logout), authorization (access control), and session access. It is Shiro's primary mechanism for single-user security functionality.
Acquiring a Subject
To acquire the currently-executing Subject, application developers will almost always use SecurityUtils:
```
 SecurityUtils.getSubject()
```
Almost all security operations should be performed with the Subject returned from this method.
Permission methods
Note that there are many *Permission methods in this interface overloaded to accept String arguments instead of Permission instances. They are a convenience allowing the caller to use a String representation of a Permission if desired. The underlying Authorization subsystem implementations will usually simply convert these String values to Permission instances and then just call the corresponding type-safe method. (Shiro's default implementations do String-to-Permission conversion for these methods using PermissionResolvers.)
These overloaded *Permission methods forgo type-safety for the benefit of convenience and simplicity, so you should choose which ones to use based on your preferences and needs.
Since:

0.1

Nested Class Summary

Nested Classes
Modifier and Type	Interface	Description
`static class`	`Subject.Builder`	Builder design pattern implementation for creating `Subject` instances in a simplified way without requiring knowledge of Shiro's construction techniques.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method	Description
	`runnable)`	Returns a `Runnable` instance matching the given argument while additionally ensuring that it will retain and execute under this Subject's identity.
`<V> <V>`	`<V> callable)`	Returns a `Callable` instance matching the given argument while additionally ensuring that it will retain and execute under this Subject's identity.
`void`	`permission)`	Ensures this Subject implies the specified permission String.
`void`	`checkPermission(Permission permission)`	Ensures this Subject `implies` the specified `Permission`.
`void`	`... permissions)`	Ensures this Subject `implies` all of the specified permission strings.
`void`	`<Permission> permissions)`	Ensures this Subject `implies` all of the specified permission strings.
`void`	`roleIdentifier)`	Asserts this Subject has the specified role by returning quietly if they do or throwing an `AuthorizationException` if they do not.
`void`	`... roleIdentifiers)`	Same as `checkRoles(CollectionroleIdentifiers)` but doesn't require a collection as a an argument.
`void`	`<> roleIdentifiers)`	Asserts this Subject has all of the specified roles by returning quietly if they do or throwing an `AuthorizationException` if they do not.
`void`	`runnable)`	Associates the specified `Runnable` with this `Subject` instance and then executes it on the currently running thread.
`<V> V`	`<V> callable)`	Associates the specified `Callable` with this `Subject` instance and then executes it on the currently running thread.
`PrincipalCollection`	`getPreviousPrincipals()`	Returns the previous 'pre run as' identity of this `Subject` before assuming the current `runAs` identity, or `null` if this `Subject` is not operating under an assumed identity (normal state).
	`getPrincipal()`	Returns this Subject's application-wide uniquely identifying principal, or `null` if this Subject is anonymous because it doesn't yet have any associated account data (for example, if they haven't logged in).
`PrincipalCollection`	`getPrincipals()`	Returns this Subject's principals (identifying attributes) in the form of a `PrincipalCollection` or `null` if this Subject is anonymous because it doesn't yet have any associated account data (for example, if they haven't logged in).
`Session`	`getSession()`	Returns the application `Session` associated with this Subject.
`Session`	`getSession(boolean create)`	Returns the application `Session` associated with this Subject.
`boolean`	`<> roleIdentifiers)`	Returns `true` if this Subject has all of the specified roles, `false` otherwise.
`boolean`	`roleIdentifier)`	Returns `true` if this Subject has the specified role, `false` otherwise.
`boolean[]`	`<> roleIdentifiers)`	Checks if this Subject has the specified roles, returning a boolean array indicating which roles are associated.
`boolean`	`isAuthenticated()`	Returns `true` if this Subject/user proved their identity during their current session by providing valid credentials matching those known to the system, `false` otherwise.
`boolean`	`permission)`	Returns `true` if this Subject is permitted to perform an action or access a resource summarized by the specified permission string.
`boolean[]`	`... permissions)`	Checks if this Subject implies the given permission strings and returns a boolean array indicating which permissions are implied.
`boolean[]`	`<Permission> permissions)`	Checks if this Subject implies the given Permissions and returns a boolean array indicating which permissions are implied.
`boolean`	`isPermitted(Permission permission)`	Returns `true` if this Subject is permitted to perform an action or access a resource summarized by the specified permission.
`boolean`	`... permissions)`	Returns `true` if this Subject implies all of the specified permission strings, `false` otherwise.
`boolean`	`<Permission> permissions)`	Returns `true` if this Subject implies all of the specified permissions, `false` otherwise.
`boolean`	`isRemembered()`	Returns `true` if this `Subject` has an identity (it is not anonymous) and the identity (aka `principals`) is remembered from a successful authentication during a previous session.
`boolean`	`isRunAs()`	Returns `true` if this `Subject` is 'running as' another identity other than its original one or `false` otherwise (normal `Subject` state).
`void`	`login(AuthenticationToken token)`	Performs a login attempt for this Subject/user.
`void`	`logout()`	Logs out this Subject and invalidates and/or removes any associated entities, such as a `Session` and authorization data.
`PrincipalCollection`	`releaseRunAs()`	Releases the current 'run as' (assumed) identity and reverts back to the previous 'pre run as' identity that existed before `#runAs runAs` was called.
`void`	`runAs(PrincipalCollection principals)`	Allows this subject to 'run as' or 'assume' another identity indefinitely.

- Method Detail
  - getPrincipal
```
 getPrincipal()
```
    Returns this Subject's application-wide uniquely identifying principal, or null if this Subject is anonymous because it doesn't yet have any associated account data (for example, if they haven't logged in).
    The term principal is just a fancy security term for any identifying attribute(s) of an application user, such as a username, or user id, or public key, or anything else you might use in your application to identify a user.
    Uniqueness
    Although given names and family names (first/last) are technically considered principals as well, Shiro expects the object returned from this method to be an identifying attribute unique across your entire application.
    This implies that things like given names and family names are usually poor candidates as return values since they are rarely guaranteed to be unique; Things often used for this value:
    
    A long RDBMS surrogate primary key
    
    An application-unique username
    
    A
    
    An LDAP Unique ID
    
    or any other similar suitable unique mechanism valuable to your application.
    Most implementations will simply return getPrincipals().getPrimaryPrincipal()
    Returns:
    
    this Subject's application-specific unique identity.
    
    See Also:
    
    PrincipalCollection.getPrimaryPrincipal()
  - getPrincipals
```
PrincipalCollection getPrincipals()
```
    Returns this Subject's principals (identifying attributes) in the form of a PrincipalCollection or null if this Subject is anonymous because it doesn't yet have any associated account data (for example, if they haven't logged in).
    The word "principals" is nothing more than a fancy security term for identifying attributes associated with a Subject, aka, application user. For example, user id, a surname (family/last name), given (first) name, social security number, nickname, username, etc, are all examples of a principal.
    
    Returns:
    
    all of this Subject's principals (identifying attributes).
    
    See Also:
    
    getPrincipal(), PrincipalCollection.getPrimaryPrincipal()
  - isPermitted
```
boolean isPermitted( permission)
```
    Returns true if this Subject is permitted to perform an action or access a resource summarized by the specified permission string.
    This is an overloaded method for the corresponding type-safe Permission variant. Please see the class-level JavaDoc for more information on these String-based permission methods.
    
    Parameters:
    
    permission - the String representation of a Permission that is being checked.
    
    Returns:
    
    true if this Subject is permitted, false otherwise.
    
    Since:
    
    0.9
    
    See Also:
    
    isPermitted(Permission permission)
  - isPermitted
```
boolean isPermitted(Permission permission)
```
    Returns true if this Subject is permitted to perform an action or access a resource summarized by the specified permission.
    More specifically, this method determines if any Permissions associated with the subject imply the specified permission.
    
    Parameters:
    
    permission - the permission that is being checked.
    
    Returns:
    
    true if this Subject is permitted, false otherwise.
  - isPermitted
```
boolean[] isPermitted(... permissions)
```
    Checks if this Subject implies the given permission strings and returns a boolean array indicating which permissions are implied.
    This is an overloaded method for the corresponding type-safe Permission variant. Please see the class-level JavaDoc for more information on these String-based permission methods.
    
    Parameters:
    
    permissions - the String representations of the Permissions that are being checked.
    
    Returns:
    
    a boolean array where indices correspond to the index of the permissions in the given list. A true value at an index indicates this Subject is permitted for for the associated Permission string in the list. A false value at an index indicates otherwise.
    
    Since:
    
    0.9
  - isPermitted
```
boolean[] isPermitted(<Permission> permissions)
```
    Checks if this Subject implies the given Permissions and returns a boolean array indicating which permissions are implied.
    More specifically, this method should determine if each Permission in the array is implied by permissions already associated with the subject.
    This is primarily a performance-enhancing method to help reduce the number of isPermitted(java.lang.String) invocations over the wire in client/server systems.
    
    Parameters:
    
    permissions - the permissions that are being checked.
    
    Returns:
    
    a boolean array where indices correspond to the index of the permissions in the given list. A true value at an index indicates this Subject is permitted for for the associated Permission object in the list. A false value at an index indicates otherwise.
  - isPermittedAll
```
boolean isPermittedAll(... permissions)
```
    Returns true if this Subject implies all of the specified permission strings, false otherwise.
    This is an overloaded method for the corresponding type-safe Permission variant. Please see the class-level JavaDoc for more information on these String-based permission methods.
    
    Parameters:
    
    permissions - the String representations of the Permissions that are being checked.
    
    Returns:
    
    true if this Subject has all of the specified permissions, false otherwise.
    
    Since:
    
    0.9
    
    See Also:
    
    isPermittedAll(Collection)
  - isPermittedAll
```
boolean isPermittedAll(<Permission> permissions)
```
    Returns true if this Subject implies all of the specified permissions, false otherwise.
    More specifically, this method determines if all of the given Permissions are implied by permissions already associated with this Subject.
    
    Parameters:
    
    permissions - the permissions to check.
    
    Returns:
    
    true if this Subject has all of the specified permissions, false otherwise.
  - checkPermission
```
void checkPermission( permission)
              throws AuthorizationException
```
    Ensures this Subject implies the specified permission String.
    If this subject's existing associated permissions do not Permission.implies(Permission) imply} the given permission, an AuthorizationException will be thrown.
    This is an overloaded method for the corresponding type-safe Permission variant. Please see the class-level JavaDoc for more information on these String-based permission methods.
    
    Parameters:
    
    permission - the String representation of the Permission to check.
    
    Throws:
    
    AuthorizationException - if the user does not have the permission.
    
    Since:
    
    0.9
  - checkPermission
```
void checkPermission(Permission permission)
              throws AuthorizationException
```
    Ensures this Subject implies the specified Permission.
    If this subject's existing associated permissions do not imply the given permission, an AuthorizationException will be thrown.
    
    Parameters:
    
    permission - the Permission to check.
    
    Throws:
    
    AuthorizationException - if this Subject does not have the permission.
  - checkPermissions
```
void checkPermissions(... permissions)
               throws AuthorizationException
```
    Ensures this Subject implies all of the specified permission strings.
    If this subject's existing associated permissions do not imply all of the given permissions, an AuthorizationException will be thrown.
    This is an overloaded method for the corresponding type-safe Permission variant. Please see the class-level JavaDoc for more information on these String-based permission methods.
    
    Parameters:
    
    permissions - the string representations of Permissions to check.
    
    Throws:
    
    AuthorizationException - if this Subject does not have all of the given permissions.
    
    Since:
    
    0.9
  - checkPermissions
```
void checkPermissions(<Permission> permissions)
               throws AuthorizationException
```
    Ensures this Subject implies all of the specified permission strings.
    If this subject's existing associated permissions do not imply all of the given permissions, an AuthorizationException will be thrown.
    
    Parameters:
    
    permissions - the Permissions to check.
    
    Throws:
    
    AuthorizationException - if this Subject does not have all of the given permissions.
  - hasRole
```
boolean hasRole( roleIdentifier)
```
    Returns true if this Subject has the specified role, false otherwise.
    
    Parameters:
    
    roleIdentifier - the application-specific role identifier (usually a role id or role name).
    
    Returns:
    
    true if this Subject has the specified role, false otherwise.
  - hasRoles
```
boolean[] hasRoles(<> roleIdentifiers)
```
    Checks if this Subject has the specified roles, returning a boolean array indicating which roles are associated.
    This is primarily a performance-enhancing method to help reduce the number of hasRole(java.lang.String) invocations over the wire in client/server systems.
    
    Parameters:
    
    roleIdentifiers - the application-specific role identifiers to check (usually role ids or role names).
    
    Returns:
    
    a boolean array where indices correspond to the index of the roles in the given identifiers. A true value indicates this Subject has the role at that index. False indicates this Subject does not have the role at that index.
  - hasAllRoles
```
boolean hasAllRoles(<> roleIdentifiers)
```
    Returns true if this Subject has all of the specified roles, false otherwise.
    
    Parameters:
    
    roleIdentifiers - the application-specific role identifiers to check (usually role ids or role names).
    
    Returns:
    
    true if this Subject has all the roles, false otherwise.
  - checkRole
```
void checkRole( roleIdentifier)
        throws AuthorizationException
```
    Asserts this Subject has the specified role by returning quietly if they do or throwing an AuthorizationException if they do not.
    
    Parameters:
    
    roleIdentifier - the application-specific role identifier (usually a role id or role name ).
    
    Throws:
    
    AuthorizationException - if this Subject does not have the role.
  - checkRoles
```
void checkRoles(<> roleIdentifiers)
         throws AuthorizationException
```
    Asserts this Subject has all of the specified roles by returning quietly if they do or throwing an AuthorizationException if they do not.
    
    Parameters:
    
    roleIdentifiers - the application-specific role identifiers to check (usually role ids or role names).
    
    Throws:
    
    AuthorizationException - if this Subject does not have all of the specified roles.
  - checkRoles
```
void checkRoles(... roleIdentifiers)
         throws AuthorizationException
```
    Same as checkRoles(CollectionroleIdentifiers) but doesn't require a collection as a an argument. Asserts this Subject has all of the specified roles by returning quietly if they do or throwing an AuthorizationException if they do not.
    
    Parameters:
    
    roleIdentifiers - roleIdentifiers the application-specific role identifiers to check (usually role ids or role names).
    
    Throws:
    
    AuthorizationException - org.apache.shiro.authz.AuthorizationException if this Subject does not have all of the specified roles.
    
    Since:
    
    1.1.0
  - login
```
void login(AuthenticationToken token)
    throws AuthenticationException
```
    Performs a login attempt for this Subject/user. If unsuccessful, an AuthenticationException is thrown, the subclass of which identifies why the attempt failed. If successful, the account data associated with the submitted principals/credentials will be associated with this Subject and the method will return quietly.
    Upon returning quietly, this Subject instance can be considered authenticated and getPrincipal() will be non-null and isAuthenticated() will be true.
    
    Parameters:
    
    token - the token encapsulating the subject's principals and credentials to be passed to the Authentication subsystem for verification.
    
    Throws:
    
    AuthenticationException - if the authentication attempt fails.
    
    Since:
    
    0.9
  - isAuthenticated
```
boolean isAuthenticated()
```
    Returns true if this Subject/user proved their identity during their current session by providing valid credentials matching those known to the system, false otherwise.
    Note that even if this Subject's identity has been remembered via 'remember me' services, this method will still return false unless the user has actually logged in with proper credentials during their current session. See the isRemembered() method JavaDoc for more.
    
    Returns:
    
    true if this Subject proved their identity during their current session by providing valid credentials matching those known to the system, false otherwise.
    
    Since:
    
    0.9
  - isRemembered
```
boolean isRemembered()
```
    Returns true if this Subject has an identity (it is not anonymous) and the identity (aka principals) is remembered from a successful authentication during a previous session.
    Although the underlying implementation determines exactly how this method functions, most implementations have this method act as the logical equivalent to this code:
    getPrincipal() != null && !isAuthenticated()
    
    Note as indicated by the above code example, if a Subject is remembered, they are NOT considered authenticated. A check against isAuthenticated() is a more strict check than that reflected by this method. For example, a check to see if a subject can access financial information should almost always depend on isAuthenticated() to guarantee a verified identity, and not this method.
    Once the subject is authenticated, they are no longer considered only remembered because their identity would have been verified during the current session.
    Remembered vs Authenticated
    Authentication is the process of proving you are who you say you are. When a user is only remembered, the remembered identity gives the system an idea who that user probably is, but in reality, has no way of absolutely guaranteeing if the remembered Subject represents the user currently using the application.
    So although many parts of the application can still perform user-specific logic based on the remembered principals, such as customized views, it should never perform highly-sensitive operations until the user has legitimately verified their identity by executing a successful authentication attempt.
    We see this paradigm all over the web, and we will use as an example:
    When you visit Amazon.com and perform a login and ask it to 'remember me', it will set a cookie with your identity. If you don't log out and your session expires, and you come back, say the next day, Amazon still knows who you probably are: you still see all of your book and movie recommendations and similar user-specific features since these are based on your (remembered) user id.
    BUT, if you try to do something sensitive, such as access your account's billing data, Amazon forces you to do an actual log-in, requiring your username and password.
    This is because although amazon.com assumed your identity from 'remember me', it recognized that you were not actually authenticated. The only way to really guarantee you are who you say you are, and therefore allow you access to sensitive account data, is to force you to perform an actual successful authentication. You can check this guarantee via the isAuthenticated() method and not via this method.
    Returns:
    
    true if this Subject's identity (aka principals) is remembered from a successful authentication during a previous session, false otherwise.
    
    Since:
    
    1.0
  - getSession
```
Session getSession()
```
    Returns the application Session associated with this Subject. If no session exists when this method is called, a new session will be created, associated with this Subject, and then returned.
    
    Returns:
    
    the application Session associated with this Subject.
    
    Since:
    
    0.2
    
    See Also:
    
    getSession(boolean)
  - getSession
```
Session getSession(boolean create)
```
    Returns the application Session associated with this Subject. Based on the boolean argument, this method functions as follows:
    
    If there is already an existing session associated with this Subject, it is returned and the create argument is ignored.
    
    If no session exists and create is true, a new session will be created, associated with this Subject and then returned.
    
    If no session exists and create is false, null is returned.
    Parameters:
    
    create - boolean argument determining if a new session should be created or not if there is no existing session.
    
    Returns:
    
    the application Session associated with this Subject or null based on the above described logic.
    
    Since:
    
    0.2
  - logout
```
void logout()
```
    Logs out this Subject and invalidates and/or removes any associated entities, such as a Session and authorization data. After this method is called, the Subject is considered 'anonymous' and may continue to be used for another log-in if desired.
    Web Environment Warning
    Calling this method in web environments will usually remove any associated session cookie as part of session invalidation. Because cookies are part of the HTTP header, and headers can only be set before the response body (html, image, etc) is sent, this method in web environments must be called before any content has been rendered.
    The typical approach most applications use in this scenario is to redirect the user to a different location (e.g. home page) immediately after calling this method. This is an effect of the HTTP protocol itself and not a reflection of Shiro's implementation.
    Non-HTTP environments may of course use a logged-out subject for login again if desired.
  - execute
```
<V> V execute(<V> callable)
       throws ExecutionException
```
    Associates the specified Callable with this Subject instance and then executes it on the currently running thread. If you want to execute the Callable on a different thread, it is better to use the associateWith(Callable) method instead.
    
    Type Parameters:
    
    V - the type of return value the Callable will return
    
    Parameters:
    
    callable - the Callable to associate with this subject and then execute.
    
    Returns:
    
    the resulting object returned by the Callable's execution.
    
    Throws:
    
    method throws an exception.
    Since: 1.0
  execute void execute( runnable) Associates the specified Runnable with this Subject instance and then executes it on the currently running thread. If you want to execute the Runnable on a different thread, it is better to use the associateWith(Runnable) method instead. Note: This method is primarily provided to execute existing/legacy Runnable implementations. It is better for new code to use execute(Callable) since that supports the ability to return values and catch exceptions. Parameters: runnable - the Runnable to associate with this Subject and then execute. Since: 1.0 associateWith <V> <V> associateWith(<V> callable) Returns a Callable instance matching the given argument while additionally ensuring that it will retain and execute under this Subject's identity. The returned object can be used with an to execute as this Subject. This will effectively ensure that any calls to SecurityUtils.getSubject() and related functionality will continue to function properly on any thread that executes the returned Callable instance. Type Parameters: V - the Callables return value type Parameters: callable - the callable to execute as this Subject Returns: a Callable that can be run as this Subject. Since: 1.0 associateWith associateWith( runnable) Returns a Runnable instance matching the given argument while additionally ensuring that it will retain and execute under this Subject's identity. The returned object can be used with an or another thread to execute as this Subject. This will effectively ensure that any calls to SecurityUtils.getSubject() and related functionality will continue to function properly on any thread that executes the returned Runnable instance. *Note that if you need a return value to be returned as a result of the runnable's execution or if you need to react to any Exceptions, it is highly recommended to use the createCallable method instead of this one. Parameters: runnable - the runnable to execute as this Subject Returns: a Runnable that can be run as this Subject on another thread. Since: 1.0 See Also: (java.util.concurrent.Callable) runAs void runAs(PrincipalCollection principals) throws , Allows this subject to 'run as' or 'assume' another identity indefinitely. This can only be called when the Subject instance already has an identity (i.e. they are remembered from a previous log-in or they have authenticated during their current session). Some notes about runAs: You can tell if a Subject is 'running as' another identity by calling the isRunAs() method. If running as another identity, you can determine what the previous 'pre run as' identity was by calling the getPreviousPrincipals() method. When you want a Subject to stop running as another identity, you can return to its previous 'pre run as' identity by calling the releaseRunAs() method. Parameters: principals - the identity to 'run as', aka the identity to assume indefinitely. Throws: - if the specified principals collection is null or empty. - if this Subject does not yet have an identity of its own. Since: 1.0 isRunAs boolean isRunAs() Returns true if this Subject is 'running as' another identity other than its original one or false otherwise (normal Subject state). See the runAs method for more information. Returns: true if this Subject is 'running as' another identity other than its original one or false otherwise (normal Subject state). Since: 1.0 See Also: runAs(org.apache.shiro.subject.PrincipalCollection) getPreviousPrincipals PrincipalCollection getPreviousPrincipals() Returns the previous 'pre run as' identity of this Subject before assuming the current runAs identity, or null if this Subject is not operating under an assumed identity (normal state). See the runAs method for more information. Returns: the previous 'pre run as' identity of this Subject before assuming the current runAs identity, or null if this Subject is not operating under an assumed identity (normal state). Since: 1.0 See Also: runAs(org.apache.shiro.subject.PrincipalCollection) releaseRunAs PrincipalCollection releaseRunAs() Releases the current 'run as' (assumed) identity and reverts back to the previous 'pre run as' identity that existed before #runAs runAs was called. This method returns 'run as' (assumed) identity being released or null if this Subject is not operating under an assumed identity. Returns: the 'run as' (assumed) identity being released or null if this Subject is not operating under an assumed identity. Since: 1.0 See Also: runAs(org.apache.shiro.subject.PrincipalCollection)

Interface Subject

Acquiring a Subject

Permission methods

Nested Class Summary

Method Summary

Method Detail

getPrincipal

Uniqueness

getPrincipals

isPermitted

isPermitted

isPermitted

isPermitted

isPermittedAll

isPermittedAll

checkPermission

checkPermission

checkPermissions

checkPermissions

hasRole

hasRoles

hasAllRoles

checkRole

checkRoles

checkRoles

login

isAuthenticated

isRemembered

Remembered vs Authenticated

getSession

getSession

logout

Web Environment Warning

execute

execute

associateWith

associateWith

runAs

isRunAs

getPreviousPrincipals

releaseRunAs