org.opendaylight.yangtools.yang.parser.spi.meta

Interface ModelActionBuilder

public interface ModelActionBuilder

Builder for effective model inference action. Model inference action is core principle of transforming declared model into effective model.

Since YANG allows forward references, some inference actions need to be taken at a later point, where reference is actually resolved. Referenced objects are not retrieved directly but are represented as ModelActionBuilder.Prerequisite (prerequisite) for inference action to be taken.

Some existing YANG statements are more complex and also object, for which effective model may be inferred is also represented as a ModelActionBuilder.Prerequisite which, when reference is available, will contain target context, which may be used for inference action.

Implementing inference action

Effective inference action could always be splitted into two separate tasks:

1. Declaration of inference action and its prerequisites
2. Execution of inference action

In order to declare inference action following steps needs to be taken:

1. Use StmtContext.Mutable.newInferenceAction(ModelProcessingPhase) to obtain ModelActionBuilder.
2. Use builder to specify concrete prerequisites of inference action (other statements, values from identifier namespaces)
3. Use builder to specify concrete set of nodes (or forward references to nodes) which will inference action mutate.
4. Use apply(InferenceAction) with ModelActionBuilder.InferenceAction implementation to register inference action.

An action will be executed when:

• InferenceAction#apply(InferenceContext) - all prerequisites (and declared forward references) are met, action could dereference them and start applying changes.
• ModelActionBuilder.InferenceAction.prerequisiteFailed(Collection) - semantic parser finished all other satisfied inference actions and some of declared prerequisites was still not met.

TODO: Insert real word example

Design notes

Future seems as viable and more standard alternative to ModelActionBuilder.Prerequisite, but Futures also carries promise that resolution of it is carried in other thread, which will actually put additional constraints on semantic parser.

Also listening on multiple futures is costly, so we opted out of future and designed API, which later may introduce futures.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	ModelActionBuilder.InferenceAction User-defined inference action.
static interface	ModelActionBuilder.InferenceContext
static interface	ModelActionBuilder.Prerequisite<T>

Method Summary

Modifier and Type	Method and Description
void	apply(ModelActionBuilder.InferenceAction action) Apply an ModelActionBuilder.InferenceAction when this action's prerequisites are resolved.
<C extends StmtContext.Mutable<?,?,?>,T extends C> @NonNull ModelActionBuilder.Prerequisite<C>	mutatesCtx(T context, ModelProcessingPhase phase) Action mutates the specified statement in the specified phase.
<K,E extends EffectiveStatement<?,?>,N extends IdentifierNamespace<K,? extends StmtContext<?,?,?>>> @NonNull ModelActionBuilder.Prerequisite<StmtContext.Mutable<?,?,E>>	mutatesEffectiveCtx(StmtContext<?,?,?> context, Class<N> namespace, K key)
default <T extends StmtContext.Mutable<?,?,?>> @NonNull ModelActionBuilder.Prerequisite<T>	mutatesEffectiveCtx(T context) Action mutates the effective model of specified statement.
default <K,E extends EffectiveStatement<?,?>,N extends IdentifierNamespace<K,? extends StmtContext<?,?,?>>> @NonNull ModelActionBuilder.Prerequisite<StmtContext.Mutable<?,?,E>>	mutatesEffectiveCtxPath(StmtContext<?,?,?> context, Class<N> namespace, Iterable<K> keys)
<N extends IdentifierNamespace<?,?>> @NonNull ModelActionBuilder.Prerequisite<StmtContext.Mutable<?,?,?>>	mutatesNs(StmtContext.Mutable<?,?,?> ctx, Class<N> namespace) Deprecated. Undocumented method. Use at your own risk.
<K,N extends StatementNamespace<K,?,?>> @NonNull ModelActionBuilder.Prerequisite<StmtContext<?,?,?>>	requiresCtx(StmtContext<?,?,?> context, Class<N> namespace, K key, ModelProcessingPhase phase)
<K,N extends StatementNamespace<K,?,?>> @NonNull ModelActionBuilder.Prerequisite<StmtContext<?,?,?>>	requiresCtx(StmtContext<?,?,?> context, Class<N> namespace, NamespaceKeyCriterion<K> criterion, ModelProcessingPhase phase)
<A,D extends DeclaredStatement<A>,E extends EffectiveStatement<A,D>> @NonNull ModelActionBuilder.Prerequisite<StmtContext<A,D,E>>	requiresCtx(StmtContext<A,D,E> context, ModelProcessingPhase phase) Action requires that the specified context completes specified phase before apply(InferenceAction) may be invoked.
<K,D extends DeclaredStatement<?>,N extends StatementNamespace<K,? extends D,?>> @NonNull ModelActionBuilder.Prerequisite<D>	requiresDeclared(StmtContext<?,?,?> context, Class<N> namespace, K key) Deprecated. Undocumented method. Use at your own risk.
<D extends DeclaredStatement<?>> @NonNull ModelActionBuilder.Prerequisite<D>	requiresDeclared(StmtContext<?,? extends D,?> context) Action requires that the specified context transition to complete ModelProcessingPhase.FULL_DECLARATION phase and produce a declared statement.
<K,D extends DeclaredStatement<?>,N extends StatementNamespace<K,? extends D,?>> @NonNull ModelActionBuilder.Prerequisite<StmtContext<?,D,?>>	requiresDeclaredCtx(StmtContext<?,?,?> context, Class<N> namespace, K key) Deprecated. Undocumented method. Use at your own risk.
<K,E extends EffectiveStatement<?,?>,N extends StatementNamespace<K,?,? extends E>> @NonNull ModelActionBuilder.Prerequisite<E>	requiresEffective(StmtContext<?,?,?> context, Class<N> namespace, K key) Deprecated. Undocumented method. Use at your own risk.
<E extends EffectiveStatement<?,?>> @NonNull ModelActionBuilder.Prerequisite<E>	requiresEffective(StmtContext<?,?,? extends E> stmt) Deprecated. Undocumented method. Use at your own risk.
<K,E extends EffectiveStatement<?,?>,N extends StatementNamespace<K,?,? extends E>> @NonNull ModelActionBuilder.Prerequisite<StmtContext<?,?,E>>	requiresEffectiveCtx(StmtContext<?,?,?> context, Class<N> namespace, K key) Deprecated. Undocumented method. Use at your own risk.

