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 java.util.Objects;
  15 import java.util.Optional;
  16 import org.eclipse.jdt.annotation.NonNull;
  17 import org.eclipse.jdt.annotation.Nullable;
  18 import org.opendaylight.yangtools.concepts.Immutable;
  19 import org.opendaylight.yangtools.yang.common.QName;
  20 import org.opendaylight.yangtools.yang.common.QNameModule;
  21 import org.opendaylight.yangtools.yang.model.api.DataSchemaNode;
  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         default @NonNull Object effectivePath() {
 104             return SchemaPathSupport.toEffectivePath(getSchemaPath());
 105         }
 106
 107         default @Nullable SchemaPath optionalPath() {
 108             return SchemaPathSupport.toOptionalPath(getSchemaPath());
 109         }
 110
 111         /**
 112          * Return the {@link SchemaPath} of this statement. Not all statements have a SchemaPath, in which case
 113          * {@link Optional#empty()} is returned.
 114          *
 115          * @return Optional SchemaPath
 116          * @deprecated Use of SchemaPath in the context of effective statements is going away. Consider not providing
 117          *             this information, if your users can exist without it.
 118          */
 119         // FIXME: 7.0.0: this needs to be a tri-state present/absent/disabled
 120         @Deprecated
 121         @NonNull Optional<SchemaPath> schemaPath();
 122
 123         @Deprecated
 124         default @NonNull SchemaPath getSchemaPath() {
 125             return schemaPath().orElseThrow();
 126         }
 127     }
 128
 129     /**
 130      * Minimum amount of state required to build an accurate effective view of a statement. This is a strict superset
 131      * of information available in {@link Parent}.
 132      *
 133      * @param <A> Argument type
 134      * @param <D> Class representing declared version of this statement
 135      */
 136     @Beta
 137     interface Current<A, D extends DeclaredStatement<A>> extends Parent, NamespaceStmtCtx, BoundStmtCtxCompat<A, D> {
 138
 139         @NonNull QName moduleName();
 140
 141         @Nullable EffectiveStatement<?, ?> original();
 142
 143         // FIXME: 7.0.0: this method should be moved to stmt.type in some shape or form
 144         @NonNull QName argumentAsTypeQName();
 145
 146         /**
 147          * Summon the <a href="https://en.wikipedia.org/wiki/Rabbit_of_Caerbannog">Rabbit of Caerbannog</a>.
 148          *
 149          * @param <E> Effective Statement representation
 150          * @return The {@code Legendary Black Beast of Arrrghhh}.
 151          */
 152         // FIXME: YANGTOOLS-1186: lob the Holy Hand Grenade of Antioch
 153         @Deprecated
 154         <E extends EffectiveStatement<A, D>> @NonNull StmtContext<A, D, E> caerbannog();
 155
 156         /**
 157          * Compare another context for equality of {@code getEffectiveParent().getSchemaPath()}, just in a safer manner.
 158          *
 159          * @param other Other {@link Current}
 160          * @return True if {@code other} has parent path equal to this context's parent path.
 161          */
 162         // FIXME: 8.0.0: Remove this method
 163         default boolean equalParentPath(final Current<A, D> other) {
 164             final Parent ours = effectiveParent();
 165             final Parent theirs = other.effectiveParent();
 166             return ours == theirs
 167                 || ours != null && theirs != null && Objects.equals(ours.schemaPath(), theirs.schemaPath());
 168         }
 169     }
 170 }