org.jboss.security.xacml.sunxacml.support.finder
Class PolicyCollection

java.lang.Object
  extended by org.jboss.security.xacml.sunxacml.support.finder.PolicyCollection

public class PolicyCollection
extends Object

This class handles collections of AbstractPolicy instances, and provides some commonly useful operations. Specifically, it lets you retrieve matching policies (based on reference or context), it optionally handles wrapping multiple matches under a single PolicySet, and it manages different versions of policies correctly. This class is intended for use as a backing store to PolicyFinderModules, but in practice may have many uses.

Note that this class will accept multiple versions of the same policy. This means that when you retieve a policy by reference, you will get the correct version. It also means that when you retrieve a policy based on context, there may be multiple revisions of the same policy, any number of which may apply. Generally speaking, the correct behavior here is not to return all of these policies, since they are (virtually speaking) the same policy, but may have conflicting rules. So, as a simplification, and to handle the most common cases, only the most recent version of a policy is returned in these cases. If you need a more complex solution, you will need to implement it yourself. Because the support modules use this class as their backing store, this is true also of those modules.

Note that this is not a heavily optimized class. It is intended more as an example, support code for the finder modules, and a starting utility for other programmers than as an enterprise-quality implementation. That said, it is fully functional, and should be useful for many applications.

Since:
2.0
Author:
Seth Proctor

Constructor Summary
PolicyCollection()
          Creates a new PolicyCollection that will return errors when multiple policies match for a given request.
PolicyCollection(PolicyCombiningAlgorithm combiningAlg, URI parentPolicyId)
          Creates a new PolicyCollection that will create a new top-level PolicySet when multiple policies match for a given request.
 
Method Summary
 boolean addPolicy(AbstractPolicy policy)
          Adds a new policy to the collection, and uses the policy's identifier as the reference identifier.
 boolean addPolicy(AbstractPolicy policy, String identifier)
          Adds a new policy to the collection using the given identifier as the reference identifier.
 AbstractPolicy getPolicy(EvaluationCtx context)
          Attempts to retrieve a policy based on the given context.
 AbstractPolicy getPolicy(String identifier, int type, VersionConstraints constraints)
          Attempts to retrieve a policy based on the given identifier and other constraints.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

PolicyCollection

public PolicyCollection()
Creates a new PolicyCollection that will return errors when multiple policies match for a given request.


PolicyCollection

public PolicyCollection(PolicyCombiningAlgorithm combiningAlg,
                        URI parentPolicyId)
Creates a new PolicyCollection that will create a new top-level PolicySet when multiple policies match for a given request.

Parameters:
combiningAlg - the algorithm to use in a new PolicySet when more than one policy applies
parentPolicyId - the identifier to use for the new PolicySet
Method Detail

addPolicy

public boolean addPolicy(AbstractPolicy policy)
Adds a new policy to the collection, and uses the policy's identifier as the reference identifier. If this identifier already exists in the collection, and this policy does not represent a new version of the policy, then the policy is not added.

Parameters:
policy - the policy to add
Returns:
true if the policy was added, false otherwise

addPolicy

public boolean addPolicy(AbstractPolicy policy,
                         String identifier)
Adds a new policy to the collection using the given identifier as the reference identifier. If this identifier already exists in the collection, and this policy does not represent a new version of the policy, then the policy is not added.

Parameters:
policy - the policy to add
identifier - the identifier to use when referencing this policy
Returns:
true if the policy was added, false otherwise

getPolicy

public AbstractPolicy getPolicy(EvaluationCtx context)
                         throws TopLevelPolicyException
Attempts to retrieve a policy based on the given context. If multiple policies match then this will either throw an exception or wrap the policies under a new PolicySet (depending on how this instance was constructed). If no policies match, then this will return null. See the comment in the class header about how this behaves when multiple versions of the same policy exist.

Parameters:
context - representation of a request
Returns:
a matching policy, or null if no policy matches
Throws:
TopLevelPolicyException - if multiple policies match but this instance wasn't setup to wrap policies

getPolicy

public AbstractPolicy getPolicy(String identifier,
                                int type,
                                VersionConstraints constraints)
Attempts to retrieve a policy based on the given identifier and other constraints. If there are multiple versions of the identified policy that meet the version constraints, then the most recent version is returned.

Parameters:
identifier - an identifier specifying some policy
type - type of reference (policy or policySet) as identified by the fields in PolicyReference
constraints - any optional constraints on the version of the referenced policy (this will never be null, but it may impose no constraints, and in fact will never impose constraints when used from a pre-2.0 XACML policy)


Copyright © 2011 JBoss, a division of Red Hat, Inc.. All Rights Reserved.