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.annotations.Beta;
11 import java.util.Optional;
12 import org.eclipse.jdt.annotation.NonNull;
13 import org.eclipse.jdt.annotation.Nullable;
14 import org.opendaylight.yangtools.yang.common.QName;
15 import org.opendaylight.yangtools.yang.common.QNameModule;
16 import org.opendaylight.yangtools.yang.model.api.meta.ArgumentDefinition;
17 import org.opendaylight.yangtools.yang.model.api.meta.DeclaredStatement;
18 import org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement;
19 import org.opendaylight.yangtools.yang.model.api.meta.StatementDefinition;
20 import org.opendaylight.yangtools.yang.parser.spi.source.SourceException;
23 * Support for processing concrete YANG statement.
26 * This interface is intended to be implemented by developers, which want to introduce support of statement to parser.
27 * Consider subclassing {@link AbstractStatementSupport} for easier implementation of this interface.
29 * @param <A> Argument type
30 * @param <D> Declared Statement representation
31 * @param <E> Effective Statement representation
33 public interface StatementSupport<A, D extends DeclaredStatement<A>, E extends EffectiveStatement<A, D>>
34 extends StatementDefinition, StatementFactory<A, D, E> {
36 * Returns public statement definition, which will be present in built statements.
39 * Public statement definition may be used to provide different implementation of statement definition,
40 * which will not retain any build specific data or context.
42 * @return public statement definition, which will be present in built statements.
44 @NonNull StatementDefinition getPublicView();
47 * Parses textual representation of argument in object representation.
49 * @param ctx Context, which may be used to access source-specific namespaces required for parsing.
50 * @param value String representation of value, as was present in text source.
51 * @return Parsed value
52 * @throws SourceException when an inconsistency is detected.
54 A parseArgumentValue(StmtContext<?, ?, ?> ctx, String value);
57 * Adapts the argument value to match a new module.
59 * @param ctx Context, which may be used to access source-specific namespaces required for parsing.
60 * @param targetModule Target module, may not be null.
61 * @return Adapted argument value. The default implementation returns original value stored in context.
63 default A adaptArgumentValue(final StmtContext<A, D, E> ctx, final QNameModule targetModule) {
64 return ctx.argument();
68 * Invoked when a statement supported by this instance is added to build context. This allows implementations
69 * of this interface to start tracking the statement and perform any modifications to the build context hierarchy,
70 * accessible via {@link StmtContext#getParentContext()}. One such use is populating the parent's namespaces to
71 * allow it to locate this child statement.
73 * @param stmt Context of added statement. No substatements are available.
75 void onStatementAdded(StmtContext.Mutable<A, D, E> stmt);
78 * Invoked when statement is closed during {@link ModelProcessingPhase#SOURCE_PRE_LINKAGE} phase, only substatements
79 * from this and previous phase are available.
82 * Implementation may use method to perform actions on this event or register modification action using
83 * {@link StmtContext.Mutable#newInferenceAction(ModelProcessingPhase)}.
85 * @param stmt Context of added statement.
87 void onPreLinkageDeclared(StmtContext.Mutable<A, D, E> stmt);
90 * Invoked when statement is closed during {@link ModelProcessingPhase#SOURCE_LINKAGE} phase, only substatements
91 * from this and previous phase are available.
94 * Implementation may use method to perform actions on this event or register modification action using
95 * {@link StmtContext.Mutable#newInferenceAction(ModelProcessingPhase)}.
97 * @param stmt Context of added statement.
98 * @throws SourceException when an inconsistency is detected.
100 void onLinkageDeclared(StmtContext.Mutable<A, D, E> stmt);
103 * Invoked when statement is closed during {@link ModelProcessingPhase#STATEMENT_DEFINITION} phase,
104 * only substatements from this phase are available.
107 * Implementation may use method to perform actions on this event or register modification action using
108 * {@link StmtContext.Mutable#newInferenceAction(ModelProcessingPhase)}.
110 * @param stmt Context of added statement. Argument and statement parent is accessible.
111 * @throws SourceException when an inconsistency is detected.
113 void onStatementDefinitionDeclared(StmtContext.Mutable<A, D, E> stmt);
116 * Invoked when statement is closed during {@link ModelProcessingPhase#FULL_DECLARATION} phase,
117 * only substatements from this phase are available.
120 * Implementation may use method to perform actions on this event or register modification action using
121 * {@link StmtContext.Mutable#newInferenceAction(ModelProcessingPhase)}.
123 * @param stmt Context of added statement. Argument and statement parent is accessible.
124 * @throws SourceException when an inconsistency is detected.
126 void onFullDefinitionDeclared(StmtContext.Mutable<A, D, E> stmt);
129 * Returns true if this support has argument specific supports.
131 boolean hasArgumentSpecificSupports();
134 * If this support has argument specific supports, the method returns support specific for given argument
135 * (e.g. type statement support need to be specialized based on its argument), otherwise returns null.
137 * @param argument argument of statement
138 * @return statement support specific for supplied argument or null
140 @Nullable StatementSupport<?, ?, ?> getSupportSpecificForArgument(String argument);
143 * Return this statement's {@link CopyPolicy}. This is a static value, reflecting how this statement reacts to being
144 * replicated to a different context, without reflecting on behaviour of potential substatements, which would come
145 * into play in something like:
159 * description "Can be used in description/reference statements to attach additional notes";
162 * description "A nice module extending description statement semantics" {
163 * foo:note "We can now attach description/reference a note.";
164 * foo:note "Also another note";
171 * In this scenario, it is the reactor's job to figure out what to do (like talking to substatements).
173 * @return This statement's copy policy
175 @NonNull CopyPolicy copyPolicy();
178 * Given a raw string representation of an argument, try to use a shared representation.
180 * @param rawArgument Argument string
181 * @return A potentially-shard instance
183 default String internArgument(final String rawArgument) {
188 * Returns unknown statement form of a regular YANG statement supplied as a parameter to the method.
190 * @param yangStmtDef statement definition of a regular YANG statement
191 * @return Optional of unknown statement form of a regular YANG statement or empty() if it is not supported by this
194 default Optional<StatementSupport<?, ?, ?>> getUnknownStatementDefinitionOf(final StatementDefinition yangStmtDef) {
195 return Optional.empty();
199 * Returns true if this statement support and all its substatements ignore if-feature statements (e.g. yang-data
200 * extension defined in <a href="https://tools.ietf.org/html/rfc8040#section-8">RFC 8040</a>). Default
201 * implementation returns false.
203 * @return true if this statement support ignores if-feature statements,
207 default boolean isIgnoringIfFeatures() {
212 * Returns true if this statement support and all its substatements ignore config statements (e.g. yang-data
213 * extension defined in <a href="https://tools.ietf.org/html/rfc8040#section-8">RFC 8040</a>). Default
214 * implementation returns false.
216 * @return true if this statement support ignores config statements,
220 default boolean isIgnoringConfig() {
225 default QName getStatementName() {
226 return getPublicView().getStatementName();
230 default @NonNull Optional<ArgumentDefinition> getArgumentDefinition() {
231 return getPublicView().getArgumentDefinition();
235 default Class<? extends DeclaredStatement<?>> getDeclaredRepresentationClass() {
236 return getPublicView().getDeclaredRepresentationClass();
240 default Class<? extends EffectiveStatement<?,?>> getEffectiveRepresentationClass() {
241 return getPublicView().getEffectiveRepresentationClass();
245 * Statement context copy policy, indicating how should reactor handle statement copy operations. Every statement
246 * copied by the reactor is subject to this policy.
250 * Reuse the source statement context in the new place, as it cannot be affected by any further operations. This
251 * implies that the semantics of the effective statement are not affected by any of its substatements. Each
252 * of the substatements is free to make its own policy.
255 * This policy is typically used by static constant statements such as {@code description} or {@code length},
256 * where the baseline RFC7950 does not allow any impact. A {@code description} could hold an extension statement
257 * in which case this interaction would come into play. Normal YANG will see empty substatements, so the reactor
258 * will be free to complete reuse the context.
261 * In case any substatement is of stronger policy, it is up to the reactor to handle correct handling of
262 * resulting subobjects.
264 // TODO: does this mean source must have transitioned to ModelProcessingPhase.EFFECTIVE_MODEL?
267 * Create a copy sharing declared instance, but otherwise having a separate disconnected lifecycle.
269 // TODO: will the copy transition to ModelProcessingPhase.FULL_DECLARATION or which phase?
272 * Reject any attempt to copy this statement. This is useful for statements that are defined as top-level
273 * constructs, such as {@code contact}, {@code deviation} and similar.
277 * Ignore this statement's existence for the purposes of the new place -- it is not impacted. This guidance
278 * is left here for completeness, as it can have justifiable uses (but I can't think of any). Any substatements
279 * need to be ignored, too.