com.metamatrix.platform.security.api
Class AuthorizationPolicy

java.lang.Object
  com.metamatrix.platform.security.api.AuthorizationPolicy

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable

public class AuthorizationPolicy
extends java.lang.Object
implements java.lang.Comparable, java.io.Serializable

The AuthorizationPolicy class defines a set of permissions (i.e., permissions) that apply to a set of principals (@see MetaMatrixPrincipalName). Each permission defines a resource (or set of resources) that are to be controlled, what actions are allowed, and possibly any additional restrictions that should be placed upon the resource to limit content (i.e., content modifiers).

See Also:

Serialized Form

Constructor Summary

AuthorizationPolicy(AuthorizationPolicy orig)
Create an instance of an AuthorizationPolicy from a copy of another.

AuthorizationPolicy(AuthorizationPolicyID id)
Create an instance of an AuthorizationPolicy that has the specified ID.

AuthorizationPolicy(AuthorizationPolicyID id, java.util.Set principals, java.util.Set permissions)
Create an instance of an AuthorizationPolicy that has the specified ID, principal set and permissions.

Method Summary

boolean	addAllPermissions(AuthorizationPermissions permissions) Add to this policy's set of existing permissions a new set of permissions that are to be applied by the policy.
boolean	addAllPermissions(java.util.Set permissions) Add to this policy's set of existing permissions a set of additional permissions that are to be applied by the policy.
boolean	addAllPrincipals(java.util.Set newPrincipals) Add to this policy's set of existing principals a set of new MetaMatrixPrincipalName to whom this policy is to apply.
boolean	addPermission(AuthorizationPermission permission) Add to this policy's set of existing permissions a new permission that is to be applied by the policy.
boolean	addPrincipal(MetaMatrixPrincipalName principal) Add to this policy's set of existing principals a new MetaMatrixPrincipalName name to whom this policy is to apply.
void	clearPrincipals() Remove from this policy the entire set of existing MetaMatrixPrincipalName references.
int	compareTo(java.lang.Object o) Compares this AuthorizationPolicy to another Object.
boolean	equals(java.lang.Object obj) Returns true if the specified object is semantically equal to this instance.
AuthorizationPermission	findPermissionWithResource(AuthorizationResource resource) Given an AuthorizationResource, find the AuthorizationPermission, if any, that supplies an AuthorizationAction for that resource.
AuthorizationPolicyID	getAuthorizationPolicyID() Obtain the identifier for this policy.
java.util.Collection	getDependantPermissions(AuthorizationResource resource) Given an AuthorizationResource, find the AuthorizationPermissions, if any, that are dependant on that resource.
java.lang.String	getDescription() Obtain the description for this policy which may be null.
int	getPermissionCount() Obtain the number of permissions that this policy applies.
java.util.Set	getPermissions() Obtain the permissions that this policy applies as a Set.
int	getPrincipalCount() Obtain the number of principals that this policy applies to.
java.util.Set	getPrincipals() Obtain the set of principal names that this policy applies to.
int	hashCode() Overrides Object hashCode method.
boolean	hasPermissions() Return whether this policy currently has at least one permission instance.
boolean	hasPrincipal() Return whether this policy currently has at least one principal reference.
boolean	implies(AuthorizationPermission permission) Checks to see if any of the AuthorizationPermission instances in this policy imply access to the resouces in the permission object.
java.util.Iterator	iterator() Obtain an iterator over the AuthorizationPermission instances that this policy applies.
void	removePermission(AuthorizationPermission permission) Remove from this policy's set of existing permissions the specified permission.
void	removePermissions() Remove all of this policy's existing permissions.
void	removePrincipal(MetaMatrixPrincipalName principal) Remove from this policy's set of existing principals the specified MetaMatrixPrincipalName.
void	setDescription(java.lang.String desc) Define the set of description for this policy.
void	setPermissions(AuthorizationPermissions permissions) Define the set of permissions that this policy is to apply.
void	setPrincipals(java.util.Set principals) Define the set of MetaMatrixPrincipalNames that this policy applies to.
java.lang.String	toString() Returns a string describing this policy object.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

AuthorizationPolicy

public AuthorizationPolicy(AuthorizationPolicyID id)

Create an instance of an AuthorizationPolicy that has the specified ID.

