yang/yang-parser-impl/src/main/java/org/opendaylight/yangtools/yang/parser/spi/meta/ModelActionBuilder.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 com.google.common.base.Supplier;
  11 import java.util.Collection;
  12 import javax.annotation.Nonnull;
  13 import org.opendaylight.yangtools.yang.model.api.meta.DeclaredStatement;
  14 import org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement;
  15 import org.opendaylight.yangtools.yang.model.api.meta.IdentifierNamespace;
  16 import org.opendaylight.yangtools.yang.parser.spi.meta.StmtContext.Mutable;
  17
  18
  19 /**
  20  * Builder for effective model inference action.
  21  *
  22  * Model inference action is core principle of transforming
  23  * declared model into effective model.
  24  *
  25  * Since YANG allows forward references, some inference actions
  26  * needs to be taken at later point, where reference is actually
  27  * resolved. Referenced objects are not retrieved directly
  28  * but are represented as {@link Prerequisite} (prerequisite) for
  29  * inference action to be taken.
  30  *
  31  * Some existing YANG statements are more complex and also object,
  32  * for which effective model may be inferred is also represented
  33  * as {@link Prerequisite} which once, when reference is available
  34  * will contain target context, which may be used for inference
  35  * action.
  36  *
  37  * <h2>Implementing inference action</h2>
  38  *
  39  * Effective inference action could always be splitted into two
  40  * separate tasks:
  41  * <ol>
  42  * <li>Declaration of inference action and its prerequisites</li>
  43  * <li>Execution of inference action</li>
  44  * </ol>
  45  * In order to declare inference action following steps needs
  46  * to be taken:
  47  *
  48  * <ol>
  49  * <li>Use {@link StmtContext.Mutable#newInferenceAction(ModelProcessingPhase)} to obtain
  50  * {@link ModelActionBuilder}.
  51  * <li>Use builder to specify concrete prerequisites of inference action
  52  * (other statements, values from identifier namespaces)
  53  * <li>Use builder to specify concrete set of nodes (or forward references to nodes)
  54  * which will inference action mutate.
  55  * <li>Use {@link #apply(InferenceAction)} with {@link InferenceAction} implementation
  56  * to register inference action.
  57  * </ol>
  58  *
  59  * Action will be executed when:
  60  * <ul>
  61  * <li> {@link InferenceAction#apply()} - all prerequisites (and declared forward references) are met,
  62  * action could dereference them and start applying changes.
  63  * </li>
  64  * <li>{@link InferenceAction#prerequisiteFailed(Collection)} - semantic parser finished all other satisfied
  65  * inference actions and some of declared prerequisites was still not met.
  66  * </li>
  67  * </ul>
  68  *
  69  * TODO: Insert real word example
  70  *
  71  * <h2>Design notes</h2>
  72  * {@link java.util.concurrent.Future} seems as viable and more standard
  73  * alternative to {@link Prerequisite}, but futures also carries
  74  * promise that resolution of it is carried in other
  75  * thread, which will actually put additional constraints on
  76  * semantic parser.
  77  *
  78  * Also listening on multiple futures is costly, so we opted
  79  * out of future and designed API, which later may introduce
  80  * futures.
  81  *
  82  */
  83 public interface ModelActionBuilder {
  84
  85     interface Prerequisite<T> extends Supplier<T> {
  86
  87         /**
  88          *
  89          * Returns associated prerequisite once it is resolved.
  90          *
  91          * @return associated prerequisite once it is resolved.
  92          *
  93          */
  94         @Override
  95         T get();
  96
  97         boolean isDone();
  98     }
  99
 100     /**
 101      * User-defined inference action.
 102      *
 103      */
 104     interface InferenceAction {
 105
 106         /**
 107          * Invoked once all prerequisites were met and forward references
 108          * were resolved and inference action should be applied.
 109          *
 110          * Implementors may do necessary changes to mutable objects
 111          * which were declared.
 112          *
 113          * @throws InferenceException If inference action can not be processed.
 114          *      Note that this exception be used for user to debug YANG sources,
 115          *      so should provide helpful context to fix issue in sources.
 116          */
 117         void apply() throws InferenceException;
 118
 119         /**
 120          * Invoked once one of prerequisites was not met,
 121          * even after all other satifiable inference actions were processed.
 122          *
 123          * Implementors MUST throw {@link InferenceException} if semantic processing
 124          * of model should be stopped and failed.
 125          *
 126          * List of failed prerequisites should be used to select right message / error
 127          * type to debug problem in YANG sources.
 128          *
 129          * @throws InferenceException If inference action can not be processed.
 130          *      Note that this exception be used for user to debug YANG sources,
 131          *      so should provide helpful context to fix issue in sources.
 132          */
 133         void prerequisiteFailed(Collection<? extends Prerequisite<?>> failed) throws InferenceException;
 134     }
 135
 136     @Nonnull <D extends DeclaredStatement<?>> Prerequisite<D> requiresDeclared(StmtContext<?,? extends D,?> context);
 137
 138     @Nonnull <K, D extends DeclaredStatement<?>, N extends StatementNamespace<K, ? extends D, ?>> Prerequisite<D> requiresDeclared(StmtContext<?,?,?> context,Class<N> namespace, K key);
 139
 140     @Nonnull <K, D extends DeclaredStatement<?>, N extends StatementNamespace<K, ? extends D, ?>> Prerequisite<StmtContext<?, D, ?>>requiresDeclaredCtx(StmtContext<?,?,?> context,Class<N> namespace, K key);
 141
 142     @Nonnull <E extends EffectiveStatement<?,?>> Prerequisite<E> requiresEffective(StmtContext<?,?,? extends E> stmt);
 143
 144     @Nonnull <K, E extends EffectiveStatement<?, ?>, N extends StatementNamespace<K, ?, ? extends E>> Prerequisite<E> requiresEffective(StmtContext<?,?,?> context,Class<N> namespace, K key);
 145
 146     @Nonnull <K, E extends EffectiveStatement<?, ?>, N extends StatementNamespace<K, ?, ? extends E>> Prerequisite<StmtContext<?,?,E>> requiresEffectiveCtx(StmtContext<?,?,?> context,Class<N> namespace, K key);
 147
 148     @Nonnull <N extends IdentifierNamespace<? ,?>> Prerequisite<Mutable<?,?,?>> mutatesNs(Mutable<?,?, ?> ctx, Class<N> namespace);
 149
 150     @Nonnull <T extends Mutable<?,?,?>> Prerequisite<T> mutatesEffectiveCtx(T stmt);
 151
 152     @Nonnull  <K,E extends EffectiveStatement<?,?>,N extends StatementNamespace<K, ?, ? extends E>> Prerequisite<Mutable<?,?,E>> mutatesEffectiveCtx(StmtContext<?,?,?> context,Class<N> namespace, K key);
 153
 154     void apply(InferenceAction action) throws InferenceException;
 155
 156     @Nonnull <A,D extends DeclaredStatement<A>,E extends EffectiveStatement<A, D>> Prerequisite<StmtContext<A, D, E>> requiresCtx(StmtContext<A, D, E> context, ModelProcessingPhase phase);
 157
 158     @Nonnull <K, N extends StatementNamespace<K, ?, ? >> Prerequisite<StmtContext<?,?,?>> requiresCtx(StmtContext<?, ?, ?> context, Class<N> namespace, K key, ModelProcessingPhase phase);
 159
 160     @Nonnull <C extends StmtContext.Mutable<?,?,?>, CT extends C> Prerequisite<C> mutatesCtx(CT root, ModelProcessingPhase phase);
 161 }