Method Detail

requiresDeclared

<D extends DeclaredStatement<?>> @NonNull ModelActionBuilder.Prerequisite<D> requiresDeclared(StmtContext<?,? extends D,?> context)

Action requires that the specified context transition to complete ModelProcessingPhase.FULL_DECLARATION phase and produce a declared statement.

Parameters:

context - Statement context which needs to complete the transition.

Returns:

A ModelActionBuilder.Prerequisite returning the declared statement of the requested context.

requiresDeclared

@Deprecated
<K,D extends DeclaredStatement<?>,N extends StatementNamespace<K,? extends D,?>> @NonNull ModelActionBuilder.Prerequisite<D> requiresDeclared(StmtContext<?,?,?> context,
                                                                                                                                                          Class<N> namespace,
                                                                                                                                                          K key)

Deprecated. Undocumented method. Use at your own risk.

Create a requirement on specified statement to be declared.

requiresCtx

<A,D extends DeclaredStatement<A>,E extends EffectiveStatement<A,D>> @NonNull ModelActionBuilder.Prerequisite<StmtContext<A,D,E>> requiresCtx(StmtContext<A,D,E> context,
                                                                                                                                              ModelProcessingPhase phase)

Action requires that the specified context completes specified phase before apply(InferenceAction) may be invoked.

Parameters:

context - Statement context which needs to complete the transition.

phase - ModelProcessingPhase which must have completed

Returns:

A ModelActionBuilder.Prerequisite returning the requested context.

requiresCtx

<K,N extends StatementNamespace<K,?,?>> @NonNull ModelActionBuilder.Prerequisite<StmtContext<?,?,?>> requiresCtx(StmtContext<?,?,?> context,
                                                                                                                 Class<N> namespace,
                                                                                                                 K key,
                                                                                                                 ModelProcessingPhase phase)

requiresCtx

<K,N extends StatementNamespace<K,?,?>> @NonNull ModelActionBuilder.Prerequisite<StmtContext<?,?,?>> requiresCtx(StmtContext<?,?,?> context,
                                                                                                                 Class<N> namespace,
                                                                                                                 NamespaceKeyCriterion<K> criterion,
                                                                                                                 ModelProcessingPhase phase)

