org.jsecurity.subject
Class DelegatingSubject

java.lang.Object
  org.jsecurity.subject.DelegatingSubject

All Implemented Interfaces:

Subject

public class DelegatingSubject
extends Object
implements Subject

Implementation of the Subject interface that delegates method calls to an underlying SecurityManager instance for security checks. It is essentially a SecurityManager proxy.

This implementation does not maintain state such as roles and permissions (only Subject principals, such as usernames or user primary keys) for better performance in a stateless architecture. It instead asks the underlying SecurityManager every time to perform the authorization check.

A common misconception in using this implementation is that an EIS resource (RDBMS, etc) would be "hit" every time a method is called. This is not necessarily the case and is up to the implementation of the underlying SecurityManager instance. If caching of authorization data is desired (to eliminate EIS round trips and therefore improve database performance), it is considered much more elegant to let the underlying SecurityManager implementation or its delegate components manage caching, not this class. A SecurityManager is considered a business-tier component, where caching strategies are better suited.

Applications from large and clustered to simple and vm local all benefit from stateless architectures. This implementation plays a part in the stateless programming paradigm and should be used whenever possible.

Since:

0.1

Author:

Les Hazlewood, Jeremy Haile

Field Summary

protected boolean	authenticated
protected InetAddress	inetAddress
protected PrincipalCollection	principals
protected SecurityManager	securityManager
protected Session	session

Constructor Summary

DelegatingSubject(PrincipalCollection principals, boolean authenticated, InetAddress inetAddress, Session session, SecurityManager securityManager)

DelegatingSubject(SecurityManager securityManager)

Method Summary

protected void	assertAuthzCheckPossible()
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 role) 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> roles) Asserts this Subject has all of the specified roles by returning quietly if they do or throwing an AuthorizationException if they do not.
InetAddress	getInetAddress() Returns the InetAddress associated with the client who created/is interacting with this Subject.
protected static InetAddress	getLocalHost()
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()
SecurityManager	getSecurityManager()
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.
protected boolean	hasPrincipals()
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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

principals

protected PrincipalCollection principals

authenticated

protected boolean authenticated

inetAddress

protected InetAddress inetAddress

session

protected Session session

securityManager

protected SecurityManager securityManager

Constructor Detail

DelegatingSubject

public DelegatingSubject(SecurityManager securityManager)

DelegatingSubject

public DelegatingSubject(PrincipalCollection principals,
                         boolean authenticated,
                         InetAddress inetAddress,
                         Session session,
                         SecurityManager securityManager)

Method Detail

getLocalHost

protected static InetAddress getLocalHost()

getSecurityManager

public SecurityManager getSecurityManager()

hasPrincipals

protected boolean hasPrincipals()

getInetAddress

public InetAddress getInetAddress()

Returns the InetAddress associated with the client who created/is interacting with this Subject.

Returns:

the InetAddress associated with the client who created/is interacting with this Subject.

getPrincipal

public Object getPrincipal()

Description copied from interface: Subject

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.

Specified by:

getPrincipal in interface Subject

Returns:

this Subject's application-specific identity.

See Also:

Subject.getPrincipal()

getPrincipals

public PrincipalCollection getPrincipals()

Specified by:

getPrincipals in interface Subject

isPermitted

public boolean isPermitted(String permission)

Description copied from interface: Subject

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.

Specified by:

isPermitted in interface Subject

Parameters:

permission - the String representation of a Permission that is being checked.

Returns:

true if this Subject is permitted, false otherwise.

See Also:

Subject.isPermitted(Permission permission)

isPermitted

public boolean isPermitted(Permission permission)

Description copied from interface: Subject

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.

Specified by:

isPermitted in interface Subject

Parameters:

permission - the permission that is being checked.

Returns:

true if this Subject is permitted, false otherwise.

isPermitted

public boolean[] isPermitted(String... permissions)

Description copied from interface: Subject

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.

Specified by:

isPermitted in interface Subject

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.

isPermitted

public boolean[] isPermitted(List<Permission> permissions)

