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