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

Interface EvaluationContext

  • public interface EvaluationContext
    Manages context for the policy evaluation of a given authorization decision request. Typically, an instance of this is instantiated whenever the PDP gets a request and needs to perform an evaluation to a authorization decision. Such a context is used and possibly updated all along the evaluation of the request.

    • Method Detail

      • getNamedAttributeValue

        <AV extends AttributeValue> AttributeBag<AV> getNamedAttributeValue​(AttributeFqn attributeFQN,
                                                                    Datatype<AV> datatype)
                                                             throws IndeterminateEvaluationException
        Returns the value of a named attribute available in the request context. Used to evaluate AttributeDesignatorExpression, ContextSelectorId of AttributeSelectorExpression, or to get values of attributes on which NamedAttributeProviders depends to resolve their own attributes (e.g. some module may need attribute X, such as a subject ID, as input to resolve attribute Y from an external source, such as subject role from a user database).
        Parameters:
        attributeFQN - attribute GUID (global ID = Category,Issuer,AttributeId)
        datatype - attribute value datatype
        Returns:
        attribute value(s), null iff attribute unknown (not set) in this context, empty if attribute known in this context but no value
        Throws:
        IndeterminateEvaluationException - if error occurred trying to determine the attribute value(s) in context. This is different from finding without error that the attribute is not in the context (and/or no value), e.g. if there is a result but type is different from attributeDatatype.

      • getNamedAttributes

        Iterator<Map.Entry<AttributeFqn,​AttributeBag<?>>> getNamedAttributes()
        Get immutable iterator over the context attributes. DO NOT ever use this method to retrieve one or more specific attributes, in which case you must use getNamedAttributeValue(AttributeFqn, Datatype) instead. This is only for iterating over all the attributes, e.g. for debugging/auditing.
        Returns:
        context attributes iterator (implementations must guarantee that the iterator is immutable, i.e. does not allow changing the internal context)

      • putNamedAttributeValueIfAbsent

        boolean putNamedAttributeValueIfAbsent​(AttributeFqn attributeFQN,
                                       AttributeBag<?> result)
        Put Attribute values in the context, only if the attribute is not already known to this context. Indeed, an attribute value cannot be overridden once it is set in the context to comply with 7.3.5 Attribute retrieval: "Regardless of any dynamic modifications of the request context during policy evaluation, the PDP SHALL behave as if each bag of attribute values is fully populated in the context before it is first tested, and is thereafter immutable during evaluation." Therefore, getNamedAttributeValue(AttributeFqn, Datatype) should be called always before calling this, for the same attributeFQN
        Parameters:
        attributeFQN - attribute's global ID
        result - attribute values
        Returns:
        false iff there is already a matching value in this context (this operation did NOT succeed)

      • getAttributeSelectorResult

        <AV extends AttributeValue> Bag<AV> getAttributeSelectorResult​(AttributeSelectorExpression<AV> attributeSelector)
                                                        throws IndeterminateEvaluationException
        Returns available context evaluation result for a given AttributeSelector. This feature is optional. Any implementation that does not implement this method may throw UnsupportedOperationException .
        Parameters:
        attributeSelector - AttributeSelector
        Returns:
        attribute value(s), null iff AttributeSelector's bag of values unknown (not set) in this context because not evaluated yet; empty if it was evaluated in this context but not result, i.e. bag is empty
        Throws:
        IndeterminateEvaluationException - if error occurred trying to determine the result in context. This is different from finding without error that the result is not in the context (and/or no value), e.g. if there is a result but type is different from datatypeClass.

      • putAttributeSelectorResultIfAbsent

        <AV extends AttributeValue> boolean putAttributeSelectorResultIfAbsent​(AttributeSelectorExpression<AV> attributeSelector,
                                                                       Bag<AV> result)
                                                                throws IndeterminateEvaluationException
        Put an Attribute Selector's values in the context, only if the AttributeSelector has not been already evaluated in this context. Therefore getAttributeSelectorResult(AttributeSelectorExpression) should be called always before calling this, for the same attributeSelector
        Parameters:
        attributeSelector - AttributeSelector
        result - AttributeSelector value bag
        Returns:
        false iff there is already a matching value in this context (this operation could NOT succeed)
        Throws:
        IndeterminateEvaluationException - if AttributeSelector evaluation is not supported (this is an optional feature of XACML specification)

      • getAttributesContent

        net.sf.saxon.s9api.XdmNode getAttributesContent​(String category)
        Returns the <Content> of the <Attributes> identified by a given category, to be used for AttributeSelector evaluation.
        Parameters:
        category - category of the Attributes element from which to get the Content.
        Returns:
        the resulting Content node, or null if none in the request Attributes category

      • getVariableValue

        <V extends Value> V getVariableValue​(String variableId,
                                     Datatype<V> datatype)
                              throws IndeterminateEvaluationException
        Get value of a VariableDefinition's expression evaluated in this context and whose value has been cached with putVariableIfAbsent(String, Value) . To be used when evaluating VariableReferences.
        Parameters:
        variableId - identifies the VariableDefinition
        datatype - datatype
        Returns:
        value of the evaluated VariableDefinition's expression, or null if not evaluated (yet) in this context
        Throws:
        IndeterminateEvaluationException - if actual datatype of variable value in context does not match expected datatype

      • putVariableIfAbsent

        boolean putVariableIfAbsent​(String variableId,
                            Value value)
        Caches the value of a VariableDefinition's expression evaluated in this context only if variable is not already set in this context, for later retrieval by getVariableValue(String, Datatype) when evaluating ValueReferences to the same VariableId.

        The variable is set only if it was absent from context. In other words, this method does/must not allow setting the same variable twice. The reason is compliance with XACML spec 7.8 VariableReference evaluation: "the value of an Expression element remains the same for the entire policy evaluation."

        Parameters:
        variableId - identifies the VariableDefinition
        value - value of the VariableDefinition's expression evaluated in this context
        Returns:
        false iff there is already a value for this variable in context (this operation could NOT succeed).

      • removeVariable

        Value removeVariable​(String variableId)
        Removes a variable (defined by VariableDefinition) from this context.
        Parameters:
        variableId - identifies the Variable to remove
        Returns:
        the value of the variable before removal, or null if there was no such variable set in this context.

      • getOther

        Object getOther​(String key)
        Get custom property
        Parameters:
        key - property key
        Returns:
        property
        See Also:
        Map.get(Object)

      • containsKey

        boolean containsKey​(String key)
        Check whether custom property is in the context
        Parameters:
        key - property key
        Returns:
        true if and only if key exists in updatable property keys
        See Also:
        Map.containsKey(Object)

      • putOther

        void putOther​(String key,
              Object val)
        Puts custom property in the context
        Parameters:
        key - property key
        val - property value
        See Also:
        Map.put(Object, Object)

      • remove

        Object remove​(String key)
        Removes custom property from the context
        Parameters:
        key - property key
        Returns:
        the previous value associated with key, or null if there was no mapping for key.
        See Also:
        Map.remove(Object)

      • isApplicablePolicyIdListRequested

        boolean isApplicablePolicyIdListRequested()
        Equivalent of XACML Request ReturnPolicyIdList attribute. XACML ยง5.4.2: "This attribute is used to request that the PDP return a list of all fully applicable policies and policy sets which were used in the decision as a part of the decision response." For a more precise definition of "applicable" in this context, see DecisionResult.getApplicablePolicies().
        Returns:
        true iff original XACML Request's ReturnPolicyIdList=true

      • putListener

        <L extends EvaluationContext.Listener> L putListener​(Class<L> listenerType,
                                                     L listener)
        Registers a listener on this evaluation context
        Parameters:
        listenerType - listener type used as key for retrieving the listener with getListener(Class)
        listener - the new listener to be registered
        Returns:
        the listener previously associated with this class (possibly null), or null if there was no previous entry.

      • getListener

        <L extends EvaluationContext.Listener> L getListener​(Class<L> listenerType)
        Returns the listener the specified class is mapped to. This will only return a value that was bound to this specific class, not a value that may have been bound to a subtype.
        Parameters:
        listenerType - listener type, used as key to retrieve the listener registered with this type with putListener(Class, Listener)
        Returns:
        the listener associated with this class, or null if no entry for this class is present