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