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