yang/yang-parser-impl/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 java.util.Optional;
  12 import javax.annotation.Nullable;
  13 import org.opendaylight.yangtools.yang.model.api.meta.DeclaredStatement;
  14 import org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement;
  15 import org.opendaylight.yangtools.yang.model.api.meta.StatementDefinition;
  16 import org.opendaylight.yangtools.yang.parser.spi.meta.StmtContext.Mutable;
  17 import org.opendaylight.yangtools.yang.parser.spi.source.SourceException;
  18 import org.opendaylight.yangtools.yang.parser.spi.source.StatementSourceReference;
  19 import org.opendaylight.yangtools.yang.parser.stmt.reactor.StatementContextBase;
  20 import org.opendaylight.yangtools.yang.parser.stmt.reactor.StatementDefinitionContext;
  21
  22 /**
  23  *
  24  * Support for processing concrete YANG statement.
  25  *
  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>> extends
  38         StatementDefinition, StatementFactory<A, D, E> {
  39
  40     /**
  41      * Returns public statement definition, which will be present in built
  42      * statements.
  43      *
  44      * Public statement definition may be used to provide different
  45      * implementation of statement definition, which will not retain any build
  46      * specific data or context.
  47      *
  48      * @return public statement definition, which will be present in built
  49      *         statements.
  50      */
  51     StatementDefinition getPublicView();
  52
  53     /**
  54      *
  55      * Parses textual representation of argument in object representation.
  56      *
  57      * @param ctx
  58      *            Context, which may be used to access source-specific
  59      *            namespaces required for parsing.
  60      * @param value
  61      *            String representation of value, as was present in text source.
  62      * @return Parsed value
  63      * @throws SourceException when an inconsistency is detected.
  64      */
  65     A parseArgumentValue(StmtContext<?, ?, ?> ctx, String value);
  66
  67     /**
  68      * Invoked when a statement supported by this instance is added to build context. This allows implementations
  69      * of this interface to start tracking the statement and perform any modifications to the build context hierarchy,
  70      * accessible via {@link StmtContext#getParentContext()}. One such use is populating the parent's namespaces to
  71      * allow it to locate this child statement.
  72      *
  73      * @param stmt
  74      *            Context of added statement. No substatements are available.
  75      */
  76     void onStatementAdded(StmtContext.Mutable<A, D, E> stmt);
  77
  78     /**
  79      * Invoked before a substatement with specified offset, definition,
  80      * reference and argument is created and added to parent statement. This
  81      * allows implementations of this interface perform any modifications to the
  82      * build context hierarchy before a substatement is created. One such use is
  83      * creating an implicit statement.
  84      *
  85      * @param stmt
  86      *            Context of parent statement where a new substatement should be
  87      *            created. No substatements are available.
  88      * @param offset
  89      *            substatement offset
  90      * @param def
  91      *            definition context
  92      * @param ref
  93      *            source reference
  94      * @param argument
  95      *            substatement argument
  96      * @return optional of an implicit substatement
  97      */
  98     Optional<StatementContextBase<?, ?, ?>> beforeSubStatementCreated(final Mutable<?, ?, ?> stmt, final int offset,
  99             final StatementDefinitionContext<?, ?, ?> def, final StatementSourceReference ref, final String argument);
 100
 101     /**
 102      * Invoked when statement is closed during
 103      * {@link ModelProcessingPhase#SOURCE_PRE_LINKAGE} phase, only substatements
 104      * from this and previous phase are available.
 105      *
 106      * Implementation may use method to perform actions on this event or
 107      * register modification action using
 108      * {@link StmtContext.Mutable#newInferenceAction(ModelProcessingPhase)}.
 109      *
 110      * @param stmt
 111      *            Context of added statement.
 112      */
 113     void onPreLinkageDeclared(StmtContext.Mutable<A, D, E> stmt);
 114
 115     /**
 116      * Invoked when statement is closed during
 117      * {@link ModelProcessingPhase#SOURCE_LINKAGE} phase, only substatements
 118      * from this and previous phase are available.
 119      *
 120      * Implementation may use method to perform actions on this event or
 121      * register modification action using
 122      * {@link StmtContext.Mutable#newInferenceAction(ModelProcessingPhase)}.
 123      *
 124      * @param stmt
 125      *            Context of added statement.
 126      * @throws SourceException when an inconsistency is detected.
 127      */
 128     void onLinkageDeclared(StmtContext.Mutable<A, D, E> stmt);
 129
 130     /**
 131      * Invoked when statement is closed during
 132      * {@link ModelProcessingPhase#STATEMENT_DEFINITION} phase, only
 133      * substatements from this phase are available.
 134      *
 135      * Implementation may use method to perform actions on this event or
 136      * register modification action using
 137      * {@link StmtContext.Mutable#newInferenceAction(ModelProcessingPhase)}.
 138      *
 139      * @param stmt
 140      *            Context of added statement. Argument and statement parent is
 141      *            accessible.
 142      * @throws SourceException when an inconsistency is detected.
 143      */
 144     void onStatementDefinitionDeclared(StmtContext.Mutable<A, D, E> stmt);
 145
 146     /**
 147      * Invoked when statement is closed during
 148      * {@link ModelProcessingPhase#FULL_DECLARATION} phase.
 149      *
 150      * Invoked when statement is closed during
 151      * {@link ModelProcessingPhase#FULL_DECLARATION} phase, only substatements
 152      * from this phase are available.
 153      *
 154      * Implementation may use method to perform actions on this event or
 155      * register modification action using
 156      * {@link StmtContext.Mutable#newInferenceAction(ModelProcessingPhase)}.
 157      *
 158      *
 159      * @param stmt
 160      *            Context of added statement. Argument and statement parent is
 161      *            accessible.
 162      * @throws SourceException when an inconsistency is detected.
 163      */
 164     void onFullDefinitionDeclared(StmtContext.Mutable<A, D, E> stmt);
 165
 166     /**
 167      * Returns true if this support has argument specific supports.
 168      */
 169     boolean hasArgumentSpecificSupports();
 170
 171     /**
 172      * If this support has argument specific supports, the method returns
 173      * support specific for given argument (e.g. type statement support need to
 174      * be specialized based on its argument), otherwise returns null.
 175      *
 176      * @param argument
 177      *            argument of statement
 178      * @return statement support specific for supplied argument or null
 179      */
 180     @Nullable
 181     StatementSupport<?, ?, ?> getSupportSpecificForArgument(String argument);
 182 }