Package org.ow2.authzforce.core.pdp.api.value

Class XPathValue

  • All Implemented Interfaces:
    AttributeValue, PrimitiveValue, Value
    public final class XPathValue
extends SimpleValue<String>
    Representation of XACML xpathExpression datatype. All objects of this class are immutable and all methods of the class are thread-safe.

    XACML 3.0 Core spec, §A.3.15: "An XPath expression evaluates to a node-set, which is a set of XML nodes that match the expression. A node or node-set is not in the formal data-type system of XACML. All comparison or other operations on node-sets are performed in isolation of the particular [XPATH-based] function specified. The context nodes and namespace mappings of the XPath expressions are defined by the XPath data-type, see section B.3."

    In short, the xpathExpression is evaluated in the context of calling XPath-based functions on a given evaluation context only. These functions typically use evaluate(EvaluationContext) to get the matching node-set.

    WARNING: this class is not optimized for request-time evaluation but for policy initialization-time. Therefore, its use is not recommended for evaluating xpathExpressions in XACML Request. We consider it not useful in the latter case, as the Requester (PEP) could evaluate the xpathExpressions in the first place, and does not need the PDP to do it.

    NB (considerations for developers): the standard datatype 'xpathExpression' may seem like a special case because xpathExpression evaluation depends on the context; therefore it might seem like a good idea to have 'xpathExpression' be implemented as a subclass of Expression instead. However, we prefer to avoid that for simplicity. Indeed, if we need to evaluate a 'xpathExpression', in standard XACML, xpathExpressions are used only as parameters of XPath-based functions (A.3.15), and such functions just need to cast input values to this XPathValue class and call evaluate(EvaluationContext) for evaluation. Outside the context of XPath-based functions, we may consider xpathExpressions as simple literal constants like other AttributeValues.

    Version:
    $Id: $

    • Field Detail

      • XPATH_CATEGORY_ATTRIBUTE_LOCALNAME

        public static final String XPATH_CATEGORY_ATTRIBUTE_LOCALNAME
        XML attribute local name that indicate the XACML attribute category of the Content to which the xpathExpression is applied: "XPathCategory" .
        See Also:
        Constant Field Values

      • XPATH_CATEGORY_ATTRIBUTE_QNAME

        public static final QName XPATH_CATEGORY_ATTRIBUTE_QNAME
        QName of XPathCategory attribute in xpathExpression, using "XPathCategory" as local name. This is allowed by XACML schema as part of: 
         
 <xs:anyAttribute namespace="##any" processContents="lax"/>
        ... therefore namespace returned by JAXB is empty "". More info: https://jaxb.java.net/tutorial/section_6_2_7_5 -Collecting-Unspecified-Attributes-XmlAnyAttribute .html#Collecting%20Unspecified%20Attributes:%20XmlAnyAttribute

    • Constructor Detail

      • XPathValue

        public XPathValue​(String xpath,
                  Map<QName,​String> otherXmlAttributes,
                  net.sf.saxon.s9api.XPathCompiler xPathCompiler)
           throws IllegalArgumentException
        Instantiates from XPath expression.
        Parameters:
        xpath - XPath
        otherXmlAttributes - other XML attributes on the xpathExpression AttributeValue node, one of which is expected to be the attribute "XPathCategory"
        xPathCompiler - XPath compiler for compiling/evaluating xpath
        Throws:
        IllegalArgumentException - if value is not a valid string representation for this value datatype or {code otherXmlAttributes == null} or {code otherXmlAttributes} does not contain any "XPathCategory" attribute

    • Method Detail

      • evaluate

        public net.sf.saxon.s9api.XdmValue evaluate​(EvaluationContext context)
                                     throws IndeterminateEvaluationException
        Convenient method to get the XML nodes ("node-set") matching the XPath expression from the Content node of the XACML Attributes element with category XPathCategory in this context. XPathCategory is extracted from the attribute of the same name in otherXmlAttributes argument passed to XPathValue(String, Map, XPathCompiler) when creating this instance. To be used by XPath-based functions defined in section A.3.15 of XACML 3.0 Core specification.
        Parameters:
        context - current evaluation context
        Returns:
        node-set
        Throws:
        IndeterminateEvaluationException - error evaluating the XPath expression

      • printXML

        public String printXML()
        Converts the internal value (accessible via SimpleValue.getUnderlyingValue() to a valid lexical representation for XML marshalling. Equivalent to the 'printMethod' in JAXB 'javaType' binding customizations. Implementations of this typically call DatatypeConverter. This method is called by SimpleValue.getContent() and its result cached by the same method for later use. Therefore, no need to cache the result in the implementation.
        Specified by:
        printXML in class SimpleValue<String>
        Returns:
        XML-valid lexical representation.

      • getXmlAttributes

        public Map<QName,​String> getXmlAttributes()
        Description copied from interface: AttributeValue
        Get the attributes attached to the value as specified by XmlAnyAttribute, or any kind of attributes/metadata defined by some markup language that this value type is designed to be (de)serialized (from) to. The primary use of this is (de)serialization of XML attributes. Each key is an attribute's QName and the associated value is the attribute's string value. One example of such XML attribute in XACML standard is the xpathExpression value which has an XPathCategory attribute.
        Returns:
        (possibly mixed) content ; not null (must be empty if no attribute)