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

   1 /*
   2  * Copyright (c) 2021 PANTHEON.tech, s.r.o. and others.  All rights reserved.
   3  *
   4  * This program and the accompanying materials are made available under the
   5  * terms of the Eclipse Public License v1.0 which accompanies this distribution,
   6  * and is available at http://www.eclipse.org/legal/epl-v10.html
   7  */
   8 package org.opendaylight.yangtools.yang.parser.api;
   9
  10 import static java.util.Objects.requireNonNull;
  11
  12 import com.google.common.annotations.Beta;
  13 import com.google.common.base.MoreObjects;
  14 import java.util.Objects;
  15 import org.eclipse.jdt.annotation.NonNullByDefault;
  16 import org.eclipse.jdt.annotation.Nullable;
  17 import org.opendaylight.yangtools.concepts.Immutable;
  18 import org.opendaylight.yangtools.concepts.Mutable;
  19 import org.opendaylight.yangtools.yang.model.api.meta.DeclarationReference;
  20 import org.opendaylight.yangtools.yang.model.api.meta.DeclaredStatement;
  21
  22 /**
  23  * A configuration of {@link YangParser} wiring for use with {@link YangParserFactory}.
  24  */
  25 @NonNullByDefault
  26 public final class YangParserConfiguration implements Immutable {
  27     /**
  28      * System-wide default configuration.
  29      */
  30     public static final YangParserConfiguration DEFAULT = builder().build();
  31
  32     private final ImportResolutionMode importResolutionMode;
  33     private final boolean retainDeclarationReferences;
  34     private final boolean warnForUnkeyedLists;
  35
  36     private YangParserConfiguration(final ImportResolutionMode importResolutionMode,
  37             final boolean retainDeclarationReferences, final boolean warnForUnkeyedLists) {
  38         this.importResolutionMode = requireNonNull(importResolutionMode);
  39         this.retainDeclarationReferences = retainDeclarationReferences;
  40         this.warnForUnkeyedLists = warnForUnkeyedLists;
  41     }
  42
  43     @Beta
  44     public ImportResolutionMode importResolutionMode() {
  45         return importResolutionMode;
  46     }
  47
  48     /**
  49      * Return {@code true} if {@link DeclarationReference} to source location in the final parser product, notably
  50      * making {@link DeclaredStatement#declarationReference()} available.
  51      *
  52      * @return {@code true} if declaration references should be retained
  53      */
  54     public boolean retainDeclarationReferences() {
  55         return retainDeclarationReferences;
  56     }
  57
  58     /**
  59      * Issue a warning when a {@code list} statement without a {@code key} statement is found in the
  60      * {@code config true} part of the schema tree. Such statements run contrary to
  61      * <a href="https://www.rfc-editor.org/rfc/rfc7950.html#section-7.8.2">RFC7950</a>, but are readily supported
  62      * by OpenDaylight infrastructure.
  63      *
  64      * @return {@code true} if non-compliant {@code list} statements should be reported
  65      */
  66     public boolean warnForUnkeyedLists() {
  67         return warnForUnkeyedLists;
  68     }
  69
  70     @Override
  71     public int hashCode() {
  72         return Objects.hash(importResolutionMode, retainDeclarationReferences);
  73     }
  74
  75     @Override
  76     public boolean equals(final @Nullable Object obj) {
  77         if (this == obj) {
  78             return true;
  79         }
  80         if (!(obj instanceof YangParserConfiguration)) {
  81             return false;
  82         }
  83         final YangParserConfiguration other = (YangParserConfiguration) obj;
  84         return importResolutionMode == other.importResolutionMode
  85             && retainDeclarationReferences == other.retainDeclarationReferences;
  86     }
  87
  88     @Override
  89     public String toString() {
  90         return MoreObjects.toStringHelper(this)
  91             .add("importResolution", importResolutionMode)
  92             .add("declarationReferences", retainDeclarationReferences)
  93             .toString();
  94     }
  95
  96     /**
  97      * Return a new {@link Builder} initialized to default configuration.
  98      *
  99      * @return A new builder
 100      */
 101     public static Builder builder() {
 102         return new Builder();
 103     }
 104
 105     public static final class Builder implements Mutable {
 106         private ImportResolutionMode importResolutionMode = ImportResolutionMode.DEFAULT;
 107         private boolean retainDeclarationReferences;
 108         // FIXME: YANGTOOLS-1423: default to false
 109         private boolean warnForUnkeyedLists = true;
 110
 111         private Builder() {
 112             // Hidden on purpose
 113         }
 114
 115         /**
 116          * Return a {@link YangParserConfiguration} initialized with contents of this builder.
 117          *
 118          * @return A YangParserConfiguration
 119          */
 120         public YangParserConfiguration build() {
 121             return new YangParserConfiguration(importResolutionMode, retainDeclarationReferences, warnForUnkeyedLists);
 122         }
 123
 124         @Beta
 125         public Builder importResolutionMode(final ImportResolutionMode newImportResolutionMode) {
 126             importResolutionMode = requireNonNull(newImportResolutionMode);
 127             return this;
 128         }
 129
 130         /**
 131          * Retain {@link DeclarationReference} to source location in the final parser product. This option results in
 132          * quite significant memory overhead for storage of {@link DeclaredStatement}, but makes
 133          * {@link DeclaredStatement#declarationReference()} available, which is useful in certain scenarios, for example
 134          * YANG editors.
 135          *
 136          * <p>
 137          * This option is disabled by default.
 138          *
 139          * @param newRetainDeclarationReferences {@code true} if declaration references should be retained
 140          * @return This builder
 141          */
 142         public Builder retainDeclarationReferences(final boolean newRetainDeclarationReferences) {
 143             retainDeclarationReferences = newRetainDeclarationReferences;
 144             return this;
 145         }
 146
 147         /**
 148          * Issue a warning when a {@code list} statement without a {@code key} statement is found in the
 149          * {@code config true} part of the schema tree. Such statements run contrary to
 150          * <a href="https://www.rfc-editor.org/rfc/rfc7950.html#section-7.8.2">RFC7950</a>, but are readily supported
 151          * by OpenDaylight infrastructure.
 152          *
 153          * <p>
 154          * This option is enabled by default.
 155          *
 156          * @param newWarnForUnkeyedLists {@code true} if non-compliant {@code list} statements should be reported
 157          * @return This builder
 158          */
 159         public Builder warnForUnkeyedLists(final boolean newWarnForUnkeyedLists) {
 160             warnForUnkeyedLists = newWarnForUnkeyedLists;
 161             return this;
 162         }
 163     }
 164 }