2 * Copyright (c) 2015 Cisco Systems, Inc. and others. All rights reserved.
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
8 package org.opendaylight.yangtools.yang.parser.spi.meta;
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;
20 * Builder for effective model inference action.
22 * Model inference action is core principle of transforming
23 * declared model into effective model.
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.
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
37 * <h2>Implementing inference action</h2>
39 * Effective inference action could always be splitted into two
42 * <li>Declaration of inference action and its prerequisites</li>
43 * <li>Execution of inference action</li>
45 * In order to declare inference action following steps needs
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.
59 * Action will be executed when:
61 * <li> {@link InferenceAction#apply()} - all prerequisites (and declared forward references) are met,
62 * action could dereference them and start applying changes.
64 * <li>{@link InferenceAction#prerequisiteFailed(Collection)} - semantic parser finished all other satisfied
65 * inference actions and some of declared prerequisites was still not met.
69 * TODO: Insert real word example
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
78 * Also listening on multiple futures is costly, so we opted
79 * out of future and designed API, which later may introduce
83 public interface ModelActionBuilder {
85 interface Prerequisite<T> extends Supplier<T> {
89 * Returns associated prerequisite once it is resolved.
91 * @return associated prerequisite once it is resolved.
101 * User-defined inference action.
104 interface InferenceAction {
107 * Invoked once all prerequisites were met and forward references
108 * were resolved and inference action should be applied.
110 * Implementors may do necessary changes to mutable objects
111 * which were declared.
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.
117 void apply() throws InferenceException;
120 * Invoked once one of prerequisites was not met,
121 * even after all other satifiable inference actions were processed.
123 * Implementors MUST throw {@link InferenceException} if semantic processing
124 * of model should be stopped and failed.
126 * List of failed prerequisites should be used to select right message / error
127 * type to debug problem in YANG sources.
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.
133 * @param failed collection of prerequisites which were not met
135 void prerequisiteFailed(Collection<? extends Prerequisite<?>> failed) throws InferenceException;
138 @Nonnull <D extends DeclaredStatement<?>> Prerequisite<D> requiresDeclared(StmtContext<?,? extends D,?> context);
140 @Nonnull <K, D extends DeclaredStatement<?>, N extends StatementNamespace<K, ? extends D, ?>> Prerequisite<D> requiresDeclared(StmtContext<?,?,?> context,Class<N> namespace, K key);
142 @Nonnull <K, D extends DeclaredStatement<?>, N extends StatementNamespace<K, ? extends D, ?>> Prerequisite<StmtContext<?, D, ?>>requiresDeclaredCtx(StmtContext<?,?,?> context,Class<N> namespace, K key);
144 @Nonnull <E extends EffectiveStatement<?,?>> Prerequisite<E> requiresEffective(StmtContext<?,?,? extends E> stmt);
146 @Nonnull <K, E extends EffectiveStatement<?, ?>, N extends StatementNamespace<K, ?, ? extends E>> Prerequisite<E> requiresEffective(StmtContext<?,?,?> context,Class<N> namespace, K key);
148 @Nonnull <K, E extends EffectiveStatement<?, ?>, N extends StatementNamespace<K, ?, ? extends E>> Prerequisite<StmtContext<?,?,E>> requiresEffectiveCtx(StmtContext<?,?,?> context,Class<N> namespace, K key);
150 @Nonnull <N extends IdentifierNamespace<? ,?>> Prerequisite<Mutable<?,?,?>> mutatesNs(Mutable<?,?, ?> ctx, Class<N> namespace);
152 @Nonnull <T extends Mutable<?,?,?>> Prerequisite<T> mutatesEffectiveCtx(T stmt);
154 @Nonnull <K,E extends EffectiveStatement<?,?>, N extends IdentifierNamespace<K, ? extends StmtContext<?, ?, ?>>> Prerequisite<Mutable<?,?,E>> mutatesEffectiveCtx(StmtContext<?,?,?> context,Class<N> namespace, K key);
156 void apply(InferenceAction action) throws InferenceException;
158 @Nonnull <A,D extends DeclaredStatement<A>,E extends EffectiveStatement<A, D>> Prerequisite<StmtContext<A, D, E>> requiresCtx(StmtContext<A, D, E> context, ModelProcessingPhase phase);
160 @Nonnull <K, N extends StatementNamespace<K, ?, ? >> Prerequisite<StmtContext<?,?,?>> requiresCtx(StmtContext<?, ?, ?> context, Class<N> namespace, K key, ModelProcessingPhase phase);
162 @Nonnull <C extends StmtContext.Mutable<?,?,?>, CT extends C> Prerequisite<C> mutatesCtx(CT root, ModelProcessingPhase phase);