From: Robert Varga <robert.varga@pantheon.tech>
Date: Fri, 5 Feb 2021 08:29:49 +0000 (+0100)
Subject: Clarify Unknown/Unrecognized statement semantics
X-Git-Tag: v7.0.0~210
X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=commitdiff_plain;h=b5f891aaf9e49b000191a9b7d71a7d192b8e4f72;p=yangtools.git

Clarify Unknown/Unrecognized statement semantics

Unknown(Effective)Statement is really a remnant of the SchemaNode
approach to statement categorization. It is useful for bridging
from UnknownSchemaNode, but has not other use and we should
eventually be removing it.

UnrecognizedStatement, on the other hand, is here to stay as it
provides a DeclaredStatement anchor for use of extensions we do not
recognize.

JIRA: YANGTOOLS-1196
Change-Id: I54a8412d4ee0c60ee2cc6108973566e08121c201
Signed-off-by: Robert Varga <robert.varga@pantheon.tech>
---

diff --git a/yang/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/stmt/UnknownEffectiveStatement.java b/yang/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/stmt/UnknownEffectiveStatement.java
index 224874d679..7325f42f50 100644
--- a/yang/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/stmt/UnknownEffectiveStatement.java
+++ b/yang/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/stmt/UnknownEffectiveStatement.java
@@ -8,10 +8,19 @@
 package org.opendaylight.yangtools.yang.model.api.stmt;
 
 import com.google.common.annotations.Beta;
+import org.opendaylight.yangtools.yang.common.Empty;
+import org.opendaylight.yangtools.yang.model.api.UnknownSchemaNode;
 import org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement;
 
+/**
+ * Effective counterpart to {@link UnknownStatement}. This interface exists only for the purposes of providing a bridge
+ * from {@link UnknownSchemaNode} to {@link EffectiveStatement} via {@link UnknownSchemaNode#asEffectiveStatement()}.
+ *
+ * @param <A> Argument type ({@link Empty} if statement does not have argument.)
+ * @param <D> Class representing declared version of this statement.
+ */
 @Beta
-// FIXME: evaluate usefulness of this
+// FIXME: remove this interface once UnknownSchemaNode is gone
 public interface UnknownEffectiveStatement<A, D extends UnknownStatement<A>> extends EffectiveStatement<A, D> {
 
 }
diff --git a/yang/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/stmt/UnknownStatement.java b/yang/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/stmt/UnknownStatement.java
index 4f690f023a..31aa062be8 100644
--- a/yang/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/stmt/UnknownStatement.java
+++ b/yang/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/stmt/UnknownStatement.java
@@ -18,8 +18,8 @@ import org.opendaylight.yangtools.yang.model.api.meta.DeclaredStatement;
  *
  * @param <A> Argument type ({@link Empty} if statement does not have argument.)
  */
-// FIXME: evaluate usefulness of this
 @Beta
+// FIXME: remove this interface once UnknownSchemaNode is gone
 public interface UnknownStatement<A> extends DeclaredStatement<A> {
 
 }
diff --git a/yang/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/stmt/UnrecognizedStatement.java b/yang/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/stmt/UnrecognizedStatement.java
index 7bc58a43b6..4704fc7a33 100644
--- a/yang/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/stmt/UnrecognizedStatement.java
+++ b/yang/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/stmt/UnrecognizedStatement.java
@@ -8,6 +8,7 @@
 package org.opendaylight.yangtools.yang.model.api.stmt;
 
 import com.google.common.annotations.Beta;
+import org.opendaylight.yangtools.yang.common.Empty;
 
 /**
  * Common interface for unrecognized unknown statements. An {@link UnrecognizedStatement} is an instance of a statement
@@ -20,5 +21,16 @@ import com.google.common.annotations.Beta;
  */
 @Beta
 public interface UnrecognizedStatement extends UnknownStatement<Object> {
-
+    /**
+     * {@inheritDoc}
+     *
+     * <p>
+     * This method can returns
+     * <ul>
+     *   <li>{@link String} if the statement has an argument</li>
+     *   <li>{@link Empty} if the statement does not have an argument</li>
+     * </ul>
+     */
+    @Override
+    Object argument();
 }