Parameters:

id - the ID of the policy

AuthorizationPolicy

public AuthorizationPolicy(AuthorizationPolicyID id,
                           java.util.Set principals,
                           java.util.Set permissions)

Create an instance of an AuthorizationPolicy that has the specified ID, principal set and permissions.

Parameters:

id - the ID of the policy

principals - the set of MetaMatrixPrincipalNames to which this policy applies.

permissions - the permissions that define the resource access for this policy.

AuthorizationPolicy

public AuthorizationPolicy(AuthorizationPolicy orig)

Create an instance of an AuthorizationPolicy from a copy of another.

Parameters:

orig - the original policy that this new instance is to be based upon

Method Detail

findPermissionWithResource

public AuthorizationPermission findPermissionWithResource(AuthorizationResource resource)

Given an AuthorizationResource, find the AuthorizationPermission, if any, that supplies an AuthorizationAction for that resource.

Parameters:

resource - The resource for which to find a permission.

Returns:

The requested AuthorizationPermission (may be null if not found).

getDependantPermissions

public java.util.Collection getDependantPermissions(AuthorizationResource resource)

Given an AuthorizationResource, find the AuthorizationPermissions, if any, that are dependant on that resource. An AuthorizationPermission is dependant on a resource if it has any AuthorizationActions on that resource or if it is part of a recursive permission involving the resource.

Parameters:

resource - The resource for which to find a permission.

Returns:

The Collections AuthorizationPermission (may be empty but not null).

getAuthorizationPolicyID

public AuthorizationPolicyID getAuthorizationPolicyID()

Obtain the identifier for this policy.

Returns:

the policy's identifier.

getPrincipals

public java.util.Set getPrincipals()

Obtain the set of principal names that this policy applies to.

Returns:

the set of MetaMatrixPrincipalNames to which this policy applies; never null but possibly empty

getPrincipalCount

public int getPrincipalCount()

Obtain the number of principals that this policy applies to.

Returns:

the number of principals instances in this policy.

getPermissionCount

public int getPermissionCount()

Obtain the number of permissions that this policy applies.

Returns:

the number of permissions instances in this policy.

getPermissions

public java.util.Set getPermissions()

Obtain the permissions that this policy applies as a Set.

Returns:

the permission instances in this policy.

hasPermissions

public boolean hasPermissions()

Return whether this policy currently has at least one permission instance.

Returns:

true if this policy contains at least one AuthorizationPermission instance that it applies.

getDescription

public java.lang.String getDescription()

Obtain the description for this policy which may be null.

Returns:

the description. May be null.

iterator

public java.util.Iterator iterator()

Obtain an iterator over the AuthorizationPermission instances that this policy applies.

Returns:

an iterator that can be used to access each of the AuthorizationPermission instances

hasPrincipal

public boolean hasPrincipal()

Return whether this policy currently has at least one principal reference.

Returns:

true if this policy contains at least one principal instance to which this policy is to be applied.

implies

public boolean implies(AuthorizationPermission permission)

Checks to see if any of the AuthorizationPermission instances in this policy imply access to the resouces in the permission object.

Parameters:

permission - the AuthorizationPermission object to check.

Returns:

true if permission is implied by the AuthorizationPermission instances in this policy, or false otherwise

toString

public java.lang.String toString()

Returns a string describing this policy object. The format is:

 super.toString() (
   // the authorization policy ID of the policy ...
   // the description of the policy ...
   // enumerate all the Principal
   // objects and call toString() on them,
   // one per line..
   // enumerate all the AuthorizationPermission
   // objects and call toString() on them,
   // one per line..
 )

super.toString is a call to the toString method of this object's superclass, which is Object. The result is this object's type name followed by this object's hashcode, thus enabling clients to differentiate different AuthorizationPolicy objects, even if they contain the same permissions.

Overrides:

toString in class java.lang.Object

hashCode

public int hashCode()

Overrides Object hashCode method.

Overrides:

hashCode in class java.lang.Object

Returns:

a hash code value for this object.

See Also:

Object.hashCode(), Object.equals(Object)

equals

public boolean equals(java.lang.Object obj)

Returns true if the specified object is semantically equal to this instance. Note: this method is consistent with compareTo().

Overrides:

equals in class java.lang.Object

Parameters:

