yang/yang-parser-spi/src/main/java/org/opendaylight/yangtools/yang/parser/spi/meta/EffectiveStmtCtx.java

   1 /*
   2  * Copyright (c) 2020 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.spi.meta;
   9
  10 import static com.google.common.base.Verify.verifyNotNull;
  11
  12 import com.google.common.annotations.Beta;
  13 import com.google.common.base.VerifyException;
  14 import org.eclipse.jdt.annotation.NonNull;
  15 import org.eclipse.jdt.annotation.Nullable;
  16 import org.opendaylight.yangtools.concepts.Immutable;
  17 import org.opendaylight.yangtools.yang.common.QName;
  18 import org.opendaylight.yangtools.yang.common.QNameModule;
  19 import org.opendaylight.yangtools.yang.model.api.DataSchemaNode;
  20 import org.opendaylight.yangtools.yang.model.api.SchemaNode;
  21 import org.opendaylight.yangtools.yang.model.api.SchemaNodeDefaults;
  22 import org.opendaylight.yangtools.yang.model.api.SchemaPath;
  23 import org.opendaylight.yangtools.yang.model.api.meta.DeclaredStatement;
  24 import org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement;
  25
  26 /**
  27  * Effective view of a {@link StmtContext} for the purposes of creating an {@link EffectiveStatement}.
  28  */
  29 @Beta
  30 public interface EffectiveStmtCtx extends CommonStmtCtx, StmtContextCompat, Immutable {
  31     /**
  32      * Return parent of this context, if there is one. All statements except for top-level source statements, such as
  33      * {@code module} and {@code submodule}.
  34      *
  35      * @return Parent context, or null if this statement is the root
  36      */
  37     @Nullable Parent effectiveParent();
  38
  39     /**
  40      * Return parent of this context.
  41      *
  42      * @return Parent context
  43      * @throws VerifyException if this context is already the root
  44      */
  45     default @NonNull Parent getEffectiveParent() {
  46         return verifyNotNull(effectiveParent(), "Attempted to access beyond root context");
  47     }
  48
  49     /**
  50      * Minimum amount of parent state required to build an accurate effective view of a particular child. Child state
  51      * is expressed as {@link Current}.
  52      */
  53     @Beta
  54     interface Parent extends EffectiveStmtCtx {
  55         /**
  56          * Effective {@code config} statement value.
  57          */
  58         @Beta
  59         enum EffectiveConfig {
  60             /**
  61              * We have an effective {@code config true} statement.
  62              */
  63             TRUE(Boolean.TRUE),
  64             /**
  65              * We have an effective {@code config false} statement.
  66              */
  67             FALSE(Boolean.FALSE),
  68             /**
  69              * We are in a context where {@code config} statements are ignored.
  70              */
  71             IGNORED(null),
  72             /**
  73              * We are in a context where {@code config} is not determined, such as within a {@code grouping}.
  74              */
  75             UNDETERMINED(null);
  76
  77             private final Boolean config;
  78
  79             EffectiveConfig(final @Nullable Boolean config) {
  80                 this.config = config;
  81             }
  82
  83             /**
  84              * Return this value as a {@link Boolean} for use with {@link DataSchemaNode#effectiveConfig()}.
  85              *
  86              * @return A boolean or null
  87              */
  88             public @Nullable Boolean asNullable() {
  89                 return config;
  90             }
  91         }
  92
  93         /**
  94          * Return the effective {@code config} statement value.
  95          *
  96          * @return This statement's effective config
  97          */
  98         @NonNull EffectiveConfig effectiveConfig();
  99
 100         // FIXME: 7.0.0: this is currently only used by AbstractTypeStatement
 101         @NonNull QNameModule effectiveNamespace();
 102
 103         /**
 104          * Return the effective path of this statement. This method is intended for use with statements which naturally
 105          * have a {@link QName} identifier and this identifier forms the ultimate step in their
 106          * {@link SchemaNode#getPath()}.
 107          *
 108          * <p>
 109          * Returned object conforms to {@link SchemaPathSupport}'s view of how these are to be handled. Users of this
 110          * method are expected to consult {@link SchemaNodeDefaults#extractQName(Immutable)} and
 111          * {@link SchemaNodeDefaults#extractPath(Object, Immutable)} to ensure correct implementation behaviour with
 112          * respect to {@link SchemaNode#getQName()} and {@link SchemaNode#getPath()} respectively.
 113          *
 114          * @return An {@link Immutable} effective path object
 115          */
 116         // FIXME: Remove this when SchemaNode.getPath() is removed. QName users will store getArgument() instead.
 117         default @NonNull Immutable effectivePath() {
 118             return SchemaPathSupport.toEffectivePath(getSchemaPath());
 119         }
 120
 121         /**
 122          * Return an optional-to-provide path for {@link SchemaNode#getPath()}. The result of this method is expected
 123          * to be consulted with {@link SchemaNodeDefaults#throwUnsupportedIfNull(Object, SchemaPath)} to get consistent
 124          * API behaviour.
 125          *
 126          * @return Potentially-null {@link SchemaPath}.
 127          */
 128         // FIXME: Remove this when SchemaNode.getPath() is removed
 129         default @Nullable SchemaPath optionalPath() {
 130             return SchemaPathSupport.toOptionalPath(getSchemaPath());
 131         }
 132
 133         /**
 134          * Return the {@link SchemaNode#getPath()} of this statement. Not all statements have a SchemaPath, in which
 135          * case null is returned.
 136          *
 137          * @return SchemaPath or null
 138          */
 139         // FIXME: Remove this when SchemaNode.getPath() is removed
 140         @Nullable SchemaPath schemaPath();
 141
 142         /**
 143          * Return the {@link SchemaNode#getPath()} of this statement, failing if it is not present.
 144          *
 145          * @return A SchemaPath.
 146          * @throws VerifyException if {@link #schemaPath()} returns null
 147          */
 148         // FIXME: Remove this when SchemaNode.getPath() is removed
 149         default @NonNull SchemaPath getSchemaPath() {
 150             return verifyNotNull(schemaPath(), "Missing path for %s", this);
 151         }
 152     }
 153
 154     /**
 155      * Minimum amount of state required to build an accurate effective view of a statement. This is a strict superset
 156      * of information available in {@link Parent}.
 157      *
 158      * @param <A> Argument type
 159      * @param <D> Class representing declared version of this statement
 160      */
 161     @Beta
 162     interface Current<A, D extends DeclaredStatement<A>> extends Parent, NamespaceStmtCtx, BoundStmtCtxCompat<A, D> {
 163
 164         @NonNull QName moduleName();
 165
 166         @Nullable EffectiveStatement<?, ?> original();
 167
 168         // FIXME: 7.0.0: this method should be moved to stmt.type in some shape or form
 169         @NonNull QName argumentAsTypeQName();
 170
 171         /**
 172          * Summon the <a href="https://en.wikipedia.org/wiki/Rabbit_of_Caerbannog">Rabbit of Caerbannog</a>.
 173          *
 174          * @param <E> Effective Statement representation
 175          * @return The {@code Legendary Black Beast of Arrrghhh}.
 176          */
 177         // FIXME: YANGTOOLS-1186: lob the Holy Hand Grenade of Antioch
 178         @Deprecated
 179         <E extends EffectiveStatement<A, D>> @NonNull StmtContext<A, D, E> caerbannog();
 180
 181         /**
 182          * Compare another context for equality of {@code getEffectiveParent().getSchemaPath()}, just in a safer manner.
 183          *
 184          * @param other Other {@link Current}
 185          * @return True if {@code other} has parent path equal to this context's parent path.
 186          */
 187         // FIXME: Remove this when SchemaNode.getPath() is removed
 188         default boolean equalParentPath(final Current<A, D> other) {
 189             final Parent ours = effectiveParent();
 190             final Parent theirs = other.effectiveParent();
 191             return ours == theirs
 192                 || ours != null && theirs != null && SchemaPathSupport.effectivelyEqual(
 193                     ours.schemaPath(), theirs.schemaPath());
 194         }
 195     }
 196 }