JBoss port of sunxacml 2.0.5-redhat-1

org.jboss.security.xacml.sunxacml
Class PolicyReference

java.lang.Object
  extended by org.jboss.security.xacml.sunxacml.AbstractPolicy
      extended by org.jboss.security.xacml.sunxacml.PolicyReference
All Implemented Interfaces:
PolicyTreeElement

public class PolicyReference
extends AbstractPolicy

This class is used as a placeholder for the PolicyIdReference and PolicySetIdReference fields in a PolicySetType. When a reference is used in a policy set, it is telling the PDP to use an external policy in the current policy. Each time the PDP needs to evaluate that policy reference, it asks the policy finder for the policy. Typically the policy finder will have cached the referenced policy, so this isn't too slow.

NOTE: all of the accessor methods, the match method, and the evaluate method require this class to ask its PolicyFinder for the referenced policy, which can be a slow operation. Care should be taken, therefore in calling these methods too often. Also note that it's not safe to cache the results of these calls, since the referenced policy may change.

Since:
1.0
Author:
Seth Proctor

Field Summary
static int POLICY_REFERENCE
          Identifies this as a reference to a Policy
static int POLICYSET_REFERENCE
          Identifies this as a reference to a PolicySet
 
Constructor Summary
PolicyReference(URI reference, int policyType, PolicyFinder finder, PolicyMetaData parentMetaData)
          Creates a new PolicyReference instance.
PolicyReference(URI reference, int policyType, VersionConstraints constraints, PolicyFinder finder, PolicyMetaData parentMetaData)
          Creates a new PolicyReference instance with version constraints.
 
Method Summary
 void encode(OutputStream output)
          Encodes this PolicyReference into its XML representation and writes this encoding to the given OutputStream with no indentation.
 void encode(OutputStream output, Indenter indenter)
          Encodes this PolicyReference into its XML representation and writes this encoding to the given OutputStream with indentation.
 Result evaluate(EvaluationCtx context)
          Tries to evaluate the policy by calling the combining algorithm on the given policies or rules.
 List getChildElements()
          Returns the child policy nodes and their associated parameters.
 List getChildren()
          Returns the child policy nodes under this node in the policy tree.
 CombiningAlgorithm getCombiningAlg()
          Returns the combining algorithm used by this policy.
 VersionConstraints getConstraints()
          Returns the version constraints associated with this reference.
 String getDefaultVersion()
          Returns the default version for this policy.
 String getDescription()
          Returns the given description of this policy or null if there is no description.
 URI getId()
          Returns the id of this policy.
static PolicyReference getInstance(Node root, PolicyFinder finder)
          Deprecated. As of 2.0 you should avoid using this method and should instead use the version that takes a PolicyMetaData instance. This method will only work for XACML 1.x policies.
static PolicyReference getInstance(Node root, PolicyFinder finder, PolicyMetaData metaData)
          Creates an instance of a PolicyReference object based on a DOM node.
 PolicyMetaData getMetaData()
          Returns the meta-data associated with this policy.
 Set getObligations()
          Returns the Set of obligations for this policy, which may be empty if there are no obligations.
 URI getReference()
          Returns the refernce identitfier used to resolve the policy.
 int getReferenceType()
          Returns whether this is a reference to a policy or to a policy set.
 Target getTarget()
          Returns the target for this policy.
 String getVersion()
          Returns the version of this policy.
 MatchResult match(EvaluationCtx context)
          Given the input context sees whether or not the request matches this policy.
 
Methods inherited from class org.jboss.security.xacml.sunxacml.AbstractPolicy
encodeCommonElements, getCombiningParameters, setChildren
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

POLICY_REFERENCE

public static final int POLICY_REFERENCE
Identifies this as a reference to a Policy

See Also:
Constant Field Values

POLICYSET_REFERENCE

public static final int POLICYSET_REFERENCE
Identifies this as a reference to a PolicySet

See Also:
Constant Field Values
Constructor Detail

PolicyReference

public PolicyReference(URI reference,
                       int policyType,
                       PolicyFinder finder,
                       PolicyMetaData parentMetaData)
                throws IllegalArgumentException
Creates a new PolicyReference instance. This has no constraints on version matching. Note that an XACML 1.x reference may not have any constraints.

Parameters:
reference - the reference to the policy
policyType - one of the two fields in this class
finder - the PolicyFinder used to handle the reference
parentMetaData - the meta-data associated with the containing (parent) policy
Throws:
IllegalArgumentException - if the input policyType isn't valid

PolicyReference

public PolicyReference(URI reference,
                       int policyType,
                       VersionConstraints constraints,
                       PolicyFinder finder,
                       PolicyMetaData parentMetaData)
                throws IllegalArgumentException
Creates a new PolicyReference instance with version constraints. Note that an XACML 1.x reference may not have any constraints.

Parameters:
reference - the reference to the policy
policyType - one of the two fields in this class
constraints - any optional constraints on the version of the referenced policy (this is never null, but it may impose no constraints, and in fact will never impose constraints when used from a pre-2.0 XACML policy)
finder - the PolicyFinder used to handle the reference
parentMetaData - the meta-data associated with the containing (parent) policy
Throws:
IllegalArgumentException - if the input policyType isn't valid
Method Detail

getInstance

public static PolicyReference getInstance(Node root,
                                          PolicyFinder finder)
                                   throws ParsingException
Deprecated. As of 2.0 you should avoid using this method and should instead use the version that takes a PolicyMetaData instance. This method will only work for XACML 1.x policies.

Creates an instance of a PolicyReference object based on a DOM node.

Parameters:
root - the DOM root of a PolicyIdReference or a PolicySetIdReference XML type
finder - the PolicyFinder used to handle the reference
Throws:
ParsingException - if the node is invalid