mutatesEffectiveCtx

default <T extends StmtContext.Mutable<?,?,?>> @NonNull ModelActionBuilder.Prerequisite<T> mutatesEffectiveCtx(T context)

Action mutates the effective model of specified statement. This is a shorthand for mutatesCtx(context, EFFECTIVE_MODEL.

Parameters:

context - Target statement context

Returns:

A ModelActionBuilder.Prerequisite returning the requested context.

mutatesEffectiveCtx

<K,E extends EffectiveStatement<?,?>,N extends IdentifierNamespace<K,? extends StmtContext<?,?,?>>> @NonNull ModelActionBuilder.Prerequisite<StmtContext.Mutable<?,?,E>> mutatesEffectiveCtx(StmtContext<?,?,?> context,
                                                                                                                                                                                             Class<N> namespace,
                                                                                                                                                                                             K key)

mutatesEffectiveCtxPath

default <K,E extends EffectiveStatement<?,?>,N extends IdentifierNamespace<K,? extends StmtContext<?,?,?>>> @NonNull ModelActionBuilder.Prerequisite<StmtContext.Mutable<?,?,E>> mutatesEffectiveCtxPath(StmtContext<?,?,?> context,
                                                                                                                                                                                                         Class<N> namespace,
                                                                                                                                                                                                         Iterable<K> keys)

mutatesCtx

<C extends StmtContext.Mutable<?,?,?>,T extends C> @NonNull ModelActionBuilder.Prerequisite<C> mutatesCtx(T context,
                                                                                                          ModelProcessingPhase phase)

Action mutates the specified statement in the specified phase. Target statement cannot complete specified phase before this action is applier.

Parameters:

context - Target statement context

Returns:

A ModelActionBuilder.Prerequisite returning the requested context.

apply

void apply(ModelActionBuilder.InferenceAction action)

Apply an ModelActionBuilder.InferenceAction when this action's prerequisites are resolved.

Parameters:

action - Inference action to apply

Throws:

InferenceException - if the action fails

NullPointerException - if action is null

IllegalStateException - if this action has an inference action already associated.

requiresDeclaredCtx

@Deprecated
<K,D extends DeclaredStatement<?>,N extends StatementNamespace<K,? extends D,?>> @NonNull ModelActionBuilder.Prerequisite<StmtContext<?,D,?>> requiresDeclaredCtx(StmtContext<?,?,?> context,
                                                                                                                                                                              Class<N> namespace,
                                                                                                                                                                              K key)

Deprecated. Undocumented method. Use at your own risk.

Create a requirement on specified statement context to be declared.

requiresEffective

@Deprecated
<E extends EffectiveStatement<?,?>> @NonNull ModelActionBuilder.Prerequisite<E> requiresEffective(StmtContext<?,?,? extends E> stmt)

Deprecated. Undocumented method. Use at your own risk.

Create a requirement on specified statement to become effective.

requiresEffective

@Deprecated
<K,E extends EffectiveStatement<?,?>,N extends StatementNamespace<K,?,? extends E>> @NonNull ModelActionBuilder.Prerequisite<E> requiresEffective(StmtContext<?,?,?> context,
                                                                                                                                                              Class<N> namespace,
                                                                                                                                                              K key)

Deprecated. Undocumented method. Use at your own risk.

Create a requirement on specified statement to become effective.

requiresEffectiveCtx

@Deprecated
<K,E extends EffectiveStatement<?,?>,N extends StatementNamespace<K,?,? extends E>> @NonNull ModelActionBuilder.Prerequisite<StmtContext<?,?,E>> requiresEffectiveCtx(StmtContext<?,?,?> context,
                                                                                                                                                                                  Class<N> namespace,
                                                                                                                                                                                  K key)

Deprecated. Undocumented method. Use at your own risk.

Create a requirement on specified statement context to become effective.

mutatesNs

@Deprecated
<N extends IdentifierNamespace<?,?>> @NonNull ModelActionBuilder.Prerequisite<StmtContext.Mutable<?,?,?>> mutatesNs(StmtContext.Mutable<?,?,?> ctx,
                                                                                                                                Class<N> namespace)

Deprecated. Undocumented method. Use at your own risk.

Mark the fact that this action is mutating a namespace.