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.Optional;
  15 import org.eclipse.jdt.annotation.NonNull;
  16 import org.eclipse.jdt.annotation.Nullable;
  17 import org.opendaylight.yangtools.concepts.Immutable;
  18 import org.opendaylight.yangtools.yang.common.QName;
  19 import org.opendaylight.yangtools.yang.model.api.DataSchemaNode;
  20 import org.opendaylight.yangtools.yang.model.api.SchemaPath;
  21 import org.opendaylight.yangtools.yang.model.api.meta.DeclaredStatement;
  22 import org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement;
  23
  24 /**
  25  * Effective view of a {@link StmtContext} for the purposes of creating an {@link EffectiveStatement}.
  26  */
  27 @Beta
  28 public interface EffectiveStmtCtx extends CommonStmtCtx, StmtContextCompat, Immutable {
  29     /**
  30      * Return parent of this context, if there is one. All statements except for top-level source statements, such as
  31      * {@code module} and {@code submodule}.
  32      *
  33      * @return Parent context, or null if this statement is the root
  34      */
  35     @Nullable Parent effectiveParent();
  36
  37     /**
  38      * Return parent of this context.
  39      *
  40      * @return Parent context
  41      * @throws VerifyException if this context is already the root
  42      */
  43     default @NonNull Parent getEffectiveParent() {
  44         return verifyNotNull(effectiveParent(), "Attempted to access beyond root context");
  45     }
  46
  47     /**
  48      * Minimum amount of parent state required to build an accurate effective view of a particular child. Child state
  49      * is expressed as {@link Current}.
  50      */
  51     @Beta
  52     interface Parent extends EffectiveStmtCtx {
  53         /**
  54          * Effective {@code config} statement value.
  55          */
  56         @Beta
  57         enum EffectiveConfig {
  58             /**
  59              * We have an effective {@code config true} statement.
  60              */
  61             TRUE(Boolean.TRUE),
  62             /**
  63              * We have an effective {@code config false} statement.
  64              */
  65             FALSE(Boolean.FALSE),
  66             /**
  67              * We are in a context where {@code config} statements are ignored.
  68              */
  69             IGNORED(null),
  70             /**
  71              * We are in a context where {@code config} is not determined, such as within a {@code grouping}.
  72              */
  73             UNDETERMINED(null);
  74
  75             private final Boolean config;
  76
  77             EffectiveConfig(final @Nullable Boolean config) {
  78                 this.config = config;
  79             }
  80
  81             /**
  82              * Return this value as a {@link Boolean} for use with {@link DataSchemaNode#effectiveConfig()}.
  83              *
  84              * @return A boolean or null
  85              */
  86             public @Nullable Boolean asNullable() {
  87                 return config;
  88             }
  89         }
  90
  91         /**
  92          * Return the effective {@code config} statement value.
  93          *
  94          * @return This statement's effective config
  95          */
  96         @NonNull EffectiveConfig effectiveConfig();
  97
  98         /**
  99          * Return the {@link SchemaPath} of this statement. Not all statements have a SchemaPath, in which case
 100          * {@link Optional#empty()} is returned.
 101          *
 102          * @return Optional SchemaPath
 103          * @deprecated Use of SchemaPath in the context of effective statements is going away. Consider not providing
 104          *             this information, if your users can exist without it.
 105          */
 106         // FIXME: 7.0.0: this needs to be a tri-state present/absent/disabled
 107         @Deprecated
 108         @NonNull Optional<SchemaPath> schemaPath();
 109
 110         @Deprecated
 111         default @NonNull SchemaPath getSchemaPath() {
 112             return schemaPath().orElseThrow();
 113         }
 114
 115         @Deprecated
 116         default @Nullable SchemaPath wrapSchemaPath() {
 117             return SchemaPathSupport.wrap(getSchemaPath());
 118         }
 119     }
 120
 121     /**
 122      * Minimum amount of state required to build an accurate effective view of a statement. This is a strict superset
 123      * of information available in {@link Parent}.
 124      *
 125      * @param <A> Argument type
 126      * @param <D> Class representing declared version of this statement
 127      */
 128     @Beta
 129     interface Current<A, D extends DeclaredStatement<A>> extends Parent, NamespaceStmtCtx, BoundStmtCtxCompat<A, D> {
 130
 131         @NonNull QName moduleName();
 132
 133         @Nullable EffectiveStatement<?, ?> original();
 134
 135         /**
 136          * Summon the <a href="https://en.wikipedia.org/wiki/Rabbit_of_Caerbannog">Rabbit of Caerbannog</a>.
 137          *
 138          * @param <E> Effective Statement representation
 139          * @return The {@code Legendary Black Beast of Arrrghhh}.
 140          */
 141         // FIXME: YANGTOOLS-1186: lob the Holy Hand Grenade of Antioch
 142         @Deprecated
 143         <E extends EffectiveStatement<A, D>> @NonNull StmtContext<A, D, E> caerbannog();
 144     }
 145 }