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