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

   1 /*
   2  * Copyright (c) 2015 Cisco Systems, Inc. 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 com.google.common.collect.Iterables;
  15 import com.google.common.collect.Streams;
  16 import java.util.Collection;
  17 import java.util.Map;
  18 import java.util.Optional;
  19 import java.util.stream.Stream;
  20 import org.eclipse.jdt.annotation.NonNull;
  21 import org.eclipse.jdt.annotation.Nullable;
  22 import org.opendaylight.yangtools.yang.common.QNameModule;
  23 import org.opendaylight.yangtools.yang.common.YangVersion;
  24 import org.opendaylight.yangtools.yang.model.api.SchemaPath;
  25 import org.opendaylight.yangtools.yang.model.api.meta.DeclaredStatement;
  26 import org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement;
  27 import org.opendaylight.yangtools.yang.model.api.meta.IdentifierNamespace;
  28 import org.opendaylight.yangtools.yang.model.api.meta.StatementDefinition;
  29 import org.opendaylight.yangtools.yang.model.api.meta.StatementSource;
  30 import org.opendaylight.yangtools.yang.model.repo.api.SourceIdentifier;
  31 import org.opendaylight.yangtools.yang.parser.spi.source.StatementSourceReference;
  32
  33 /**
  34  * An inference context associated with an instance of a statement.
  35  *
  36  * @param <A> Argument type
  37  * @param <D> Declared Statement representation
  38  * @param <E> Effective Statement representation
  39  */
  40 public interface StmtContext<A, D extends DeclaredStatement<A>, E extends EffectiveStatement<A, D>> {
  41     /**
  42      * Returns the origin of the statement.
  43      *
  44      * @return origin of statement
  45      */
  46     @NonNull StatementSource getStatementSource();
  47
  48     /**
  49      * Returns a reference to statement source.
  50      *
  51      * @return reference of statement source
  52      */
  53     @NonNull StatementSourceReference getStatementSourceReference();
  54
  55     /**
  56      * See {@link StatementSupport#getPublicView()}.
  57      */
  58     @NonNull StatementDefinition getPublicDefinition();
  59
  60     /**
  61      * Return the parent statement context, or null if this is the root statement.
  62      *
  63      * @return context of parent of statement, or null if this is the root statement.
  64      */
  65     @Nullable StmtContext<?, ?, ?> getParentContext();
  66
  67     /**
  68      * Return the parent statement context, forcing a VerifyException if this is the root statement.
  69      *
  70      * @return context of parent of statement
  71      * @throws VerifyException if this statement is the root statement
  72      */
  73     default @NonNull StmtContext<?, ?, ?> coerceParentContext() {
  74         return verifyNotNull(getParentContext(), "Root context %s does not have a parent", this);
  75     }
  76
  77     /**
  78      * Return the statement argument in literal format.
  79      *
  80      * @return raw statement argument string, or null if this statement does not have an argument.
  81      */
  82     @Nullable String rawStatementArgument();
  83
  84     /**
  85      * Return the statement argument in literal format.
  86      *
  87      * @return raw statement argument string
  88      * @throws VerifyException if this statement does not have an argument
  89      */
  90     default @NonNull String coerceRawStatementArgument() {
  91         return verifyNotNull(rawStatementArgument(), "Statement context %s does not have an argument", this);
  92     }
  93
  94     /**
  95      * Return the statement argument.
  96      *
  97      * @return statement argument, or null if this statement does not have an argument
  98      */
  99     @Nullable A getStatementArgument();
 100
 101     /**
 102      * Return the statement argument in literal format.
 103      *
 104      * @return raw statement argument string
 105      * @throws VerifyException if this statement does not have an argument
 106      */
 107     default @NonNull A coerceStatementArgument() {
 108         return verifyNotNull(getStatementArgument(), "Statement context %s does not have an argument", this);
 109     }
 110
 111     default <X, Y extends DeclaredStatement<X>> boolean producesDeclared(final Class<? super Y> type) {
 112         return type.isAssignableFrom(getPublicDefinition().getDeclaredRepresentationClass());
 113     }
 114
 115     default <X, Y extends DeclaredStatement<X>, Z extends EffectiveStatement<A, D>> boolean producesEffective(
 116             final Class<? super Z> type) {
 117         return type.isAssignableFrom(getPublicDefinition().getEffectiveRepresentationClass());
 118     }
 119
 120     /**
 121      * Return the {@link SchemaPath} of this statement. Not all statements have a SchemaPath, in which case
 122      * {@link Optional#empty()} is returned.
 123      *
 124      * @return Optional SchemaPath
 125      * @deprecated Use of SchemaPath in the context of effective statements is going away. Consider not providing this
 126      *             information, if your users can exist without it.
 127      */
 128     @Deprecated
 129     @NonNull Optional<SchemaPath> getSchemaPath();
 130
 131     boolean isConfiguration();
 132
 133     boolean isEnabledSemanticVersioning();
 134
 135     /**
 136      * Return a value associated with specified key within a namespace.
 137      *
 138      * @param type Namespace type
 139      * @param key Key
 140      * @param <K> namespace key type
 141      * @param <V> namespace value type
 142      * @param <N> namespace type
 143      * @param <T> key type
 144      * @return Value, or null if there is no element
 145      * @throws NamespaceNotAvailableException when the namespace is not available.
 146      */
 147     <K, V, T extends K, N extends IdentifierNamespace<K, V>> @Nullable V getFromNamespace(Class<@NonNull N> type,
 148             T key);
 149
 150     <K, V, N extends IdentifierNamespace<K, V>> Map<K, V> getAllFromNamespace(Class<N> type);
 151
 152     <K, V, N extends IdentifierNamespace<K, V>> Map<K, V> getAllFromCurrentStmtCtxNamespace(Class<N> type);
 153
 154     @NonNull StmtContext<?, ?, ?> getRoot();
 155
 156     /**
 157      * Return declared substatements. These are the statements which are explicitly written in the source model.
 158      *
 159      * @return Collection of declared substatements
 160      */
 161     @NonNull Collection<? extends StmtContext<?, ?, ?>> declaredSubstatements();
 162
 163     /**
 164      * Return effective substatements. These are the statements which are added as this statement's substatements
 165      * complete their effective model phase.
 166      *
 167      * @return Collection of declared substatements
 168      */
 169     @NonNull Collection<? extends StmtContext<?, ?, ?>> effectiveSubstatements();
 170
 171     default Iterable<? extends StmtContext<?, ?, ?>> allSubstatements() {
 172         return Iterables.concat(declaredSubstatements(), effectiveSubstatements());
 173     }
 174
 175     default Stream<? extends StmtContext<?, ?, ?>> allSubstatementsStream() {
 176         return Streams.concat(declaredSubstatements().stream(), effectiveSubstatements().stream());
 177     }
 178
 179     /**
 180      * Builds {@link DeclaredStatement} for statement context.
 181      */
 182     D buildDeclared();
 183
 184     /**
 185      * Builds {@link EffectiveStatement} for statement context.
 186      */
 187     E buildEffective();
 188
 189     boolean isSupportedToBuildEffective();
 190
 191     boolean isSupportedByFeatures();
 192
 193     Collection<? extends StmtContext<?, ?, ?>> getEffectOfStatement();
 194
 195     /*
 196      * FIXME: YANGTOOLS-784: the next three methods are closely related to the copy process:
 197      *        - getCopyHistory() is a brief summary of what went on
 198      *        - getOriginalContext() points to the CopyHistory.ORIGINAL
 199      *        - getPreviousCopyCtx() points to the immediate predecessor forming a singly-linked list terminated
 200      *          at getOriginalContext()
 201      *
 202      *        When implementing YANGTOOLS-784, this needs to be taken into account and properly forwarded through
 203      *        intermediate MutableTrees. Also note this closely relates to current namespace context, as taken into
 204      *        account when creating the argument. At least parts of this are only needed during buildEffective()
 205      *        and hence should become arguments to that method.
 206      */
 207
 208     /**
 209      * Return the executive summary of the copy process that has produced this context.
 210      *
 211      * @return A simplified summary of the copy process.
 212      */
 213     CopyHistory getCopyHistory();
 214
 215     /**
 216      * Return the statement context of the original definition, if this statement is an instantiated copy.
 217      *
 218      * @return Original definition, if this statement was copied.
 219      */
 220     Optional<StmtContext<A, D, E>> getOriginalCtx();
 221
 222     /**
 223      * Return the context of the previous copy of this statement -- effectively walking towards the source origin
 224      * of this statement.
 225      *
 226      * @return Context of the previous copy of this statement, if this statement has been copied.
 227      */
 228     Optional<StmtContext<A, D, E>> getPreviousCopyCtx();
 229
 230     ModelProcessingPhase getCompletedPhase();
 231
 232     /**
 233      * Return version of root statement context.
 234      *
 235      * @return version of root statement context
 236      */
 237     @NonNull YangVersion getRootVersion();
 238
 239     /**
 240      * An mutable view of an inference context associated with an instance of a statement.
 241      *
 242      * @param <A> Argument type
 243      * @param <D> Declared Statement representation
 244      * @param <E> Effective Statement representation
 245      */
 246     interface Mutable<A, D extends DeclaredStatement<A>, E extends EffectiveStatement<A, D>>
 247             extends StmtContext<A, D, E> {
 248
 249         @Override
 250         Mutable<?, ?, ?> getParentContext();
 251
 252         @Override
 253         default Mutable<?, ?, ?> coerceParentContext() {
 254             return verifyNotNull(getParentContext(), "Root context %s does not have a parent", this);
 255         }
 256
 257         /**
 258          * Associate a value with a key within a namespace.
 259          *
 260          * @param type Namespace type
 261          * @param key Key
 262          * @param value value
 263          * @param <K> namespace key type
 264          * @param <V> namespace value type
 265          * @param <N> namespace type
 266          * @param <T> key type
 267          * @param <U> value type
 268          * @throws NamespaceNotAvailableException when the namespace is not available.
 269          */
 270         <K, V, T extends K, U extends V, N extends IdentifierNamespace<K, V>> void addToNs(Class<@NonNull N> type,
 271                 T key, U value);
 272
 273         @Override
 274         Mutable<?, ?, ?> getRoot();
 275
 276         /**
 277          * Create a child sub-statement, which is a child of this statement, inheriting all attributes from specified
 278          * child and recording copy type. Resulting object may only be added as a child of this statement.
 279          *
 280          * @param stmt Statement to be used as a template
 281          * @param type Type of copy to record in history
 282          * @param targetModule Optional new target module
 283          * @return copy of statement considering {@link CopyType} (augment, uses)
 284          *
 285          * @throws IllegalArgumentException if stmt cannot be copied into this statement, for example because it comes
 286          *                                  from an alien implementation.
 287          * @throws org.opendaylight.yangtools.yang.parser.spi.source.SourceException instance of SourceException
 288          */
 289         Mutable<?, ?, ?> childCopyOf(StmtContext<?, ?, ?> stmt, CopyType type, @Nullable QNameModule targetModule);
 290
 291         /**
 292          * Create a child sub-statement, which is a child of this statement, inheriting all attributes from specified
 293          * child and recording copy type. Resulting object may only be added as a child of this statement.
 294          *
 295          * @param stmt Statement to be used as a template
 296          * @param type Type of copy to record in history
 297          * @return copy of statement considering {@link CopyType} (augment, uses)
 298          *
 299          * @throws IllegalArgumentException if stmt cannot be copied into this statement, for example because it comes
 300          *                                  from an alien implementation.
 301          * @throws org.opendaylight.yangtools.yang.parser.spi.source.SourceException instance of SourceException
 302          */
 303         default Mutable<?, ?, ?> childCopyOf(final StmtContext<?, ?, ?> stmt, final CopyType type) {
 304             return childCopyOf(stmt, type, null);
 305         }
 306
 307         @Beta
 308         @NonNull Optional<? extends Mutable<?, ?, ?>> copyAsChildOf(Mutable<?, ?, ?> parent, CopyType type,
 309                 @Nullable QNameModule targetModule);
 310
 311         @Override
 312         default Collection<? extends StmtContext<?, ?, ?>> declaredSubstatements() {
 313             return mutableDeclaredSubstatements();
 314         }
 315
 316         @NonNull Collection<? extends Mutable<?, ?, ?>> mutableDeclaredSubstatements();
 317
 318         @Override
 319         default Collection<? extends StmtContext<?, ?, ?>> effectiveSubstatements() {
 320             return mutableEffectiveSubstatements();
 321         }
 322
 323         @NonNull Collection<? extends Mutable<?, ?, ?>> mutableEffectiveSubstatements();
 324
 325         /**
 326          * Create a new inference action to be executed during specified phase. The action cannot be cancelled
 327          * and will be executed even if its definition remains incomplete. The specified phase cannot complete until
 328          * this action is resolved. If the action cannot be resolved, model processing will fail.
 329          *
 330          * @param phase Target phase in which the action will resolved.
 331          * @return A new action builder.
 332          * @throws NullPointerException if the specified phase is null
 333          */
 334         @NonNull ModelActionBuilder newInferenceAction(@NonNull ModelProcessingPhase phase);
 335
 336         /**
 337          * Adds s statement to namespace map with a key.
 338          *
 339          * @param namespace
 340          *            {@link StatementNamespace} child that determines namespace to be added to
 341          * @param key
 342          *            of type according to namespace class specification
 343          * @param stmt
 344          *            to be added to namespace map
 345          */
 346         <K, KT extends K, N extends StatementNamespace<K, ?, ?>> void addContext(Class<@NonNull N> namespace, KT key,
 347                 StmtContext<?, ?, ?> stmt);
 348
 349         /**
 350          * Set version of root statement context.
 351          *
 352          * @param version
 353          *            of root statement context
 354          */
 355         void setRootVersion(YangVersion version);
 356
 357         /**
 358          * Add mutable statement to seal. Each mutable statement must be sealed
 359          * as the last step of statement parser processing.
 360          *
 361          * @param mutableStatement
 362          *            mutable statement which should be sealed
 363          */
 364         void addMutableStmtToSeal(MutableStatement mutableStatement);
 365
 366         /**
 367          * Add required module. Based on these dependencies are collected required sources from library sources.
 368          *
 369          * @param dependency
 370          *            SourceIdentifier of module required by current root
 371          *            context
 372          */
 373         /*
 374          * FIXME: this method is used solely during SOURCE_PRE_LINKAGE reactor phase and does not have a corresponding
 375          *        getter -- which makes it rather strange. At some point this method needs to be deprecated and its
 376          *        users migrated to use proper global namespace.
 377          */
 378         void addRequiredSource(SourceIdentifier dependency);
 379
 380         void addAsEffectOfStatement(StmtContext<?, ?, ?> ctx);
 381
 382         void addAsEffectOfStatement(Collection<? extends StmtContext<?, ?, ?>> ctxs);
 383
 384         /**
 385          * Set identifier of current root context.
 386          *
 387          * @param identifier
 388          *            of current root context, must not be null
 389          */
 390         void setRootIdentifier(SourceIdentifier identifier);
 391
 392         void setIsSupportedToBuildEffective(boolean isSupportedToBuild);
 393     }
 394
 395     /**
 396      * Search of any child statement context of specified type and return its argument. If such a statement exists, it
 397      * is assumed to have the right argument. Users should be careful to use this method for statements which have
 398      * cardinality {@code 0..1}, otherwise this method can return any one of the statement's argument.
 399      *
 400      * <p>
 401      * The default implementation defers to
 402      * {@link StmtContextDefaults#findSubstatementArgument(StmtContext, Class)}, subclasses are expected to provide
 403      * optimized implementation if possible.
 404      *
 405      * @param <X> Substatement argument type
 406      * @param <Z> Substatement effective statement representation
 407      * @param type Effective statement representation being look up
 408      * @return {@link Optional#empty()} if no statement exists, otherwise the argument value
 409      */
 410     default <X, Z extends EffectiveStatement<X, ?>> @NonNull Optional<X> findSubstatementArgument(
 411             final @NonNull Class<Z> type) {
 412         return StmtContextDefaults.findSubstatementArgument(this, type);
 413     }
 414
 415     /**
 416      * Check if there is any child statement context of specified type.
 417      *
 418      * <p>
 419      * The default implementation defers to {@link StmtContextDefaults#hasSubstatement(StmtContext, Class)},
 420      * subclasses are expected to provide optimized implementation if possible.
 421      *
 422      * @param type Effective statement representation being look up
 423      * @return True if such a child statement exists, false otherwise
 424      */
 425     default boolean hasSubstatement(final @NonNull Class<? extends EffectiveStatement<?, ?>> type) {
 426         return StmtContextDefaults.hasSubstatement(this, type);
 427     }
 428 }