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.model.api.meta.DeclaredStatement;
  15 import org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement;
  16 import org.opendaylight.yangtools.yang.model.api.meta.StatementDefinition;
  17 import org.opendaylight.yangtools.yang.parser.spi.meta.StmtContext.Mutable;
  18 import org.opendaylight.yangtools.yang.parser.spi.source.SourceException;
  19 import org.opendaylight.yangtools.yang.parser.spi.source.StatementSourceReference;
  20 import org.opendaylight.yangtools.yang.parser.stmt.reactor.StatementContextBase;
  21 import org.opendaylight.yangtools.yang.parser.stmt.reactor.StatementDefinitionContext;
  22
  23 /**
  24  * Support for processing concrete YANG statement.
  25  *
  26  * <p>
  27  * This interface is intended to be implemented by developers, which want to
  28  * introduce support of statement to parser. Consider subclassing
  29  * {@link AbstractStatementSupport} for easier implementation of this interface.
  30  *
  31  * @param <A>
  32  *            Argument type
  33  * @param <D>
  34  *            Declared Statement representation
  35  * @param <E>
  36  *            Effective Statement representation
  37  */
  38 public interface StatementSupport<A, D extends DeclaredStatement<A>, E extends EffectiveStatement<A, D>>
  39         extends StatementDefinition, StatementFactory<A, D, E> {
  40
  41     /**
  42      * Returns public statement definition, which will be present in built
  43      * statements.
  44      *
  45      * Public statement definition may be used to provide different
  46      * implementation of statement definition, which will not retain any build
  47      * specific data or context.
  48      *
  49      * @return public statement definition, which will be present in built
  50      *         statements.
  51      */
  52     StatementDefinition getPublicView();
  53
  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      * Invoked when a statement supported by this instance is added to build context. This allows implementations
  71      * of this interface to start tracking the statement and perform any modifications to the build context hierarchy,
  72      * accessible via {@link StmtContext#getParentContext()}. One such use is populating the parent's namespaces to
  73      * allow it to locate this child statement.
  74      *
  75      * @param stmt
  76      *            Context of added statement. No substatements are available.
  77      */
  78     void onStatementAdded(StmtContext.Mutable<A, D, E> stmt);
  79
  80     /**
  81      * Invoked before a substatement with specified offset, definition,
  82      * reference and argument is created and added to parent statement. This
  83      * allows implementations of this interface perform any modifications to the
  84      * build context hierarchy before a substatement is created. One such use is
  85      * creating an implicit statement.
  86      *
  87      * @param stmt
  88      *            Context of parent statement where a new substatement should be
  89      *            created. No substatements are available.
  90      * @param offset
  91      *            substatement offset
  92      * @param def
  93      *            definition context
  94      * @param ref
  95      *            source reference
  96      * @param argument
  97      *            substatement argument
  98      * @return optional of an implicit substatement
  99      */
 100     Optional<StatementContextBase<?, ?, ?>> beforeSubStatementCreated(final Mutable<?, ?, ?> stmt, final int offset,
 101             final StatementDefinitionContext<?, ?, ?> def, final StatementSourceReference ref, final String argument);
 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 }