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 // FIXME: 3.0.0: do not extends ImplicitParentAwareStatementSupport
  36 public interface StatementSupport<A, D extends DeclaredStatement<A>, E extends EffectiveStatement<A, D>>
  37         extends StatementDefinition, StatementFactory<A, D, E>, ImplicitParentAwareStatementSupport {
  38
  39     /**
  40      * Returns public statement definition, which will be present in built statements.
  41      *
  42      * <p>
  43      * Public statement definition may be used to provide different implementation of statement definition,
  44      * which will not retain any build 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     // FIXME: 3.0.0: remove this default method
  91     @Override
  92     default Optional<StatementSupport<?, ?, ?>> getImplicitParentFor(final StatementDefinition stmtDef) {
  93         return Optional.empty();
  94     }
  95
  96     /**
  97      * Invoked when statement is closed during {@link ModelProcessingPhase#SOURCE_PRE_LINKAGE} phase, only substatements
  98      * from this and previous phase are available.
  99      *
 100      * <p>
 101      * Implementation may use method to perform actions on this event or register modification action using
 102      * {@link StmtContext.Mutable#newInferenceAction(ModelProcessingPhase)}.
 103      *
 104      * @param stmt
 105      *            Context of added statement.
 106      */
 107     void onPreLinkageDeclared(StmtContext.Mutable<A, D, E> stmt);
 108
 109     /**
 110      * Invoked when statement is closed during {@link ModelProcessingPhase#SOURCE_LINKAGE} phase, only substatements
 111      * from this and previous phase are available.
 112      *
 113      * <p>
 114      * Implementation may use method to perform actions on this event or register modification action using
 115      * {@link StmtContext.Mutable#newInferenceAction(ModelProcessingPhase)}.
 116      *
 117      * @param stmt
 118      *            Context of added statement.
 119      * @throws SourceException
 120      *             when an inconsistency is detected.
 121      */
 122     void onLinkageDeclared(StmtContext.Mutable<A, D, E> stmt);
 123
 124     /**
 125      * Invoked when statement is closed during {@link ModelProcessingPhase#STATEMENT_DEFINITION} phase,
 126      * only substatements from this phase are available.
 127      *
 128      * <p>
 129      * Implementation may use method to perform actions on this event or register modification action using
 130      * {@link StmtContext.Mutable#newInferenceAction(ModelProcessingPhase)}.
 131      *
 132      * @param stmt
 133      *            Context of added statement. Argument and statement parent is
 134      *            accessible.
 135      * @throws SourceException
 136      *             when an inconsistency is detected.
 137      */
 138     void onStatementDefinitionDeclared(StmtContext.Mutable<A, D, E> stmt);
 139
 140     /**
 141      * Invoked when statement is closed during {@link ModelProcessingPhase#FULL_DECLARATION} phase,
 142      * only substatements from this phase are available.
 143      *
 144      * <p>
 145      * Implementation may use method to perform actions on this event or register modification action using
 146      * {@link StmtContext.Mutable#newInferenceAction(ModelProcessingPhase)}.
 147      *
 148      * @param stmt
 149      *            Context of added statement. Argument and statement parent is
 150      *            accessible.
 151      * @throws SourceException
 152      *             when an inconsistency is detected.
 153      */
 154     void onFullDefinitionDeclared(StmtContext.Mutable<A, D, E> stmt);
 155
 156     /**
 157      * Returns true if this support has argument specific supports.
 158      */
 159     boolean hasArgumentSpecificSupports();
 160
 161     /**
 162      * If this support has argument specific supports, the method returns support specific for given argument
 163      * (e.g. type statement support need to be specialized based on its argument), otherwise returns null.
 164      *
 165      * @param argument
 166      *            argument of statement
 167      * @return statement support specific for supplied argument or null
 168      */
 169     @Nullable
 170     StatementSupport<?, ?, ?> getSupportSpecificForArgument(String argument);
 171
 172     /**
 173      * Given a raw string representation of an argument, try to use a shared representation.
 174      *
 175      * @param rawArgument
 176      *            Argument string
 177      * @return A potentially-shard instance
 178      */
 179     default String internArgument(final String rawArgument) {
 180         return rawArgument;
 181     }
 182
 183     /**
 184      * Returns unknown statement form of a regular YANG statement supplied as a parameter to the method.
 185      *
 186      * @param yangStmtDef
 187      *            statement definition of a regular yang statement
 188      * @return Optional of unknown statement form of a regular yang statement or
 189      *         Optional.empty() if it is not supported by this statement support
 190      */
 191     default Optional<StatementSupport<?, ?, ?>> getUnknownStatementDefinitionOf(final StatementDefinition yangStmtDef) {
 192         return Optional.empty();
 193     }
 194
 195     /**
 196      * Returns true if this statement support and all its substatements ignore if-feature statements (e.g. yang-data
 197      * extension defined in <a href="https://tools.ietf.org/html/rfc8040#section-8">RFC 8040</a>). Default
 198      * implementation returns false.
 199      *
 200      * @return true if this statement support ignores if-feature statements,
 201      *         otherwise false.
 202      */
 203     @Beta
 204     default boolean isIgnoringIfFeatures() {
 205         return false;
 206     }
 207
 208     /**
 209      * Returns true if this statement support and all its substatements ignore config statements (e.g. yang-data
 210      * extension defined in <a href="https://tools.ietf.org/html/rfc8040#section-8">RFC 8040</a>). Default
 211      * implementation returns false.
 212      *
 213      * @return true if this statement support ignores config statements,
 214      *         otherwise false.
 215      */
 216     @Beta
 217     default boolean isIgnoringConfig() {
 218         return false;
 219     }
 220 }