From a2592b21861882e07388f9a6ea501c9995be6665 Mon Sep 17 00:00:00 2001
From: Robert Varga <robert.varga@pantheon.tech>
Date: Sun, 25 Oct 2020 16:17:08 +0100
Subject: [PATCH] Clarify DOMQueryEvaluator API

DOMQueryEvaluator has two modes of operation, each useful on its
own. Separate the two and document them.

JIRA: MDSAL-605
Change-Id: I6bc93b7098a18dc8d5c5886234fc0cf90772d15b
Signed-off-by: Robert Varga <robert.varga@pantheon.tech>
---
 .../adapter/query/SimpleQueryExecutor.java    |  2 +-
 .../dom/spi/query/DOMQueryEvaluator.java      | 41 +++++++++++++++----
 2 files changed, 33 insertions(+), 10 deletions(-)

diff --git a/binding/mdsal-binding-dom-adapter/src/main/java/org/opendaylight/mdsal/binding/dom/adapter/query/SimpleQueryExecutor.java b/binding/mdsal-binding-dom-adapter/src/main/java/org/opendaylight/mdsal/binding/dom/adapter/query/SimpleQueryExecutor.java
index 608dcb3265..776301d7b7 100644
--- a/binding/mdsal-binding-dom-adapter/src/main/java/org/opendaylight/mdsal/binding/dom/adapter/query/SimpleQueryExecutor.java
+++ b/binding/mdsal-binding-dom-adapter/src/main/java/org/opendaylight/mdsal/binding/dom/adapter/query/SimpleQueryExecutor.java
@@ -47,7 +47,7 @@ public final class SimpleQueryExecutor implements QueryExecutor {
     public <T extends @NonNull DataObject> QueryResult<T> executeQuery(final QueryExpression<T> query) {
         checkArgument(query instanceof DOMQueryLike, "Unsupported expression %s", query);
         final DOMQuery domQuery = ((DOMQueryLike) query).asDOMQuery();
-        return new DefaultQueryResult<>(codec, DOMQueryEvaluator.evaluate(domQuery, root));
+        return new DefaultQueryResult<>(codec, DOMQueryEvaluator.evaluateOnRoot(domQuery, root));
     }
 
     public static @NonNull Builder builder(final BindingCodecTree codec) {
diff --git a/dom/mdsal-dom-spi/src/main/java/org/opendaylight/mdsal/dom/spi/query/DOMQueryEvaluator.java b/dom/mdsal-dom-spi/src/main/java/org/opendaylight/mdsal/dom/spi/query/DOMQueryEvaluator.java
index 09b2a8a032..0a38354c50 100644
--- a/dom/mdsal-dom-spi/src/main/java/org/opendaylight/mdsal/dom/spi/query/DOMQueryEvaluator.java
+++ b/dom/mdsal-dom-spi/src/main/java/org/opendaylight/mdsal/dom/spi/query/DOMQueryEvaluator.java
@@ -33,26 +33,49 @@ public final class DOMQueryEvaluator {
 
     }
 
-    public static List<? extends Entry<YangInstanceIdentifier, NormalizedNode<?, ?>>> evaluate(final DOMQuery query,
-            final NormalizedNode<?, ?> root) {
+    /**
+     * Evaluate {@link DOMQuery} on its data element. The element is expected to correspond to
+     * {@link DOMQuery#getRoot()}.
+     *
+     * @param query Query to execute
+     * @param queryRoot Query root object
+     * @return Result of evaluation
+     * @throws NullPointerException if any argument is null
+     */
+    public static List<? extends Entry<YangInstanceIdentifier, NormalizedNode<?, ?>>> evaluateOn(final DOMQuery query,
+            final NormalizedNode<?, ?> queryRoot) {
         final YangInstanceIdentifier path = query.getSelect();
-        return path.isEmpty() ? evalSingle(root, query)
-                : evalPath(new ArrayDeque<>(path.getPathArguments()), root, query);
+        return path.isEmpty() ? evalSingle(queryRoot, query)
+            : evalPath(new ArrayDeque<>(path.getPathArguments()), queryRoot, query);
     }
 
-    private static List<? extends Entry<YangInstanceIdentifier, NormalizedNode<?, ?>>> evalPath(
-            final ArrayDeque<PathArgument> remaining, final NormalizedNode<?,?> data, final DOMQuery query) {
-        NormalizedNode<?, ?> evalRoot = data;
+    /**
+     * Evaluate {@link DOMQuery} on a conceptual root. The element is expected to correspond to the conceptual data tree
+     * root. This method will first find the {@link DOMQuery#getRoot()} and then defer to
+     * {@link #evaluateOn(DOMQuery, NormalizedNode)}.
+     *
+     * @param query Query to execute
+     * @param root Conceptual root object
+     * @return Result of evaluation
+     * @throws NullPointerException if any argument is null
+     */
+    public static List<? extends Entry<YangInstanceIdentifier, NormalizedNode<?, ?>>> evaluateOnRoot(
+            final DOMQuery query, final NormalizedNode<?, ?> root) {
+        NormalizedNode<?, ?> evalRoot = root;
         for (PathArgument arg : query.getRoot().getPathArguments()) {
-            final Optional<NormalizedNode<?, ?>> next = NormalizedNodes.findNode(data, arg);
+            final Optional<NormalizedNode<?, ?>> next = NormalizedNodes.findNode(root, arg);
             if (next.isEmpty()) {
                 return ImmutableList.of();
             }
             evalRoot = next.orElseThrow();
         }
+        return evaluateOn(query, evalRoot);
+    }
 
+    private static List<? extends Entry<YangInstanceIdentifier, NormalizedNode<?, ?>>> evalPath(
+            final ArrayDeque<PathArgument> remaining, final NormalizedNode<?,?> data, final DOMQuery query) {
         final List<Entry<YangInstanceIdentifier, NormalizedNode<?, ?>>> result = new ArrayList<>();
-        evalPath(result, query.getRoot(), remaining, evalRoot, query);
+        evalPath(result, query.getRoot(), remaining, data, query);
         return result;
     }
 
-- 
2.36.6