yang/yang-parser-spi/src/main/java/org/opendaylight/yangtools/yang/parser/spi/source/StatementWriter.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.source;
   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.NonNullByDefault;
  14 import org.eclipse.jdt.annotation.Nullable;
  15 import org.opendaylight.yangtools.yang.common.QName;
  16 import org.opendaylight.yangtools.yang.model.api.meta.StatementDefinition;
  17 import org.opendaylight.yangtools.yang.parser.spi.meta.ModelProcessingPhase;
  18
  19 public interface StatementWriter {
  20     /**
  21      * Resumed statement state.
  22      *
  23      * @author Robert Varga
  24      */
  25     @Beta
  26     @NonNullByDefault
  27     interface ResumedStatement {
  28         /**
  29          * Return statement definition.
  30          *
  31          * @return statement definition.
  32          */
  33         StatementDefinition getDefinition();
  34
  35         /**
  36          * Return statement source reference.
  37          *
  38          * @return statement source reference.
  39          */
  40         StatementSourceReference getSourceReference();
  41
  42         /**
  43          * Check if the statement has been fully defined. This implies that all its children have been fully defined.
  44          *
  45          * @return True if the statement has been fully defined.
  46          */
  47         boolean isFullyDefined();
  48     }
  49
  50     /**
  51      * Attempt to resume a child statement. If the statement has been previously defined, a {@link ResumedStatement}
  52      * instance is returned.
  53      *
  54      * <p>
  55      * If an empty optional is returned, the caller is expected to follow-up with
  56      * {@link #startStatement(int, QName, String, StatementSourceReference)} to define the statement.
  57      *
  58      * <p>
  59      * If the returned resumed statement indicates {@link ResumedStatement#isFullyDefined()}, the caller should take
  60      * no further action with this or any of the child statements. Otherwise this call is equivalent of issuing
  61      * {@link #startStatement(int, QName, String, StatementSourceReference)} and the caller is expected to process
  62      * any child statements. The caller should call {@link #storeStatement(int, boolean)} before finishing processing
  63      * with {@link #endStatement(StatementSourceReference)}.
  64      *
  65      * @param childId Child
  66      * @return A resumed statement or empty if the statement has not previously been defined.
  67      */
  68     @Beta
  69     default Optional<? extends ResumedStatement> resumeStatement(final int childId) {
  70         return Optional.empty();
  71     }
  72
  73     /**
  74      * Store a defined statement, hinting at the number of children it is expected to have and indicating whether
  75      * it has been fully defined. This method should be called before {@link #endStatement(StatementSourceReference)}
  76      * when the caller is taking advantage of {@link #resumeStatement(int)}.
  77      *
  78      * @param expectedChildren Number of expected children, cannot be negative
  79      * @param fullyDefined True if the statement and all its descendants have been defined.
  80      */
  81     @Beta
  82     default void storeStatement(final int expectedChildren, final boolean fullyDefined) {
  83         // No-op
  84     }
  85
  86     /**
  87      * Starts statement with supplied name and location in source.
  88      *
  89      * <p>
  90      * Each started statement must also be closed by
  91      * {@link #endStatement(StatementSourceReference)} in order for stream to be
  92      * correct.
  93      *
  94      * <p>
  95      * If statement has substatements, in order to start substatement, call to
  96      * {@link #startStatement(int, QName, String, StatementSourceReference)} needs to be done for substatement.
  97      *
  98      * @param childId Child identifier, unique among siblings
  99      * @param name Fully qualified name of statement.
 100      * @param argument String representation of value as appeared in source, null if not present
 101      * @param ref Identifier of location in source, which will be used for reporting in case of statement processing
 102      *            error.
 103      * @throws SourceException if statement is not valid according to current context.
 104      */
 105     void startStatement(int childId, @NonNull QName name, @Nullable String argument,
 106             @NonNull StatementSourceReference ref);
 107
 108     /**
 109      * Ends current opened statement.
 110      *
 111      * @param ref Identifier of location in source, which will be used for reporting in case of statement processing
 112      *            error.
 113      * @throws SourceException if closed statement is not valid in current context, or there is no such statement
 114      */
 115     void endStatement(@NonNull StatementSourceReference ref);
 116
 117     /**
 118      * Return current model processing phase.
 119      *
 120      * @return current processing phase
 121      */
 122     @NonNull ModelProcessingPhase getPhase();
 123 }