yang/yang-parser-impl/src/main/java/org/opendaylight/yangtools/yang/parser/spi/meta/StatementSupport.java

   1 /*
   2  * Copyright (c) 2015 Cisco Systems, Inc. and others.  All rights reserved.
   3  *
   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
   7  */
   8
   9 package org.opendaylight.yangtools.yang.parser.spi.meta;
  10
  11 import com.google.common.annotations.Beta;
  12 import java.util.Optional;
  13 import javax.annotation.Nullable;
  14 import org.opendaylight.yangtools.yang.common.QNameModule;
  15 import org.opendaylight.yangtools.yang.model.api.meta.DeclaredStatement;
  16 import org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement;
  17 import org.opendaylight.yangtools.yang.model.api.meta.StatementDefinition;
  18 import org.opendaylight.yangtools.yang.parser.spi.source.SourceException;
  19 import org.opendaylight.yangtools.yang.parser.stmt.reactor.StatementDefinitionContext;
  20
  21 /**
  22  * Support for processing concrete YANG statement.
  23  *
  24  * <p>
  25  * This interface is intended to be implemented by developers, which want to
  26  * introduce support of statement to parser. Consider subclassing
  27  * {@link AbstractStatementSupport} for easier implementation of this interface.
  28  *
  29  * @param <A>
  30  *            Argument type
  31  * @param <D>
  32  *            Declared Statement representation
  33  * @param <E>
  34  *            Effective Statement representation
  35  */
  36 public interface StatementSupport<A, D extends DeclaredStatement<A>, E extends EffectiveStatement<A, D>>
  37         extends StatementDefinition, StatementFactory<A, D, E> {
  38
  39     /**
  40      * Returns public statement definition, which will be present in built
  41      * statements.
  42      *
  43      * Public statement definition may be used to provide different
  44      * implementation of statement definition, which will not retain any build
  45      * specific data or context.
  46      *
  47      * @return public statement definition, which will be present in built
  48      *         statements.
  49      */
  50     StatementDefinition getPublicView();
  51
  52     /**
  53      * Parses textual representation of argument in object representation.
  54      *
  55      * @param ctx
  56      *            Context, which may be used to access source-specific
  57      *            namespaces required for parsing.
  58      * @param value
  59      *            String representation of value, as was present in text source.
  60      * @return Parsed value
  61      * @throws SourceException
  62      *             when an inconsistency is detected.
  63      */
  64     A parseArgumentValue(StmtContext<?, ?, ?> ctx, String value);
  65
  66     /**
  67      * Adapts the argument value to match a new module.
  68      *
  69      * @param ctx
  70      *            Context, which may be used to access source-specific
  71      *            namespaces required for parsing.
  72      * @param targetModule
  73      *            Target module, may not be null.
  74      * @return Adapted argument value. The default implementation returns original value stored in context.
  75      */
  76     default A adaptArgumentValue(final StmtContext<A, D, E> ctx, final QNameModule targetModule) {
  77         return ctx.getStatementArgument();
  78     }
  79
  80     /**
  81      * Invoked when a statement supported by this instance is added to build context. This allows implementations
  82      * of this interface to start tracking the statement and perform any modifications to the build context hierarchy,
  83      * accessible via {@link StmtContext#getParentContext()}. One such use is populating the parent's namespaces to
  84      * allow it to locate this child statement.
  85      *
  86      * @param stmt
  87      *            Context of added statement. No substatements are available.
  88      */
  89     void onStatementAdded(StmtContext.Mutable<A, D, E> stmt);
  90
  91     /**
  92      * Returns implicit parent statement support for supplied statement
  93      * definition, if it is defined. This allows implementations of this
  94      * interface add implicit parent to the build context hierarchy before a
  95      * substatement is created.
  96      *
  97      * @param stmtDef
  98      *            statement definition of substatement
  99      * @return optional of implicit parent statement support
 100      */
 101     Optional<StatementSupport<?, ?, ?>> getImplicitParentFor(final StatementDefinition stmtDef);
 102
 103     /**
 104      * Invoked when statement is closed during
 105      * {@link ModelProcessingPhase#SOURCE_PRE_LINKAGE} phase, only substatements
 106      * from this and previous phase are available.
 107      *
 108      * Implementation may use method to perform actions on this event or
 109      * register modification action using
 110      * {@link StmtContext.Mutable#newInferenceAction(ModelProcessingPhase)}.
 111      *
 112      * @param stmt
 113      *            Context of added statement.
 114      */
 115     void onPreLinkageDeclared(StmtContext.Mutable<A, D, E> stmt);
 116
 117     /**
 118      * Invoked when statement is closed during
 119      * {@link ModelProcessingPhase#SOURCE_LINKAGE} phase, only substatements
 120      * from this and previous phase are available.
 121      *
 122      * Implementation may use method to perform actions on this event or
 123      * register modification action using
 124      * {@link StmtContext.Mutable#newInferenceAction(ModelProcessingPhase)}.
 125      *
 126      * @param stmt
 127      *            Context of added statement.
 128      * @throws SourceException
 129      *             when an inconsistency is detected.
 130      */
 131     void onLinkageDeclared(StmtContext.Mutable<A, D, E> stmt);
 132
 133     /**
 134      * Invoked when statement is closed during
 135      * {@link ModelProcessingPhase#STATEMENT_DEFINITION} phase, only
 136      * substatements from this phase are available.
 137      *
 138      * Implementation may use method to perform actions on this event or
 139      * register modification action using
 140      * {@link StmtContext.Mutable#newInferenceAction(ModelProcessingPhase)}.
 141      *
 142      * @param stmt
 143      *            Context of added statement. Argument and statement parent is
 144      *            accessible.
 145      * @throws SourceException
 146      *             when an inconsistency is detected.
 147      */
 148     void onStatementDefinitionDeclared(StmtContext.Mutable<A, D, E> stmt);
 149
 150     /**
 151      * Invoked when statement is closed during
 152      * {@link ModelProcessingPhase#FULL_DECLARATION} phase.
 153      *
 154      * Invoked when statement is closed during
 155      * {@link ModelProcessingPhase#FULL_DECLARATION} phase, only substatements
 156      * from this phase are available.
 157      *
 158      * Implementation may use method to perform actions on this event or
 159      * register modification action using
 160      * {@link StmtContext.Mutable#newInferenceAction(ModelProcessingPhase)}.
 161      *
 162      *
 163      * @param stmt
 164      *            Context of added statement. Argument and statement parent is
 165      *            accessible.
 166      * @throws SourceException
 167      *             when an inconsistency is detected.
 168      */
 169     void onFullDefinitionDeclared(StmtContext.Mutable<A, D, E> stmt);
 170
 171     /**
 172      * Returns true if this support has argument specific supports.
 173      */
 174     boolean hasArgumentSpecificSupports();
 175
 176     /**
 177      * If this support has argument specific supports, the method returns
 178      * support specific for given argument (e.g. type statement support need to
 179      * be specialized based on its argument), otherwise returns null.
 180      *
 181      * @param argument
 182      *            argument of statement
 183      * @return statement support specific for supplied argument or null
 184      */
 185     @Nullable
 186     StatementSupport<?, ?, ?> getSupportSpecificForArgument(String argument);
 187
 188     /**
 189      * Given a raw string representation of an argument, try to use a shared representation
 190      *
 191      * @param rawArgument
 192      *            Argument string
 193      * @return A potentially-shard instance
 194      */
 195     default String internArgument(final String rawArgument) {
 196         return rawArgument;
 197     }
 198
 199     /**
 200      * Returns unknown statement form of a regular yang statement supplied as
 201      * parameter to the method.
 202      *
 203      * @param yangStmtDef
 204      *            statement definition of a regular yang statement
 205      * @return Optional of unknown statement form of a regular yang statement or
 206      *         Optional.empty() if it is not supported by this statement support
 207      */
 208     default Optional<StatementDefinitionContext<?, ?, ?>> getUnknownStatementDefinitionOf(
 209             final StatementDefinitionContext<?, ?, ?> yangStmtDef) {
 210         return Optional.empty();
 211     }
 212
 213     /**
 214      * Returns true if this statement support and all its substatements ignore
 215      * if-feature statements (e.g. yang-data extension defined in
 216      * https://tools.ietf.org/html/rfc8040#section-8). Default implementation
 217      * returns false.
 218      *
 219      * @return true if this statement support ignores if-feature statements,
 220      *         otherwise false.
 221      */
 222     @Beta
 223     default boolean isIgnoringIfFeatures() {
 224         return false;
 225     }
 226
 227     /**
 228      * Returns true if this statement support and all its substatements ignore
 229      * config statements (e.g. yang-data extension defined in
 230      * https://tools.ietf.org/html/rfc8040#section-8). Default implementation
 231      * returns false.
 232      *
 233      * @return true if this statement support ignores config statements,
 234      *         otherwise false.
 235      */
 236     @Beta
 237     default boolean isIgnoringConfig() {
 238         return false;
 239     }
 240 }