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 224874d67917aed5449e3c69f0da41dd4d92ec35..7325f42f50dbe1f45bad1550a631811b1af96f7f 100644 (file)
--- 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 4f690f023a00fec43fbd863d5bc22ecf73a68879..31aa062be8b630ccf55b82c817ca7f50c0de95a9 100644 (file)
--- 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 7bc58a43b66582592de98015f05621c2eb3885d1..4704fc7a33c4e4f90bfb891190e89083313dae12 100644 (file)
--- 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();
 }