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