Moderinize DeviateKind documentation

Expand the documentation to include a reference to RFC7950. Also
guarantee @NonNull return from getKeyword() and rename it to argument().
Provide static factory methods for acquiring an enum object for an
argument.

Change-Id: I290631863394545f7240eeb66eb5b6dd1090d5ea
Signed-off-by: Robert Varga <robert.varga@pantheon.tech>

diff --git a/model/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/DeviateKind.java b/model/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/DeviateKind.java
index d7a728007eda540af0e50f77d6574015220d3bae..c928a774c6432aea7bcc1ef6f31de196f7941fb9 100644 (file)
--- a/model/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/DeviateKind.java
+++ b/model/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/DeviateKind.java
@@ -5,32 +5,97 @@
  * 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.model.api;
 
 import static java.util.Objects.requireNonNull;
 
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+
 /**
- * Enum describing YANG deviation 'deviate' statement. It defines how the
- * device's implementation of the target node deviates from its original
- * definition.
+ * Enumeration describing {@code deviate}
+ * <a href="https://www.rfc-editor.org/rfc/rfc7950.html#section-7.20.3.2">YANG statement</a> argument. It defines how
+ * the server implementation of the target node deviates from its original definition.
  */
+@NonNullByDefault
 public enum DeviateKind {
+    /**
+     * Target node is not implemented by the server.
+     */
+    NOT_SUPPORTED("not-supported"),
+    /**
+     * Server implements target node with additional properties.
+     */
+    ADD("add"),
+    /**
+     * Server implements target node with different properties.
+     */
+    REPLACE("replace"),
+    /**
+     * Server implements target node without some properties.
+     */
+    DELETE("delete");
 
-    NOT_SUPPORTED("not-supported"), ADD("add"), REPLACE("replace"), DELETE("delete");
+    private final String argument;
 
-    private final String keyword;
+    DeviateKind(final String argumentValue) {
+        argument = requireNonNull(argumentValue);
+    }
 
-    DeviateKind(final String keyword) {
-        this.keyword = requireNonNull(keyword);
+    /**
+     * Returns the YANG {@code deviate} statement argument value corresponding to this object.
+     *
+     * @return String that corresponds to the YANG {@code deviate} statement argument
+     */
+    public String argument() {
+        return argument;
     }
 
     /**
      * Returns the YANG keyword corresponding to this object.
      *
-     * @return String that corresponds to the yang keyword.
+     * @return String that corresponds to the YANG keyword.
+     * @deprecated Use {@link #argument} instead.
      */
+    @Deprecated(since = "9.0.0", forRemoval = true)
     public String getKeyword() {
-        return keyword;
+        return argument;
+    }
+
+    /**
+     * Return a {@link DeviateKind} for specified {@code deviate} statement argument. This methods returns a
+     * {@code null} for illegal values. See {@link #ofArgument(String)} for a version which returns non-null and throws
+     * an exception for illegal values.
+     *
+     * @param argument {@code deviate} statement argument
+     * @return An enumeration value, or {@code null} if specified argument is not valid
+     * @throws NullPointerException if {@code argument} is {@code null}
+     */
+    public static @Nullable DeviateKind forArgument(final String argument) {
+        return switch (argument) {
+            case "not-supported" -> NOT_SUPPORTED;
+            case "add" -> ADD;
+            case "replace" -> REPLACE;
+            case "delete" -> DELETE;
+            default -> null;
+        };
+    }
+
+    /**
+     * Return a {@link DeviateKind} for specified {@code deviate} statement argument. This methods throws an exception
+     * for illegal values. See {@link #forArgument(String)} for a version which returns a {@code null} instead for
+     * illegal values.
+     *
+     * @param argument {@code deviate} statement argument
+     * @return An enumeration value
+     * @throws NullPointerException if {@code argument} is {@code null}
+     * @throws IllegalArgumentException if {@code argument} is not a valid {@code deviate} statement argument
+     */
+    public static DeviateKind ofArgument(final String argument) {
+        final var ret = forArgument(argument);
+        if (ret == null) {
+            throw new IllegalArgumentException("\"" + argument + "\" is not a valid deviate statement argument");
+        }
+        return ret;
     }
 }

diff --git a/parser/yang-parser-rfc7950/src/main/java/org/opendaylight/yangtools/yang/parser/rfc7950/stmt/deviate/AbstractDeviateStatementSupport.java b/parser/yang-parser-rfc7950/src/main/java/org/opendaylight/yangtools/yang/parser/rfc7950/stmt/deviate/AbstractDeviateStatementSupport.java
index 11dc737e53faf71429dfb4bc795b894a75fc0a1f..d6903c5d6e66e2516a600191a84c465706342e0f 100644 (file)
--- a/parser/yang-parser-rfc7950/src/main/java/org/opendaylight/yangtools/yang/parser/rfc7950/stmt/deviate/AbstractDeviateStatementSupport.java
+++ b/parser/yang-parser-rfc7950/src/main/java/org/opendaylight/yangtools/yang/parser/rfc7950/stmt/deviate/AbstractDeviateStatementSupport.java
@@ -8,12 +8,9 @@
 package org.opendaylight.yangtools.yang.parser.rfc7950.stmt.deviate;
 
 import com.google.common.collect.ImmutableList;
-import com.google.common.collect.ImmutableMap;
 import com.google.common.collect.ImmutableSet;
 import com.google.common.collect.Iterables;
-import com.google.common.collect.Maps;
 import com.google.common.collect.SetMultimap;
-import java.util.Arrays;
 import java.util.Collection;
 import java.util.List;
 import java.util.Objects;
@@ -94,9 +91,6 @@ abstract class AbstractDeviateStatementSupport
                 .addOptional(YangStmtMapping.UNITS)
                 .build();
 
-    private static final ImmutableMap<String, DeviateKind> KEYWORD_TO_DEVIATE_MAP =
-            Maps.uniqueIndex(Arrays.asList(DeviateKind.values()), DeviateKind::getKeyword);
-
     private static final ImmutableSet<YangStmtMapping> SINGLETON_STATEMENTS = ImmutableSet.of(
             YangStmtMapping.UNITS, YangStmtMapping.CONFIG, YangStmtMapping.MANDATORY,
             YangStmtMapping.MIN_ELEMENTS, YangStmtMapping.MAX_ELEMENTS);
@@ -112,7 +106,7 @@ abstract class AbstractDeviateStatementSupport
 
     @Override
     public final DeviateKind parseArgumentValue(final StmtContext<?, ?, ?> ctx, final String value) {
-        return SourceException.throwIfNull(KEYWORD_TO_DEVIATE_MAP.get(value), ctx,
+        return SourceException.throwIfNull(DeviateKind.forArgument(value), ctx,
             "String '%s' is not valid deviate argument", value);
     }