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 public interface Prerequisite<T> extends Supplier<T> {
89 * Returns associated prerequisite once it is resolved.
91 * @return associated prerequisite once it is resolved.
102 * User-defined inference action.
105 public interface InferenceAction {
108 * Invoked once all prerequisites were met and forward references
109 * were resolved and inference action should be applied.
111 * Implementors may do necessary changes to mutable objects
112 * which were declared.
114 * @throws InferenceException If inference action can not be processed.
115 * Note that this exception be used for user to debug YANG sources,
116 * so should provide helpful context to fix issue in sources.
118 void apply() throws InferenceException;
121 * Invoked once one of prerequisites was not met,
122 * even after all other satifiable inference actions were processed.
124 * Implementors MUST throw {@link InferenceException} if semantic processing
125 * of model should be stopped and failed.
127 * List of failed prerequisites should be used to select right message / error
128 * type to debug problem in YANG sources.
130 * @throws InferenceException If inference action can not be processed.
131 * Note that this exception be used for user to debug YANG sources,
132 * so should provide helpful context to fix issue in sources.
134 void prerequisiteFailed(Collection<? extends Prerequisite<?>> failed) throws InferenceException;
137 @Nonnull <D extends DeclaredStatement<?>> Prerequisite<D> requiresDeclared(StmtContext<?,? extends D,?> context);
139 @Nonnull <K, D extends DeclaredStatement<?>, N extends StatementNamespace<K, ? extends D, ?>> Prerequisite<D> requiresDeclared(StmtContext<?,?,?> context,Class<N> namespace, K key);
141 @Nonnull <K, D extends DeclaredStatement<?>, N extends StatementNamespace<K, ? extends D, ?>> Prerequisite<StmtContext<?, D, ?>>requiresDeclaredCtx(StmtContext<?,?,?> context,Class<N> namespace, K key);
143 @Nonnull <E extends EffectiveStatement<?,?>> Prerequisite<E> requiresEffective(StmtContext<?,?,? extends E> stmt);
145 @Nonnull <K, E extends EffectiveStatement<?, ?>, N extends StatementNamespace<K, ?, ? extends E>> Prerequisite<E> requiresEffective(StmtContext<?,?,?> context,Class<N> namespace, K key);
147 @Nonnull <K, E extends EffectiveStatement<?, ?>, N extends StatementNamespace<K, ?, ? extends E>> Prerequisite<StmtContext<?,?,E>> requiresEffectiveCtx(StmtContext<?,?,?> context,Class<N> namespace, K key);
149 @Nonnull <N extends IdentifierNamespace<? ,?>> Prerequisite<Mutable<?,?,?>> mutatesNs(Mutable<?,?, ?> ctx, Class<N> namespace);
151 @Nonnull <T extends Mutable<?,?,?>> Prerequisite<T> mutatesEffectiveCtx(T stmt);
153 @Nonnull <K,E extends EffectiveStatement<?,?>,N extends StatementNamespace<K, ?, ? extends E>> Prerequisite<Mutable<?,?,E>> mutatesEffectiveCtx(StmtContext<?,?,?> context,Class<N> namespace, K key);
155 void apply(InferenceAction action) throws InferenceException;
157 @Nonnull <A,D extends DeclaredStatement<A>,E extends EffectiveStatement<A, D>> Prerequisite<StmtContext<A, D, E>> requiresCtx(StmtContext<A, D, E> context, ModelProcessingPhase phase);
159 @Nonnull <K, N extends StatementNamespace<K, ?, ? >> Prerequisite<StmtContext<?,?,?>> requiresCtx(StmtContext<?, ?, ?> context, Class<N> namespace, K key, ModelProcessingPhase phase);
161 @Nonnull <C extends StmtContext.Mutable<?,?,?>, CT extends C> Prerequisite<C> mutatesCtx(CT root, ModelProcessingPhase phase);