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