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