Description copied from interface: Subject

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 Subject.isPermitted(java.lang.String) invocations over the wire in client/server systems.

Specified by:

isPermitted in interface Subject

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

public boolean isPermittedAll(String... permissions)

Description copied from interface: Subject

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.

Specified by:

isPermittedAll in interface Subject

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.

See Also:

Subject.isPermittedAll(Collection)

isPermittedAll

public boolean isPermittedAll(Collection<Permission> permissions)

Description copied from interface: Subject

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.

Specified by:

isPermittedAll in interface Subject

Parameters:

permissions - the permissions to check.

Returns:

true if this Subject has all of the specified permissions, false otherwise.

assertAuthzCheckPossible

protected void assertAuthzCheckPossible()
                                 throws AuthorizationException

Throws:

AuthorizationException

checkPermission

public void checkPermission(String permission)
                     throws AuthorizationException

Description copied from interface: Subject

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.

Specified by:

checkPermission in interface Subject

Parameters:

permission - the String representation of the Permission to check.

Throws:

AuthorizationException - if the user does not have the permission.

checkPermission

public void checkPermission(Permission permission)
                     throws AuthorizationException

Description copied from interface: Subject

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.

Specified by:

checkPermission in interface Subject

Parameters:

permission - the Permission to check.

Throws:

AuthorizationException - if this Subject does not have the permission.

checkPermissions

public void checkPermissions(String... permissions)
                      throws AuthorizationException

Description copied from interface: Subject

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.

Specified by:

checkPermissions in interface Subject

Parameters:

permissions - the string representations of Permissions to check.

Throws:

AuthorizationException - if this Subject does not have all of the given permissions.

checkPermissions

public void checkPermissions(Collection<Permission> permissions)
                      throws AuthorizationException

Description copied from interface: Subject

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.

Specified by:

checkPermissions in interface Subject

Parameters:

permissions - the Permissions to check.

Throws:

AuthorizationException - if this Subject does not have all of the given permissions.

hasRole

public boolean hasRole(String roleIdentifier)

Description copied from interface: Subject

Returns true if this Subject has the specified role, false otherwise.

Specified by:

hasRole in interface Subject

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

public boolean[] hasRoles(List<String> roleIdentifiers)

Description copied from interface: Subject

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 Subject.hasRole(java.lang.String) invocations over the wire in client/server systems.

Specified by:

hasRoles in interface Subject

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

public boolean hasAllRoles(Collection<String> roleIdentifiers)

Description copied from interface: Subject

Returns true if this Subject has all of the specified roles, false otherwise.

Specified by:

hasAllRoles in interface Subject

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

public void checkRole(String role)
               throws AuthorizationException

Description copied from interface: Subject

Asserts this Subject has the specified role by returning quietly if they do or throwing an AuthorizationException if they do not.

Specified by:

checkRole in interface Subject

Parameters:

role - the application-specific role identifier (usually a role id or role name ).

Throws:

AuthorizationException - if this Subject does not have the role.

checkRoles

public void checkRoles(Collection<String> roles)
                throws AuthorizationException

Description copied from interface: Subject

Asserts this Subject has all of the specified roles by returning quietly if they do or throwing an AuthorizationException if they do not.

Specified by:

checkRoles in interface Subject

Parameters:

roles - 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

public void login(AuthenticationToken token)
           throws AuthenticationException

Description copied from interface: Subject

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.

Specified by:

login in interface Subject

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.

isAuthenticated

public boolean isAuthenticated()

Description copied from interface: Subject

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.

Specified by:

isAuthenticated in interface Subject

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.

getSession

public Session getSession()

Description copied from interface: Subject

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.

Specified by:

getSession in interface Subject

Returns:

the application Session associated with this Subject.

See Also:

Subject.getSession(boolean)

getSession

public Session getSession(boolean create)

Description copied from interface: Subject

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.

Specified by:

getSession in interface Subject

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.

logout

public void logout()

Description copied from interface: Subject

Logs out this Subject and invalidates and/or removes any associated entities (such as a Session and authorization data.

Specified by:

logout in interface Subject