yang/yang-xpath-api/src/main/java/org/opendaylight/yangtools/yang/xpath/api/YangXPathExpression.java

   1 /*
   2  * Copyright (c) 2018 Pantheon Technologies, s.r.o.  All rights reserved.
   3  *
   4  * This program and the accompanying materials are made available under the
   5  * terms of the Eclipse Public License v1.0 which accompanies this distribution,
   6  * and is available at http://www.eclipse.org/legal/epl-v10.html
   7  */
   8 package org.opendaylight.yangtools.yang.xpath.api;
   9
  10 import com.google.common.annotations.Beta;
  11 import javax.xml.xpath.XPathExpressionException;
  12 import org.opendaylight.yangtools.concepts.Immutable;
  13 import org.opendaylight.yangtools.yang.common.QName;
  14 import org.opendaylight.yangtools.yang.common.QualifiedQName;
  15 import org.opendaylight.yangtools.yang.common.UnqualifiedQName;
  16 import org.opendaylight.yangtools.yang.common.YangVersion;
  17
  18 /**
  19  * An XPath expression. This interface defines a parsed representation of an XPath defined in a YANG context, as
  20  * specified in <a href="https://tools.ietf.org/html/rfc7950#section-6.4">RFC7950, Section 6.4</a>.
  21  *
  22  * <p>
  23  * The specification along with rules for {@code path} statement evaluation rules end up defining four incremental
  24  * levels to which an XPath expression can be bound:
  25  * <ul>
  26  * <li>Unbound Expressions, which is a essentially a parse tree. No namespace binding has been performed, i.e. all
  27  *     node identifiers are in {@link QualifiedQName} or {@link UnqualifiedQName} form. This level is typically not used
  28  *     when dealing with YANG models directly, but can be useful for validating a String conforms to XPath syntax.
  29  * </li>
  30  * <li>Qualified-bound Expressions, where all {@link QualifiedQName}s are resolved and bound to {@link QName}s, but
  31  *     {@link UnqualifiedQName}s are still present. This level corresponds to how far a YANG parser can interpret XPath
  32  *     expressions defined in {@code typedef} statements and statements which are not fully instantiated, i.e. are
  33  *     descendants of a {@code grouping} statement.
  34  * </li>
  35  * <li>Namespace-bound Expressions, where all node identifier references are resolved to {@link QName}s. This level
  36  *     corresponds to how far a YANG parser can interpret XPath expressions at their place of instantiation, either in
  37  *     the data tree or an {@code action}/@{code rpc}/{@code notification} or similar context.
  38  * </li>
  39  * <li>Context-bound Expressions, where the expression is bound to a {code context node}, i.e. {@code current()}
  40  *     function result is know. This API does not handle this state, as it is inherently bound to a particular data
  41  *     object model.
  42  * </li>
  43  * </ul>
  44  *
  45  * @author Robert Varga
  46  */
  47 @Beta
  48 public interface YangXPathExpression extends Immutable {
  49     /**
  50      * A Qualified-bound expression. All {@link QualifiedQName}s are eliminated and replaced with {@link QName}s.
  51      */
  52     interface QualifiedBound extends YangXPathExpression {
  53
  54     }
  55
  56     interface UnqualifiedBound extends QualifiedBound {
  57         @Override
  58         YangQNameExpr.Resolved interpretAsQName(YangLiteralExpr expr) throws XPathExpressionException;
  59     }
  60
  61     /**
  62      * Return the root {@link YangExpr}.
  63      *
  64      * @return Root expression.
  65      */
  66     YangExpr getRootExpr();
  67
  68     /**
  69      * Return the {@link YangXPathMathMode} used in this expression. All {@link YangNumberExpr} objects used by this
  70      * expression are expected to be handled by this mode's {@link YangXPathMathSupport}.
  71      *
  72      * @return YangXPathMathMode
  73      */
  74     YangXPathMathMode getMathMode();
  75
  76     /**
  77      * Return the minimum YangVersion runtime required to interpret this expression. The default implementation returns
  78      * {@link YangVersion#VERSION_1_1}. Implementations are encouraged to provide a less conservative estimate.
  79      *
  80      * @return YangVersion runtime version compatibility level required to accurately interpret this expression.
  81      */
  82     // FIXME: 5.0.0: make this method non-default.
  83     default YangVersion getYangVersion() {
  84         return YangVersion.VERSION_1_1;
  85     }
  86
  87     /**
  88      * Attempt to interpret a {@link YangLiteralExpr} referenced by this expression as a {@link QName}. This method
  89      * is required to perform late value binding of the expression when the literal needs to be interpreted as
  90      * a reference to an {@code identity}.
  91      *
  92      * <p>
  93      * The syntax of expr is required to conform to
  94      * <a href="https://www.w3.org/TR/REC-xml-names/#NT-QName">XML QName format</a>, as further restricted by
  95      * <a href="https://tools.ietf.org/html/rfc7950#section-9.10.3">YANG {@code identityref} Lexical Representation</a>.
  96      *
  97      * <p>
  98      * Unfortunately we do not know when a literal will need to be interpreted in this way, as that can only be known
  99      * at evaluation.
 100      *
 101      * @param expr Literal to be reinterpreted
 102      * @return YangQNameExpr result of interpretation
 103      * @throws XPathExpressionException when the literal cannot be interpreted as a QName
 104      */
 105     YangQNameExpr interpretAsQName(YangLiteralExpr expr) throws XPathExpressionException;
 106
 107     // FIXME: this really should be YangInstanceIdentifier without AugmentationIdentifier. Implementations are
 108     //        strongly encouraged to validate it as such.
 109     YangLocationPath interpretAsInstanceIdentifier(YangLiteralExpr expr) throws XPathExpressionException;
 110 }