Expose ReusableStreamReceiver

ReusableImmutableNormalizedNodeStreamWriter has two properties
which are not inherently tied to it being bound to immutable nodes:
- it can have its state reset
- it exposes a NormalizedNode result of a streaming session

Expose these traits as ReusableStreamReceiver, so that users
can use the API rather than the implementation.

Change-Id: I841211c89520c4a5c67d436c8a49d719e8f7f1b7
Signed-off-by: Robert Varga <robert.varga@pantheon.tech>
(cherry picked from commit 9e66147b4a8167007e6d3479c449ab9944cce5f9)

diff --git a/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/stream/ReusableStreamReceiver.java b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/stream/ReusableStreamReceiver.java
new file mode 100644 (file)
index 0000000..ac13ccc
--- /dev/null
+++ b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/stream/ReusableStreamReceiver.java
@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) 2019 PANTHEON.tech, s.r.o. and others.  All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v1.0 which accompanies this distribution,
+ * and is available at http://www.eclipse.org/legal/epl-v10.html
+ */
+package org.opendaylight.yangtools.yang.data.api.schema.stream;
+
+import com.google.common.annotations.Beta;
+import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode;
+
+/**
+ * Utility marker interface for {@link NormalizedNodeStreamWriter} implementations which can be reused multiple times
+ * and can expose a {@link NormalizedNode} result of each complete streaming use.
+ *
+ * <p>
+ * An example of use would be:
+ * <pre>
+ *   ReusableStreamReceiver writer;
+ *   final NormalizedNode result;
+ *
+ *   try {
+ *       // pipe events into writer:
+ *       writer.startContainer(...);
+ *       ...
+ *
+ *       result = writer.getResult();
+ *   } finally {
+ *       writer.reset();
+ *   }
+ * </pre>
+ *
+ * <p>
+ * Note the writer should always be {@link #reset()} in a {@code finally} block, so that any streaming state is
+ * properly discarded.
+ */
+@Beta
+public interface ReusableStreamReceiver extends NormalizedNodeStreamWriter {
+    /**
+     * Acquire the result of the last streaming session.
+     *
+     * @return Result of streaming.
+     */
+    NormalizedNode<?, ?> getResult();
+
+    /**
+     * Reset this writer to initial state.
+     */
+    void reset();
+}

diff --git a/yang/yang-data-impl/src/main/java/org/opendaylight/yangtools/yang/data/impl/schema/ReusableImmutableNormalizedNodeStreamWriter.java b/yang/yang-data-impl/src/main/java/org/opendaylight/yangtools/yang/data/impl/schema/ReusableImmutableNormalizedNodeStreamWriter.java
index c9f7974eeaa4b50445e65072e8ff40f99cf7d3b3..25710269402e675d684353e0b6834b17ec273d8e 100644 (file)
--- a/yang/yang-data-impl/src/main/java/org/opendaylight/yangtools/yang/data/impl/schema/ReusableImmutableNormalizedNodeStreamWriter.java
+++ b/yang/yang-data-impl/src/main/java/org/opendaylight/yangtools/yang/data/impl/schema/ReusableImmutableNormalizedNodeStreamWriter.java
@@ -12,13 +12,15 @@ import static java.util.Objects.requireNonNull;
 import com.google.common.annotations.Beta;
 import org.eclipse.jdt.annotation.NonNull;
 import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode;
+import org.opendaylight.yangtools.yang.data.api.schema.stream.ReusableStreamReceiver;
 
 /**
  * A reusable variant of {@link ImmutableNormalizedNodeStreamWriter}. It can be reset into its base state and used for
  * multiple streaming sessions.
  */
 @Beta
-public final class ReusableImmutableNormalizedNodeStreamWriter extends ImmutableNormalizedNodeStreamWriter {
+public final class ReusableImmutableNormalizedNodeStreamWriter extends ImmutableNormalizedNodeStreamWriter
+        implements ReusableStreamReceiver {
     private final NormalizedNodeResultBuilder builder;
 
     private ReusableImmutableNormalizedNodeStreamWriter(final NormalizedNodeResultBuilder builder) {
@@ -30,11 +32,13 @@ public final class ReusableImmutableNormalizedNodeStreamWriter extends Immutable
         return new ReusableImmutableNormalizedNodeStreamWriter(new NormalizedNodeResultBuilder());
     }
 
+    @Override
     public void reset() {
         builder.result().reset();
         reset(builder);
     }
 
+    @Override
     public NormalizedNode<?, ?> getResult() {
         return builder.result().getResult();
     }