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.meta.StmtContext.Mutable;
  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 introduce support of statement to parser.
  28  * Consider subclassing {@link AbstractStatementSupport} for easier implementation of this interface.
  29  *
  30  * @param <A> Argument type
  31  * @param <D> Declared Statement representation
  32  * @param <E> Effective Statement representation
  33  */
  34 public interface StatementSupport<A, D extends DeclaredStatement<A>, E extends EffectiveStatement<A, D>>
  35         extends StatementDefinition, StatementFactory<A, D, E> {
  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 Context, which may be used to access source-specific namespaces required for parsing.
  61      * @param targetModule Target module, may not be null.
  62      * @return Adapted argument value. The default implementation returns original value stored in context.
  63      */
  64     default A adaptArgumentValue(final StmtContext<A, D, E> ctx, final QNameModule targetModule) {
  65         return ctx.getStatementArgument();
  66     }
  67
  68     /**
  69      * Invoked when a statement supported by this instance is added to build context. This allows implementations
  70      * of this interface to start tracking the statement and perform any modifications to the build context hierarchy,
  71      * accessible via {@link StmtContext#getParentContext()}. One such use is populating the parent's namespaces to
  72      * allow it to locate this child statement.
  73      *
  74      * @param stmt Context of added statement. No substatements are available.
  75      */
  76     void onStatementAdded(StmtContext.Mutable<A, D, E> stmt);
  77
  78     /**
  79      * Invoked when statement is closed during {@link ModelProcessingPhase#SOURCE_PRE_LINKAGE} phase, only substatements
  80      * from this and previous phase are available.
  81      *
  82      * <p>
  83      * Implementation may use method to perform actions on this event or register modification action using
  84      * {@link StmtContext.Mutable#newInferenceAction(ModelProcessingPhase)}.
  85      *
  86      * @param stmt Context of added statement.
  87      */
  88     void onPreLinkageDeclared(StmtContext.Mutable<A, D, E> stmt);
  89
  90     /**
  91      * Invoked when statement is closed during {@link ModelProcessingPhase#SOURCE_LINKAGE} phase, only substatements
  92      * from this and previous phase are available.
  93      *
  94      * <p>
  95      * Implementation may use method to perform actions on this event or register modification action using
  96      * {@link StmtContext.Mutable#newInferenceAction(ModelProcessingPhase)}.
  97      *
  98      * @param stmt Context of added statement.
  99      * @throws SourceException when an inconsistency is detected.
 100      */
 101     void onLinkageDeclared(StmtContext.Mutable<A, D, E> stmt);
 102
 103     /**
 104      * Invoked when statement is closed during {@link ModelProcessingPhase#STATEMENT_DEFINITION} phase,
 105      * only substatements from this phase are available.
 106      *
 107      * <p>
 108      * Implementation may use method to perform actions on this event or register modification action using
 109      * {@link StmtContext.Mutable#newInferenceAction(ModelProcessingPhase)}.
 110      *
 111      * @param stmt Context of added statement. Argument and statement parent is accessible.
 112      * @throws SourceException when an inconsistency is detected.
 113      */
 114     void onStatementDefinitionDeclared(StmtContext.Mutable<A, D, E> stmt);
 115
 116     /**
 117      * Invoked when statement is closed during {@link ModelProcessingPhase#FULL_DECLARATION} phase,
 118      * only substatements from this phase are available.
 119      *
 120      * <p>
 121      * Implementation may use method to perform actions on this event or register modification action using
 122      * {@link StmtContext.Mutable#newInferenceAction(ModelProcessingPhase)}.
 123      *
 124      * @param stmt Context of added statement. Argument and statement parent is accessible.
 125      * @throws SourceException when an inconsistency is detected.
 126      */
 127     void onFullDefinitionDeclared(StmtContext.Mutable<A, D, E> stmt);
 128
 129     /**
 130      * Returns true if this support has argument specific supports.
 131      */
 132     boolean hasArgumentSpecificSupports();
 133
 134     /**
 135      * If this support has argument specific supports, the method returns support specific for given argument
 136      * (e.g. type statement support need to be specialized based on its argument), otherwise returns null.
 137      *
 138      * @param argument argument of statement
 139      * @return statement support specific for supplied argument or null
 140      */
 141     @Nullable StatementSupport<?, ?, ?> getSupportSpecificForArgument(String argument);
 142
 143     /**
 144      * Create an optional copy of specified statement as a substatement of parent.
 145      *
 146      * <p>
 147      * Note that while it may be tempting to return the same context, this is not safe in general case. It is only safe
 148      * if the entire subtree is unaffected by changes to parent/namespace/history. This includes the semantics of this
 149      * statement (it cannot be a target of any inference effects) as well as any substatements -- an extension statement
 150      * is allowed pretty much anywhere and if its semantics are context-dependent, a simple instance reuse will not
 151      * work.
 152      *
 153      * @param stmt Context of statement to be copied statement.
 154      * @param parent Parent statement context
 155      * @param type Type of copy being performed
 156      * @param targetModule Target module, if present
 157      * @return Empty if the statement should be ignored, or present with an instance that should be copied into parent.
 158      */
 159     @NonNull Optional<? extends Mutable<?, ?, ?>> copyAsChildOf(Mutable<?, ?, ?> stmt, Mutable<?, ?, ?> parent,
 160             CopyType type, @Nullable QNameModule targetModule);
 161
 162     /**
 163      * Given a raw string representation of an argument, try to use a shared representation.
 164      *
 165      * @param rawArgument 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 statement definition of a regular YANG statement
 176      * @return Optional of unknown statement form of a regular YANG statement or empty() if it is not supported by this
 177      *         statement support
 178      */
 179     default Optional<StatementSupport<?, ?, ?>> getUnknownStatementDefinitionOf(final StatementDefinition yangStmtDef) {
 180         return Optional.empty();
 181     }
 182
 183     /**
 184      * Returns true if this statement support and all its substatements ignore if-feature statements (e.g. yang-data
 185      * extension defined in <a href="https://tools.ietf.org/html/rfc8040#section-8">RFC 8040</a>). Default
 186      * implementation returns false.
 187      *
 188      * @return true if this statement support ignores if-feature statements,
 189      *         otherwise false.
 190      */
 191     @Beta
 192     default boolean isIgnoringIfFeatures() {
 193         return false;
 194     }
 195
 196     /**
 197      * Returns true if this statement support and all its substatements ignore config 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 config statements,
 202      *         otherwise false.
 203      */
 204     @Beta
 205     default boolean isIgnoringConfig() {
 206         return false;
 207     }
 208
 209     @Override
 210     default QName getStatementName() {
 211         return getPublicView().getStatementName();
 212     }
 213
 214     @Override
 215     default @NonNull Optional<ArgumentDefinition> getArgumentDefinition() {
 216         return getPublicView().getArgumentDefinition();
 217     }
 218
 219     @Override
 220     default Class<? extends DeclaredStatement<?>> getDeclaredRepresentationClass() {
 221         return getPublicView().getDeclaredRepresentationClass();
 222     }
 223
 224     @Override
 225     default Class<? extends EffectiveStatement<?,?>> getEffectiveRepresentationClass() {
 226         return getPublicView().getEffectiveRepresentationClass();
 227     }
 228 }