org.jsecurity.subject
Interface Subject

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 JSecurity's primary mechanism for single-user security functionality.

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. (JSecurity's default implementations do String-to-Permission conversion for these methods using PermissionResolvers.)

These overloaded *Permission methods do forego type-saftey for the benefit of convenience and simplicity, so you should choose which ones to use based on your preferences and needs.

Since:

0.1

Author:

Les Hazlewood, Jeremy Haile

Method Summary

void	checkPermission(Permission permission) Ensures this Subject implies the specified Permission.
void	checkPermission(String permission) Ensures this Subject implies the specified permission String.
void	checkPermissions(Collection<Permission> permissions) Ensures this Subject implies all of the specified permission strings.
void	checkPermissions(String... permissions) Ensures this Subject implies all of the specified permission strings.
void	checkRole(String roleIdentifier) Asserts this Subject has the specified role by returning quietly if they do or throwing an AuthorizationException if they do not.
void	checkRoles(Collection<String> roleIdentifiers) Asserts this Subject has all of the specified roles by returning quietly if they do or throwing an AuthorizationException if they do not.
Object	getPrincipal() Returns this Subject's uniquely-identifying principal, or null if this Subject doesn't yet have account data associated with it (for example, if they haven't logged in).
PrincipalCollection	getPrincipals()
Session	getSession() Returns the application Session associated with this Subject.
Session	getSession(boolean create) Returns the application Session associated with this Subject.
boolean	hasAllRoles(Collection<String> roleIdentifiers) Returns true if this Subject has all of the specified roles, false otherwise.
boolean	hasRole(String roleIdentifier) Returns true if this Subject has the specified role, false otherwise.
boolean[]	hasRoles(List<String> 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 has proven their identity during their current session by providing valid credentials matching those known to the system, false otherwise.
boolean[]	isPermitted(List<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[]	isPermitted(String... permissions) Checks if this Subject implies the given permission strings and returns a boolean array indicating which permissions are implied.
boolean	isPermitted(String permission) Returns true if this Subject is permitted to perform an action or access a resource summarized by the specified permission string.
boolean	isPermittedAll(Collection<Permission> permissions) Returns true if this Subject implies all of the specified permissions, false otherwise.
boolean	isPermittedAll(String... permissions) Returns true if this Subject implies all of the specified permission strings, false otherwise.
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.

Method Detail

getPrincipal

Object getPrincipal()

Returns this Subject's uniquely-identifying principal, or null if this Subject doesn't yet have account data associated with it (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. And although given names and family names (first/last) are technically principals as well, JSecurity expects the object(s) returned from this method to be uniquely identifying attibute(s) for your 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.

Most single-Realm applications would return from this method a single unique principal as noted above (for example a String username or Long user id, etc, etc). Single-realm applications represent the large majority of JSecurity applications.

However, in multi-Realm configurations, which are fully supported by JSecurity as well, it is possible that the return value encapsulates more than one principal. Typically multi-realm applications need to retain the unique principals for each Realm so subsequent security checks against these Realms can utilize these multiple principals. In these cases, the object returned could be a Collection or any application-specific instance that encapsulates the principals.

Returns:

this Subject's application-specific identity.

getPrincipals

PrincipalCollection getPrincipals()

isPermitted

boolean isPermitted(String 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(String... 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:

an array of booleans whose 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(List<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:

an array of booleans whose 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(String... 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(Collection<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(String 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 exisiting 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(String... permissions)
                      throws AuthorizationException

Ensures this Subject implies all of the specified permission strings. If this subject's exisiting 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(Collection<Permission> permissions)
                      throws AuthorizationException

Ensures this Subject implies all of the specified permission strings. If this subject's exisiting 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(String 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(List<String> 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:

an array of booleans whose 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(Collection<String> 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(String 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(Collection<String> 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.

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 returninq 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 has proven 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 RememberMeAuthenticationToken class JavaDoc for why this would occur.

Returns:

true if this Subject has proven their identity during their current session by providing valid credentials matching those known to the system, false otherwise.

Since:

0.9

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.