com.sun.xacml
Class PolicyReference

java.lang.Object
  com.sun.xacml.AbstractPolicy
      com.sun.xacml.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

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

Fields inherited from class com.sun.xacml.AbstractPolicy

XPATH_1_0_VERSION

Constructor Summary

PolicyReference(URI reference, int policyType, PolicyFinder finder)
Creates a new PolicyReference.

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	getChildren() Returns the child policy nodes under this node in the policy tree.
CombiningAlgorithm	getCombiningAlg() Returns the combining algorithm used by this policy.
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) Creates an instance of a PolicyReference object based on a DOM node.
Set	getObligations() Returns the Set of obligations for this policy, which may be empty if there are no obligations.
Target	getTarget() Returns the target for this policy.
MatchResult	match(EvaluationCtx context) Given the input context sees whether or not the request matches this policy.

Methods inherited from class com.sun.xacml.AbstractPolicy

encodeCommonElements, 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)
                throws IllegalArgumentException

Creates a new PolicyReference.

Parameters:

reference - the reference to the policy

policyType - one of the two fields in this class

finder - the PolicyFinder used to handle the reference

Throws:

IllegalArgumentException - if the input policyType isn't valid

Method Detail

getInstance

public static PolicyReference getInstance(Node root,
                                          PolicyFinder finder)
                                   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

Throws:

ParsingException - if the node is invalid

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

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

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

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