parser/yang-parser-spi/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 static org.opendaylight.yangtools.yang.parser.spi.meta.ModelProcessingPhase.EFFECTIVE_MODEL;
  11
  12 import com.google.common.annotations.Beta;
  13 import com.google.common.collect.ImmutableList;
  14 import java.util.Collection;
  15 import org.eclipse.jdt.annotation.NonNull;
  16 import org.opendaylight.yangtools.yang.model.api.meta.DeclaredStatement;
  17 import org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement;
  18 import org.opendaylight.yangtools.yang.parser.spi.meta.StmtContext.Mutable;
  19
  20 /**
  21  * Builder for effective model inference action. Model inference action is core principle of transforming
  22  * declared model into effective model.
  23  *
  24  * <p>
  25  * Since YANG allows forward references, some inference actions need to be taken at a later point, where reference is
  26  * actually resolved. Referenced objects are not retrieved directly but are represented as {@link Prerequisite}
  27  * (prerequisite) for inference action to be taken.
  28  *
  29  * <p>
  30  * Some existing YANG statements are more complex and also object, for which effective model may be inferred is also
  31  * represented as a {@link Prerequisite} which, when reference is available, will contain target context, which may be
  32  * used for inference action.
  33  *
  34  * <h2>Implementing inference action</h2>
  35  * Effective inference action could always be splitted into two separate tasks:
  36  * <ol>
  37  * <li>Declaration of inference action and its prerequisites</li>
  38  * <li>Execution of inference action</li>
  39  * </ol>
  40  *
  41  * <p>
  42  * In order to declare inference action following steps needs
  43  * to be taken:
  44  * <ol>
  45  * <li>Use {@link StmtContext.Mutable#newInferenceAction(ModelProcessingPhase)} to obtain
  46  * {@link ModelActionBuilder}.
  47  * <li>Use builder to specify concrete prerequisites of inference action
  48  * (other statements, values from identifier namespaces)
  49  * <li>Use builder to specify concrete set of nodes (or forward references to nodes)
  50  * which will inference action mutate.
  51  * <li>Use {@link #apply(InferenceAction)} with {@link InferenceAction} implementation
  52  * to register inference action.
  53  * </ol>
  54  *
  55  * <p>
  56  * An action will be executed when:
  57  * <ul>
  58  * <li> {@link InferenceAction#apply(InferenceContext)} - all prerequisites (and declared forward references) are met,
  59  * action could dereference them and start applying changes.
  60  * </li>
  61  * <li>{@link InferenceAction#prerequisiteFailed(Collection)} - semantic parser finished all other satisfied
  62  * inference actions and some of declared prerequisites was still not met.
  63  * </li>
  64  * </ul>
  65  *
  66  * <p>
  67  * TODO: Insert real word example
  68  *
  69  * <h2>Design notes</h2>
  70  * {@link java.util.concurrent.Future} seems as viable and more standard alternative to {@link Prerequisite}, but
  71  * Futures also carries promise that resolution of it is carried in other thread, which will actually put additional
  72  * constraints on semantic parser.
  73  *
  74  * <p>
  75  * Also listening on multiple futures is costly, so we opted out of future and designed API, which later may introduce
  76  * futures.
  77  */
  78 public interface ModelActionBuilder {
  79     interface InferenceContext {
  80
  81     }
  82
  83     @FunctionalInterface
  84     interface Prerequisite<T> {
  85         /**
  86          * Returns associated prerequisite once it is resolved.
  87          *
  88          * @param ctx Inference context in which the prerequisite was satisfied
  89          * @return associated prerequisite once it is resolved.
  90          */
  91         @NonNull T resolve(InferenceContext ctx);
  92     }
  93
  94     /**
  95      * User-defined inference action.
  96      */
  97     interface InferenceAction {
  98
  99         /**
 100          * Invoked once all prerequisites were met and forward references were resolved and inference action should be
 101          * applied. Implementors may perform necessary changes to mutable objects which were declared.
 102          *
 103          * @throws InferenceException If inference action can not be processed. Note that this exception be used for
 104          *         user to debug YANG sources, so should provide helpful context to fix issue in sources.
 105          */
 106         void apply(InferenceContext ctx);
 107
 108         /**
 109          * Invoked once one of prerequisites was not met, even after all other satisfiable inference actions were
 110          * processed.
 111          *
 112          * <p>
 113          * Implementors MUST throw {@link InferenceException} if semantic processing of model should be stopped
 114          * and failed.
 115          *
 116          * <p>
 117          * List of failed prerequisites should be used to select right message / error type to debug problem in YANG
 118          * sources.
 119          *
 120          * @param failed collection of prerequisites which were not met
 121          * @throws InferenceException If inference action can not be processed. Note that this exception be used
 122          *                            by user to debug YANG sources, hence it should provide helpful context to fix
 123          *                            the issue in sources.
 124          */
 125         void prerequisiteFailed(Collection<? extends Prerequisite<?>> failed);
 126
 127         /**
 128          * Invoked once the prerequisite is deemed unavailable due to conformance reasons. This typically happens when
 129          * a feature-dependent prerequisite does not have the appropriate feature activated.
 130          *
 131          * <p>
 132          * The default implementation invokes {@link #prerequisiteFailed(Collection)}, implementations should override
 133          * this method if they wish, for example, to ignore the missing prerequisite.
 134          *
 135          * @param unavail Unavailable prerequisite
 136          */
 137         @Beta
 138         default void prerequisiteUnavailable(final Prerequisite<?> unavail) {
 139             prerequisiteFailed(ImmutableList.of(unavail));
 140         }
 141     }
 142
 143     /**
 144      * Action requires that the specified context transition to complete {@link ModelProcessingPhase#FULL_DECLARATION}
 145      * phase and produce a declared statement.
 146      *
 147      * @param context Statement context which needs to complete the transition.
 148      * @return A {@link Prerequisite} returning the declared statement of the requested context.
 149      */
 150     <D extends DeclaredStatement<?>> @NonNull Prerequisite<D> requiresDeclared(StmtContext<?, ? extends D, ?> context);
 151
 152     /**
 153      * Create a requirement on specified statement to be declared.
 154      *
 155      * @deprecated Undocumented method. Use at your own risk.
 156      */
 157     @Deprecated
 158     <K, D extends DeclaredStatement<?>> @NonNull Prerequisite<D> requiresDeclared(StmtContext<?, ?, ?> context,
 159         ParserNamespace<K, StmtContext<?, ? extends D, ?>> namespace, K key);
 160
 161     /**
 162      * Action requires that the specified context completes specified phase before {@link #apply(InferenceAction)}
 163      * may be invoked.
 164      *
 165      * @param context Statement context which needs to complete the transition.
 166      * @param phase ModelProcessingPhase which must have completed
 167      * @return A {@link Prerequisite} returning the requested context.
 168      */
 169     <A, D extends DeclaredStatement<A>, E extends EffectiveStatement<A, D>> @NonNull Prerequisite<StmtContext<A, D, E>>
 170         requiresCtx(StmtContext<A, D, E> context, ModelProcessingPhase phase);
 171
 172     <K, C extends StmtContext<?, ?, ?>> @NonNull Prerequisite<C> requiresCtx(StmtContext<?, ?, ?> context,
 173         @NonNull ParserNamespace<K, C> namespace, K key, ModelProcessingPhase phase);
 174
 175     <K, C extends StmtContext<?, ?, ?>> @NonNull Prerequisite<C> requiresCtx(StmtContext<?, ?, ?> context,
 176         @NonNull ParserNamespace<K, C> namespace, NamespaceKeyCriterion<K> criterion, ModelProcessingPhase phase);
 177
 178     <K, C extends StmtContext<?, ?, ?>> @NonNull Prerequisite<C> requiresEffectiveCtxPath(StmtContext<?, ?, ?> context,
 179         ParserNamespace<K, C> namespace, Iterable<K> keys);
 180
 181     /**
 182      * Action mutates the effective model of specified statement. This is a shorthand for
 183      * {@code mutatesCtx(context, EFFECTIVE_MODEL}.
 184      *
 185      * @param context Target statement context
 186      * @return A {@link Prerequisite} returning the requested context.
 187      */
 188     default <T extends Mutable<?, ?, ?>> @NonNull Prerequisite<T> mutatesEffectiveCtx(final T context) {
 189         return mutatesCtx(context, EFFECTIVE_MODEL);
 190     }
 191
 192     <K, E extends EffectiveStatement<?, ?>> @NonNull Prerequisite<Mutable<?, ?, E>> mutatesEffectiveCtx(
 193         StmtContext<?, ?, ?> context, ParserNamespace<K, ? extends StmtContext<?, ?, ?>> namespace, K key);
 194
 195     <K, E extends EffectiveStatement<?, ?>> @NonNull Prerequisite<Mutable<?, ?, E>> mutatesEffectiveCtxPath(
 196         StmtContext<?, ?, ?> context, ParserNamespace<K, ? extends StmtContext<?, ?, ?>> namespace, Iterable<K> keys);
 197
 198     /**
 199      * Action mutates the specified statement in the specified phase. Target statement cannot complete specified
 200      * phase before this action is applier.
 201      *
 202      * @param context Target statement context
 203      * @return A {@link Prerequisite} returning the requested context.
 204      */
 205     <C extends Mutable<?, ?, ?>, T extends C> @NonNull Prerequisite<C> mutatesCtx(T context,
 206             ModelProcessingPhase phase);
 207
 208     /**
 209      * Apply an {@link InferenceAction} when this action's prerequisites are resolved.
 210      *
 211      * @param action Inference action to apply
 212      * @throws InferenceException if the action fails
 213      * @throws NullPointerException if {@code action is null}
 214      * @throws IllegalStateException if this action has an inference action already associated.
 215      */
 216     void apply(InferenceAction action);
 217
 218     /**
 219      * Create a requirement on specified statement context to be declared.
 220      *
 221      * @deprecated Undocumented method. Use at your own risk.
 222      */
 223     @Deprecated
 224     <K, C extends StmtContext<?, ?, ?>> @NonNull Prerequisite<C> requiresDeclaredCtx(StmtContext<?, ?, ?> context,
 225         ParserNamespace<K, C> namespace, K key);
 226
 227     /**
 228      * Create a requirement on specified statement to become effective.
 229      *
 230      * @deprecated Undocumented method. Use at your own risk.
 231      */
 232     @Deprecated
 233     <E extends EffectiveStatement<?, ?>> @NonNull Prerequisite<E> requiresEffective(
 234             StmtContext<?, ?, ? extends E> stmt);
 235
 236     /**
 237      * Create a requirement on specified statement to become effective.
 238      *
 239      * @deprecated Undocumented method. Use at your own risk.
 240      */
 241     @Deprecated
 242     <K, E extends EffectiveStatement<?, ?>> @NonNull Prerequisite<E> requiresEffective(StmtContext<?, ?, ?> context,
 243         ParserNamespace<K, StmtContext<?, ?, ? extends E>> namespace, K key);
 244
 245     /**
 246      * Create a requirement on specified statement context to become effective.
 247      *
 248      * @deprecated Undocumented method. Use at your own risk.
 249      */
 250     @Deprecated
 251     <K, C extends StmtContext<?, ?, ?>> @NonNull Prerequisite<C> requiresEffectiveCtx(StmtContext<?, ?, ?> context,
 252         ParserNamespace<K, C> namespace, K key);
 253
 254     /**
 255      * Mark the fact that this action is mutating a namespace.
 256      *
 257      * @deprecated Undocumented method. Use at your own risk.
 258      */
 259     @Deprecated
 260     @NonNull Prerequisite<Mutable<?, ?, ?>> mutatesNs(Mutable<?, ?, ?> ctx, ParserNamespace<?, ?> namespace);
 261 }