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.meta.StmtContext.Mutable;
21 import org.opendaylight.yangtools.yang.parser.spi.source.SourceException;
24 * Support for processing concrete YANG statement.
27 * This interface is intended to be implemented by developers, which want to introduce support of statement to parser.
28 * Consider subclassing {@link AbstractStatementSupport} for easier implementation of this interface.
30 * @param <A> Argument type
31 * @param <D> Declared Statement representation
32 * @param <E> Effective Statement representation
34 public interface StatementSupport<A, D extends DeclaredStatement<A>, E extends EffectiveStatement<A, D>>
35 extends StatementDefinition, StatementFactory<A, D, E> {
37 * Returns public statement definition, which will be present in built statements.
40 * Public statement definition may be used to provide different implementation of statement definition,
41 * which will not retain any build specific data or context.
43 * @return public statement definition, which will be present in built statements.
45 @NonNull StatementDefinition getPublicView();
48 * Parses textual representation of argument in object representation.
50 * @param ctx Context, which may be used to access source-specific namespaces required for parsing.
51 * @param value String representation of value, as was present in text source.
52 * @return Parsed value
53 * @throws SourceException when an inconsistency is detected.
55 A parseArgumentValue(StmtContext<?, ?, ?> ctx, String value);
58 * Adapts the argument value to match a new module.
60 * @param ctx Context, which may be used to access source-specific namespaces required for parsing.
61 * @param targetModule Target module, may not be null.
62 * @return Adapted argument value. The default implementation returns original value stored in context.
64 default A adaptArgumentValue(final StmtContext<A, D, E> ctx, final QNameModule targetModule) {
65 return ctx.getStatementArgument();
69 * Invoked when a statement supported by this instance is added to build context. This allows implementations
70 * of this interface to start tracking the statement and perform any modifications to the build context hierarchy,
71 * accessible via {@link StmtContext#getParentContext()}. One such use is populating the parent's namespaces to
72 * allow it to locate this child statement.
74 * @param stmt Context of added statement. No substatements are available.
76 void onStatementAdded(StmtContext.Mutable<A, D, E> stmt);
79 * Invoked when statement is closed during {@link ModelProcessingPhase#SOURCE_PRE_LINKAGE} phase, only substatements
80 * from this and previous phase are available.
83 * Implementation may use method to perform actions on this event or register modification action using
84 * {@link StmtContext.Mutable#newInferenceAction(ModelProcessingPhase)}.
86 * @param stmt Context of added statement.
88 void onPreLinkageDeclared(StmtContext.Mutable<A, D, E> stmt);
91 * Invoked when statement is closed during {@link ModelProcessingPhase#SOURCE_LINKAGE} phase, only substatements
92 * from this and previous phase are available.
95 * Implementation may use method to perform actions on this event or register modification action using
96 * {@link StmtContext.Mutable#newInferenceAction(ModelProcessingPhase)}.
98 * @param stmt Context of added statement.
99 * @throws SourceException when an inconsistency is detected.
101 void onLinkageDeclared(StmtContext.Mutable<A, D, E> stmt);
104 * Invoked when statement is closed during {@link ModelProcessingPhase#STATEMENT_DEFINITION} phase,
105 * only substatements from this phase are available.
108 * Implementation may use method to perform actions on this event or register modification action using
109 * {@link StmtContext.Mutable#newInferenceAction(ModelProcessingPhase)}.
111 * @param stmt Context of added statement. Argument and statement parent is accessible.
112 * @throws SourceException when an inconsistency is detected.
114 void onStatementDefinitionDeclared(StmtContext.Mutable<A, D, E> stmt);
117 * Invoked when statement is closed during {@link ModelProcessingPhase#FULL_DECLARATION} phase,
118 * only substatements from this phase are available.
121 * Implementation may use method to perform actions on this event or register modification action using
122 * {@link StmtContext.Mutable#newInferenceAction(ModelProcessingPhase)}.
124 * @param stmt Context of added statement. Argument and statement parent is accessible.
125 * @throws SourceException when an inconsistency is detected.
127 void onFullDefinitionDeclared(StmtContext.Mutable<A, D, E> stmt);
130 * Returns true if this support has argument specific supports.
132 boolean hasArgumentSpecificSupports();
135 * If this support has argument specific supports, the method returns support specific for given argument
136 * (e.g. type statement support need to be specialized based on its argument), otherwise returns null.
138 * @param argument argument of statement
139 * @return statement support specific for supplied argument or null
141 @Nullable StatementSupport<?, ?, ?> getSupportSpecificForArgument(String argument);
144 * Create an optional copy of specified statement as a substatement of parent.
147 * Note that while it may be tempting to return the same context, this is not safe in general case. It is only safe
148 * if the entire subtree is unaffected by changes to parent/namespace/history. This includes the semantics of this
149 * statement (it cannot be a target of any inference effects) as well as any substatements -- an extension statement
150 * is allowed pretty much anywhere and if its semantics are context-dependent, a simple instance reuse will not
153 * @param stmt Context of statement to be copied statement.
154 * @param parent Parent statement context
155 * @param type Type of copy being performed
156 * @param targetModule Target module, if present
157 * @return Empty if the statement should be ignored, or present with an instance that should be copied into parent.
159 @NonNull Optional<? extends Mutable<?, ?, ?>> copyAsChildOf(Mutable<?, ?, ?> stmt, Mutable<?, ?, ?> parent,
160 CopyType type, @Nullable QNameModule targetModule);
163 * Given a raw string representation of an argument, try to use a shared representation.
165 * @param rawArgument Argument string
166 * @return A potentially-shard instance
168 default String internArgument(final String rawArgument) {
173 * Returns unknown statement form of a regular YANG statement supplied as a parameter to the method.
175 * @param yangStmtDef statement definition of a regular YANG statement
176 * @return Optional of unknown statement form of a regular YANG statement or empty() if it is not supported by this
179 default Optional<StatementSupport<?, ?, ?>> getUnknownStatementDefinitionOf(final StatementDefinition yangStmtDef) {
180 return Optional.empty();
184 * Returns true if this statement support and all its substatements ignore if-feature statements (e.g. yang-data
185 * extension defined in <a href="https://tools.ietf.org/html/rfc8040#section-8">RFC 8040</a>). Default
186 * implementation returns false.
188 * @return true if this statement support ignores if-feature statements,
192 default boolean isIgnoringIfFeatures() {
197 * Returns true if this statement support and all its substatements ignore config statements (e.g. yang-data
198 * extension defined in <a href="https://tools.ietf.org/html/rfc8040#section-8">RFC 8040</a>). Default
199 * implementation returns false.
201 * @return true if this statement support ignores config statements,
205 default boolean isIgnoringConfig() {
210 default QName getStatementName() {
211 return getPublicView().getStatementName();
215 default @NonNull Optional<ArgumentDefinition> getArgumentDefinition() {
216 return getPublicView().getArgumentDefinition();
220 default Class<? extends DeclaredStatement<?>> getDeclaredRepresentationClass() {
221 return getPublicView().getDeclaredRepresentationClass();
225 default Class<? extends EffectiveStatement<?,?>> getEffectiveRepresentationClass() {
226 return getPublicView().getEffectiveRepresentationClass();