Define the concept of unresolved QName

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

diff --git a/yang/yang-xpath-api/src/main/java/org/opendaylight/yangtools/yang/xpath/api/YangXPathExpression.java b/yang/yang-xpath-api/src/main/java/org/opendaylight/yangtools/yang/xpath/api/YangXPathExpression.java
index da7ac0068fa3037ba012850e25f28ccfd2b487ca..3d7dc728086d275b2aef2609544aa48624ee5b75 100644 (file)
--- a/yang/yang-xpath-api/src/main/java/org/opendaylight/yangtools/yang/xpath/api/YangXPathExpression.java
+++ b/yang/yang-xpath-api/src/main/java/org/opendaylight/yangtools/yang/xpath/api/YangXPathExpression.java
@@ -11,14 +11,52 @@ import com.google.common.annotations.Beta;
 import javax.xml.xpath.XPathExpressionException;
 import org.opendaylight.yangtools.concepts.Immutable;
 import org.opendaylight.yangtools.yang.common.QName;
+import org.opendaylight.yangtools.yang.common.QualifiedQName;
+import org.opendaylight.yangtools.yang.common.UnqualifiedQName;
 
 /**
- * An XPath expression.
+ * An XPath expression. This interface defines a parsed representation of an XPath defined in a YANG context, as
+ * specified in <a href="https://tools.ietf.org/html/rfc7950#section-6.4">RFC7950, Section 6.4</a>.
+ *
+ * <p>
+ * The specification along with rules for {@code path} statement evaluation rules end up defining four incremental
+ * levels to which an XPath expression can be bound:
+ * <ul>
+ * <li>Unbound Expressions, which is a essentially a parse tree. No namespace binding has been performed, i.e. all
+ *     node identifiers are in {@link QualifiedQName} or {@link UnqualifiedQName} form. This level is typically not used
+ *     when dealing with YANG models directly, but can be useful for validating a String conforms to XPath syntax.
+ * </li>
+ * <li>Qualified-bound Expressions, where all {@link QualifiedQName}s are resolved and bound to {@link QName}s, but
+ *     {@link UnqualifiedQName}s are still present. This level corresponds to how far a YANG parser can interpret XPath
+ *     expressions defined in {@code typedef} statements and statements which are not fully instantiated, i.e. are
+ *     descendants of a {@code grouping} statement.
+ * </li>
+ * <li>Namespace-bound Expressions, where all node identifier references are resolved to {@link QName}s. This level
+ *     corresponds to how far a YANG parser can interpret XPath expressions at their place of instantiation, either in
+ *     the data tree or an {@code action}/@{code rpc}/{@code notification} or similar context.
+ * </li>
+ * <li>Context-bound Expressions, where the expression is bound to a {code context node}, i.e. {@code current()}
+ *     function result is know. This API does not handle this state, as it is inherently bound to a particular data
+ *     object model.
+ * </li>
+ * </ul>
  *
  * @author Robert Varga
  */
 @Beta
 public interface YangXPathExpression extends Immutable {
+    /**
+     * A Qualified-bound expression. All {@link QualifiedQName}s are eliminated and replaced with {@link QName}s.
+     */
+    interface QualifiedBound extends YangXPathExpression {
+
+    }
+
+    interface UnqualifiedBound extends QualifiedBound {
+        @Override
+        YangQNameExpr.Resolved interpretAsQName(YangLiteralExpr expr) throws XPathExpressionException;
+    }
+
     /**
      * Return the root {@link YangExpr}.
      *