getInstance

public static PolicyReference getInstance(Node root,
                                          PolicyFinder finder,
                                          PolicyMetaData metaData)
                                   throws ParsingException
Creates an instance of a PolicyReference object based on a DOM node.

Parameters:
root - the DOM root of a PolicyIdReference or a PolicySetIdReference XML type
finder - the PolicyFinder used to handle the reference
metaData - the meta-data associated with the containing policy
Throws:
ParsingException - if the node is invalid

getReference

public URI getReference()
Returns the refernce identitfier used to resolve the policy.

Returns:
the reference URI

getConstraints

public VersionConstraints getConstraints()
Returns the version constraints associated with this reference. This will never be null, though the constraints may be empty.

Returns:
the version constraints

getReferenceType

public int getReferenceType()
Returns whether this is a reference to a policy or to a policy set.

Returns:
the reference type, either POLICY_REFERENCE or POLICYSET_REFERENCE

getId

public URI getId()
Returns the id of this policy. If the policy is invalid or can't be retrieved, then a runtime exception is thrown.

Specified by:
getId in interface PolicyTreeElement
Overrides:
getId in class AbstractPolicy
Returns:
the policy id
Throws:
ProcessingException - if the referenced policy can't be retrieved

getVersion

public String getVersion()
Returns the version of this policy. If the policy is invalid or can't be retrieved, then a runtime exception is thrown.

Overrides:
getVersion in class AbstractPolicy
Returns:
the policy version
Throws:
ProcessingException - if the referenced policy can't be retrieved

getCombiningAlg

public CombiningAlgorithm getCombiningAlg()
Returns the combining algorithm used by this policy. If the policy is invalid or can't be retrieved, then a runtime exception is thrown.

Overrides:
getCombiningAlg in class AbstractPolicy
Returns:
the combining algorithm
Throws:
ProcessingException - if the referenced policy can't be retrieved

getDescription

public String getDescription()
Returns the given description of this policy or null if there is no description. If the policy is invalid or can't be retrieved, then a runtime exception is thrown.

Specified by:
getDescription in interface PolicyTreeElement
Overrides:
getDescription in class AbstractPolicy
Returns:
the description or null
Throws:
ProcessingException - if the referenced policy can't be retrieved

getTarget

public Target getTarget()
Returns the target for this policy. If the policy is invalid or can't be retrieved, then a runtime exception is thrown.

Specified by:
getTarget in interface PolicyTreeElement
Overrides:
getTarget in class AbstractPolicy
Returns:
the policy's target
Throws:
ProcessingException - if the referenced policy can't be retrieved

getDefaultVersion

public String getDefaultVersion()
Returns the default version for this policy. If the policy is invalid or can't be retrieved, then a runtime exception is thrown.

Overrides:
getDefaultVersion in class AbstractPolicy
Returns:
the policy's default version
Throws:
ProcessingException - if the referenced policy can't be retrieved

getChildren

public List getChildren()
Returns the child policy nodes under this node in the policy tree. If the policy is invalid or can't be retrieved, then a runtime exception is thrown.

Specified by:
getChildren in interface PolicyTreeElement
Overrides:
getChildren in class AbstractPolicy
Returns:
the List of child policy nodes
Throws:
ProcessingException - if the referenced policy can't be retrieved

getChildElements

public List getChildElements()
Returns the child policy nodes and their associated parameters. If the policy is invalid or can't be retrieved, then a runtime exception is thrown.

Overrides:
getChildElements in class AbstractPolicy
Returns:
a List of CombinerElements
Throws:
ProcessingException - if the referenced policy can't be retrieved

getObligations

public Set getObligations()
Returns the Set of obligations for this policy, which may be empty if there are no obligations. If the policy is invalid or can't be retrieved, then a runtime exception is thrown.

Overrides:
getObligations in class AbstractPolicy
Returns:
the policy's obligations
Throws:
ProcessingException - if the referenced policy can't be retrieved

getMetaData

public PolicyMetaData getMetaData()
Returns the meta-data associated with this policy. If the policy is invalid or can't be retrieved, then a runtime exception is thrown. Note that this is the meta-data for the referenced policy, not the meta-data for the parent policy (which is what gets provided to the constructors of this class).

Overrides:
getMetaData in class AbstractPolicy
Returns:
the policy's meta-data
Throws:
ProcessingException - if the referenced policy can't be retrieved

match

public MatchResult match(EvaluationCtx context)
Given the input context sees whether or not the request matches this policy. This must be called by combining algorithms before they evaluate a policy. This is also used in the initial policy finding operation to determine which top-level policies might apply to the request. If the policy is invalid or can't be retrieved, then a runtime exception is thrown.

Specified by:
match in interface PolicyTreeElement
Overrides:
match in class AbstractPolicy
Parameters:
context - the representation of the request
Returns:
the result of trying to match the policy and the request

evaluate

public Result evaluate(EvaluationCtx context)
Tries to evaluate the policy by calling the combining algorithm on the given policies or rules. The match method must always be called first, and must always return MATCH, before this method is called.

Specified by:
evaluate in interface PolicyTreeElement
Overrides:
evaluate in class AbstractPolicy
Parameters:
context - the representation of the request
Returns:
the result of evaluation

encode

public void encode(OutputStream output)
Encodes this PolicyReference into its XML representation and writes this encoding to the given OutputStream with no indentation.

Parameters:
output - a stream into which the XML-encoded data is written

encode

public void encode(OutputStream output,
                   Indenter indenter)
Encodes this PolicyReference into its XML representation and writes this encoding to the given OutputStream with indentation.

Parameters:
output - a stream into which the XML-encoded data is written
indenter - an object that creates indentation strings

JBoss port of sunxacml 2.0.5-redhat-1

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