obj - the object that this instance is to be compared to.

Returns:

whether the object is equal to this object.

compareTo

public int compareTo(java.lang.Object o)
              throws java.lang.ClassCastException

Compares this AuthorizationPolicy to another Object. If the Object is an AuthorizationPolicy, this function compares the name. Otherwise, it throws a ClassCastException (as AuthorizationPolicy instances are comparable only to other AuthorizationPolicy instances). Note: this method is consistent with equals().

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

o - the object that this instance is to be compared to.

Returns:

a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object, respectively.

Throws:

java.lang.ClassCastException - if the specified object's type prevents it from being compared to this AuthorizationPolicy.

setDescription

public void setDescription(java.lang.String desc)

Define the set of description for this policy.

Parameters:

desc - the new description for this policy.

setPermissions

public void setPermissions(AuthorizationPermissions permissions)

Define the set of permissions that this policy is to apply. Any existing permissions are removed from the policy. If the specified set is null, this policy will have no governing permissions.

Parameters:

permissions - the new permissions that this policy applies.

setPrincipals

public void setPrincipals(java.util.Set principals)

Define the set of MetaMatrixPrincipalNames that this policy applies to. Any existing MetaMatrixPrincipalNames are removed from the policy. If the specified set is null or empty, this policy will apply to no principals.

Parameters:

principals - the new set of MetaMatrixPrincipalNames to which this policy applies.

addPermission

public boolean addPermission(AuthorizationPermission permission)

Add to this policy's set of existing permissions a new permission that is to be applied by the policy.

Parameters:

permission - the new permission that is to be added to this policy. May not be null.

Returns:

true if this policy changed as a result of the addition.

Throws:

java.lang.IllegalArgumentException - if the specified permission is null.

addAllPermissions

public boolean addAllPermissions(AuthorizationPermissions permissions)

Add to this policy's set of existing permissions a new set of permissions that are to be applied by the policy.

Parameters:

permissions - the new permissions that are to be added to this policy. May not be null.

Returns:

true if this policy changed as a result of the addition.

Throws:

java.lang.IllegalArgumentException - if the specified permission is null.

addAllPermissions

public boolean addAllPermissions(java.util.Set permissions)

Add to this policy's set of existing permissions a set of additional permissions that are to be applied by the policy. Any permission that is added that has the same resource name as an existing permission overwrites the existing permission.

Parameters:

permissions - the set of new permissions that are to be added to this policy. May not be null.

Returns:

true if this policy changed as a result of the additions.

Throws:

java.lang.IllegalArgumentException - if the specified set of permissions is null or if the set contains a null value.

removePermission

public void removePermission(AuthorizationPermission permission)

Remove from this policy's set of existing permissions the specified permission. If the permission is not currently in this policy, this method simply returns without performing any operation.

Parameters:

permission - the permission that is to be removed from this policy.

removePermissions

public void removePermissions()

Remove all of this policy's existing permissions.

addPrincipal

public boolean addPrincipal(MetaMatrixPrincipalName principal)

Add to this policy's set of existing principals a new MetaMatrixPrincipalName name to whom this policy is to apply.

Parameters:

principal - the new MetaMatrixPrincipalName that is to be added to this policy. May not be null.

Returns:

true if this policy changed as a result of the addition.

Throws:

java.lang.IllegalArgumentException - if the specified principal is null.

addAllPrincipals

public boolean addAllPrincipals(java.util.Set newPrincipals)

Add to this policy's set of existing principals a set of new MetaMatrixPrincipalName to whom this policy is to apply.

Parameters:

newPrincipals - the set of new MetaMatrixPrincipalName that are to be added to this policy. May not be null.

Returns:

true if this policy changed as a result of the additions.

Throws:

java.lang.IllegalArgumentException - if the specified set of principals is null or if the set contains a null value.

removePrincipal

public void removePrincipal(MetaMatrixPrincipalName principal)

Remove from this policy's set of existing principals the specified MetaMatrixPrincipalName. If the principal is not in the existing set of principal names for this policy, this method simply does nothing for that principal.

Parameters:

principal - the MetaMatrixPrincipalName that is to be removed from this policy.

clearPrincipals

public void clearPrincipals()

Remove from this policy the entire set of existing MetaMatrixPrincipalName references.