org.wso2.balana

Class PolicyReference

java.lang.Object

org.wso2.balana.AbstractPolicy

org.wso2.balana.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

Fields

Modifier and Type	Field and Description
static int	POLICY_REFERENCE Identifies this as a reference to a Policy
static int	POLICYSET_REFERENCE Identifies this as a reference to a PolicySet

Fields inherited from class org.wso2.balana.AbstractPolicy

metaData

Constructor Summary

Constructors

Constructor and Description
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

Modifier and Type	Method and Description
String	encode() Encodes this PolicyReference into its XML form
void	encode(StringBuilder builder) Encodes this PolicyReference into its XML form and writes this out to the provided StringBuilder
AbstractResult	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	getObligationExpressions() Returns the Set of obligations for this policy, which may be empty if there are no obligations.
URI	getReference() Returns the reference identifier used to resolve the policy.
int	getReferenceType() Returns whether this is a reference to a policy or to a policy set.
AbstractTarget	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.wso2.balana.AbstractPolicy

encodeCommonElements, getActionPolicyValue, getAdviceExpressions, getCombiningParameters, getEnvPolicyValue, getResourcePolicyValue, getSubjectPolicyValue, setActionPolicyValue, setChildren, setEnvPolicyValue, setResourcePolicyValue, setSubjectPolicyValue

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

Returns:

an instance of PolicyReference

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

Returns:

an instance of PolicyReference

Throws:

ParsingException - if the node is invalid

getReference

public URI getReference()

Returns the reference identifier 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 AbstractTarget 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

getObligationExpressions

public Set getObligationExpressions()

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:

getObligationExpressions 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 AbstractResult 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 String encode()

Encodes this PolicyReference into its XML form

Returns:

String

encode

public void encode(StringBuilder builder)

Encodes this PolicyReference into its XML form and writes this out to the provided StringBuilder

Parameters:

builder - string stream into which the XML-encoded data is written