Add a knob to control warnings about unkeyed lists

[yangtools.git] / parser / yang-parser-api / src / main / java / org / opendaylight / yangtools / yang / parser / api / YangParserConfiguration.java

diff --git a/parser/yang-parser-api/src/main/java/org/opendaylight/yangtools/yang/parser/api/YangParserConfiguration.java b/parser/yang-parser-api/src/main/java/org/opendaylight/yangtools/yang/parser/api/YangParserConfiguration.java
index 317159120122a1b54e57c240a1ca2fdd77d91be1..3343407dd11476d3ca4297eb987ff5907a738f39 100644 (file)
--- a/parser/yang-parser-api/src/main/java/org/opendaylight/yangtools/yang/parser/api/YangParserConfiguration.java
+++ b/parser/yang-parser-api/src/main/java/org/opendaylight/yangtools/yang/parser/api/YangParserConfiguration.java
@@ -15,6 +15,9 @@ import java.util.Objects;
 import org.eclipse.jdt.annotation.NonNullByDefault;
 import org.eclipse.jdt.annotation.Nullable;
 import org.opendaylight.yangtools.concepts.Immutable;
+import org.opendaylight.yangtools.concepts.Mutable;
+import org.opendaylight.yangtools.yang.model.api.meta.DeclarationReference;
+import org.opendaylight.yangtools.yang.model.api.meta.DeclaredStatement;
 
 /**
  * A configuration of {@link YangParser} wiring for use with {@link YangParserFactory}.
@@ -28,11 +31,13 @@ public final class YangParserConfiguration implements Immutable {
 
     private final ImportResolutionMode importResolutionMode;
     private final boolean retainDeclarationReferences;
+    private final boolean warnForUnkeyedLists;
 
     private YangParserConfiguration(final ImportResolutionMode importResolutionMode,
-            final boolean retainDeclarationReferences) {
+            final boolean retainDeclarationReferences, final boolean warnForUnkeyedLists) {
         this.importResolutionMode = requireNonNull(importResolutionMode);
         this.retainDeclarationReferences = retainDeclarationReferences;
+        this.warnForUnkeyedLists = warnForUnkeyedLists;
     }
 
     @Beta
@@ -40,10 +45,28 @@ public final class YangParserConfiguration implements Immutable {
         return importResolutionMode;
     }
 
+    /**
+     * Return {@code true} if {@link DeclarationReference} to source location in the final parser product, notably
+     * making {@link DeclaredStatement#declarationReference()} available.
+     *
+     * @return {@code true} if declaration references should be retained
+     */
     public boolean retainDeclarationReferences() {
         return retainDeclarationReferences;
     }
 
+    /**
+     * Issue a warning when a {@code list} statement without a {@code key} statement is found in the
+     * {@code config true} part of the schema tree. Such statements run contrary to
+     * <a href="https://www.rfc-editor.org/rfc/rfc7950.html#section-7.8.2">RFC7950</a>, but are readily supported
+     * by OpenDaylight infrastructure.
+     *
+     * @return {@code true} if non-compliant {@code list} statements should be reported
+     */
+    public boolean warnForUnkeyedLists() {
+        return warnForUnkeyedLists;
+    }
+
     @Override
     public int hashCode() {
         return Objects.hash(importResolutionMode, retainDeclarationReferences);
@@ -70,31 +93,71 @@ public final class YangParserConfiguration implements Immutable {
             .toString();
     }
 
+    /**
+     * Return a new {@link Builder} initialized to default configuration.
+     *
+     * @return A new builder
+     */
     public static Builder builder() {
         return new Builder();
     }
 
-    public static final class Builder implements org.opendaylight.yangtools.concepts.Builder<YangParserConfiguration> {
+    public static final class Builder implements Mutable {
         private ImportResolutionMode importResolutionMode = ImportResolutionMode.DEFAULT;
-        private boolean retainDeclarationReferences = false;
+        private boolean retainDeclarationReferences;
+        // FIXME: YANGTOOLS-1423: default to false
+        private boolean warnForUnkeyedLists = true;
 
         private Builder() {
             // Hidden on purpose
         }
 
-        @Override
+        /**
+         * Return a {@link YangParserConfiguration} initialized with contents of this builder.
+         *
+         * @return A YangParserConfiguration
+         */
         public YangParserConfiguration build() {
-            return new YangParserConfiguration(importResolutionMode, retainDeclarationReferences);
+            return new YangParserConfiguration(importResolutionMode, retainDeclarationReferences, warnForUnkeyedLists);
         }
 
         @Beta
         public Builder importResolutionMode(final ImportResolutionMode newImportResolutionMode) {
-            this.importResolutionMode = requireNonNull(newImportResolutionMode);
+            importResolutionMode = requireNonNull(newImportResolutionMode);
             return this;
         }
 
+        /**
+         * Retain {@link DeclarationReference} to source location in the final parser product. This option results in
+         * quite significant memory overhead for storage of {@link DeclaredStatement}, but makes
+         * {@link DeclaredStatement#declarationReference()} available, which is useful in certain scenarios, for example
+         * YANG editors.
+         *
+         * <p>
+         * This option is disabled by default.
+         *
+         * @param newRetainDeclarationReferences {@code true} if declaration references should be retained
+         * @return This builder
+         */
         public Builder retainDeclarationReferences(final boolean newRetainDeclarationReferences) {
-            this.retainDeclarationReferences = newRetainDeclarationReferences;
+            retainDeclarationReferences = newRetainDeclarationReferences;
+            return this;
+        }
+
+        /**
+         * Issue a warning when a {@code list} statement without a {@code key} statement is found in the
+         * {@code config true} part of the schema tree. Such statements run contrary to
+         * <a href="https://www.rfc-editor.org/rfc/rfc7950.html#section-7.8.2">RFC7950</a>, but are readily supported
+         * by OpenDaylight infrastructure.
+         *
+         * <p>
+         * This option is enabled by default.
+         *
+         * @param newWarnForUnkeyedLists {@code true} if non-compliant {@code list} statements should be reported
+         * @return This builder
+         */
+        public Builder warnForUnkeyedLists(final boolean newWarnForUnkeyedLists) {
+            warnForUnkeyedLists = newWarnForUnkeyedLists;
             return this;
         }
     }