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