X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;f=yang%2Fyang-xpath-api%2Fsrc%2Fmain%2Fjava%2Forg%2Fopendaylight%2Fyangtools%2Fyang%2Fxpath%2Fapi%2FYangXPathExpression.java;fp=yang%2Fyang-xpath-api%2Fsrc%2Fmain%2Fjava%2Forg%2Fopendaylight%2Fyangtools%2Fyang%2Fxpath%2Fapi%2FYangXPathExpression.java;h=3d7dc728086d275b2aef2609544aa48624ee5b75;hb=8b9ebd167b78bf49ba5dfa28105a2cba4c9e4f67;hp=da7ac0068fa3037ba012850e25f28ccfd2b487ca;hpb=933099fc2dd0cb42de89e69d90113d84f779b542;p=yangtools.git

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 da7ac0068f..3d7dc72808 100644
--- 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}.
      *