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)
<C extends StmtContext.Mutable<?,?,?>,CT extends C> ModelActionBuilder.Prerequisite<C>	mutatesCtx(CT root, ModelProcessingPhase phase)
<K,E extends org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement<?,?>,N extends org.opendaylight.yangtools.yang.model.api.meta.IdentifierNamespace<K,? extends StmtContext<?,?,?>>> ModelActionBuilder.Prerequisite<StmtContext.Mutable<?,?,E>>	mutatesEffectiveCtx(StmtContext<?,?,?> context, Class<N> namespace, K key)
default <T extends StmtContext.Mutable<?,?,?>> ModelActionBuilder.Prerequisite<T>	mutatesEffectiveCtx(T stmt)
<N extends org.opendaylight.yangtools.yang.model.api.meta.IdentifierNamespace<?,?>> ModelActionBuilder.Prerequisite<StmtContext.Mutable<?,?,?>>	mutatesNs(StmtContext.Mutable<?,?,?> ctx, Class<N> namespace) Deprecated. Undocumented method. Use at your own risk.
<K,N extends StatementNamespace<K,?,?>> ModelActionBuilder.Prerequisite<StmtContext<?,?,?>>	requiresCtx(StmtContext<?,?,?> context, Class<N> namespace, K key, ModelProcessingPhase phase)
<K,N extends StatementNamespace<K,?,?>> ModelActionBuilder.Prerequisite<StmtContext<?,?,?>>	requiresCtx(StmtContext<?,?,?> context, Class<N> namespace, NamespaceKeyCriterion<K> criterion, ModelProcessingPhase phase)
<A,D extends org.opendaylight.yangtools.yang.model.api.meta.DeclaredStatement<A>,E extends org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement<A,D>> ModelActionBuilder.Prerequisite<StmtContext<A,D,E>>	requiresCtx(StmtContext<A,D,E> context, ModelProcessingPhase phase) Action requires that the specified context completes specified phase.
<K,D extends org.opendaylight.yangtools.yang.model.api.meta.DeclaredStatement<?>,N extends StatementNamespace<K,? extends D,?>> ModelActionBuilder.Prerequisite<D>	requiresDeclared(StmtContext<?,?,?> context, Class<N> namespace, K key) Deprecated. Undocumented method. Use at your own risk.
<D extends org.opendaylight.yangtools.yang.model.api.meta.DeclaredStatement<?>> 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 org.opendaylight.yangtools.yang.model.api.meta.DeclaredStatement<?>,N extends StatementNamespace<K,? extends D,?>> ModelActionBuilder.Prerequisite<StmtContext<?,D,?>>	requiresDeclaredCtx(StmtContext<?,?,?> context, Class<N> namespace, K key) Deprecated. Undocumented method. Use at your own risk.
<K,E extends org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement<?,?>,N extends StatementNamespace<K,?,? extends E>> ModelActionBuilder.Prerequisite<E>	requiresEffective(StmtContext<?,?,?> context, Class<N> namespace, K key) Deprecated. Undocumented method. Use at your own risk.
<E extends org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement<?,?>> ModelActionBuilder.Prerequisite<E>	requiresEffective(StmtContext<?,?,? extends E> stmt) Deprecated. Undocumented method. Use at your own risk.
<K,E extends org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement<?,?>,N extends StatementNamespace<K,?,? extends E>> ModelActionBuilder.Prerequisite<StmtContext<?,?,E>>	requiresEffectiveCtx(StmtContext<?,?,?> context, Class<N> namespace, K key) Deprecated. Undocumented method. Use at your own risk.

Method Detail

requiresDeclared

@Nonnull
<D extends org.opendaylight.yangtools.yang.model.api.meta.DeclaredStatement<?>> 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
 @Nonnull
<K,D extends org.opendaylight.yangtools.yang.model.api.meta.DeclaredStatement<?>,N extends StatementNamespace<K,? extends D,?>> 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

@Nonnull
<A,D extends org.opendaylight.yangtools.yang.model.api.meta.DeclaredStatement<A>,E extends org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement<A,D>> ModelActionBuilder.Prerequisite<StmtContext<A,D,E>> requiresCtx(StmtContext<A,D,E> context,
                                                                                                                                                                                                                                            ModelProcessingPhase phase)

Action requires that the specified context completes specified phase.

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

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

requiresCtx

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

mutatesEffectiveCtx

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

mutatesEffectiveCtx

@Nonnull
<K,E extends org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement<?,?>,N extends org.opendaylight.yangtools.yang.model.api.meta.IdentifierNamespace<K,? extends StmtContext<?,?,?>>> ModelActionBuilder.Prerequisite<StmtContext.Mutable<?,?,E>> mutatesEffectiveCtx(StmtContext<?,?,?> context,
                                                                                                                                                                                                                                                                                           Class<N> namespace,
                                                                                                                                                                                                                                                                                           K key)

mutatesCtx

@Nonnull
<C extends StmtContext.Mutable<?,?,?>,CT extends C> ModelActionBuilder.Prerequisite<C> mutatesCtx(CT root,
                                                                                                           ModelProcessingPhase phase)

apply

void apply(ModelActionBuilder.InferenceAction action)
    throws InferenceException

Throws:

InferenceException

requiresDeclaredCtx

@Deprecated
 @Nonnull
<K,D extends org.opendaylight.yangtools.yang.model.api.meta.DeclaredStatement<?>,N extends StatementNamespace<K,? extends D,?>> 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
 @Nonnull
<E extends org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement<?,?>> 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
 @Nonnull
<K,E extends org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement<?,?>,N extends StatementNamespace<K,?,? extends E>> 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
 @Nonnull
<K,E extends org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement<?,?>,N extends StatementNamespace<K,?,? extends E>> 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
 @Nonnull
<N extends org.opendaylight.yangtools.yang.model.api.meta.IdentifierNamespace<?,?>> 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.