parser/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     Optional<? extends ResumedStatement> resumeStatement(int childId);
  69
  70     /**
  71      * Store a defined statement, hinting at the number of children it is expected to have and indicating whether
  72      * it has been fully defined. This method should be called before {@link #endStatement(StatementSourceReference)}
  73      * when the caller is taking advantage of {@link #resumeStatement(int)}.
  74      *
  75      * @param expectedChildren Number of expected children, cannot be negative
  76      * @param fullyDefined True if the statement and all its descendants have been defined.
  77      */
  78     void storeStatement(int expectedChildren, boolean fullyDefined);
  79
  80     /**
  81      * Starts statement with supplied name and location in source.
  82      *
  83      * <p>
  84      * Each started statement must also be closed by
  85      * {@link #endStatement(StatementSourceReference)} in order for stream to be
  86      * correct.
  87      *
  88      * <p>
  89      * If statement has substatements, in order to start substatement, call to
  90      * {@link #startStatement(int, QName, String, StatementSourceReference)} needs to be done for substatement.
  91      *
  92      * @param childId Child identifier, unique among siblings
  93      * @param name Fully qualified name of statement.
  94      * @param argument String representation of value as appeared in source, null if not present
  95      * @param ref Identifier of location in source, which will be used for reporting in case of statement processing
  96      *            error.
  97      * @throws SourceException if statement is not valid according to current context.
  98      */
  99     void startStatement(int childId, @NonNull QName name, @Nullable String argument,
 100             @NonNull StatementSourceReference ref);
 101
 102     /**
 103      * Ends current opened statement.
 104      *
 105      * @param ref Identifier of location in source, which will be used for reporting in case of statement processing
 106      *            error.
 107      * @throws SourceException if closed statement is not valid in current context, or there is no such statement
 108      */
 109     void endStatement(@NonNull StatementSourceReference ref);
 110
 111     /**
 112      * Return current model processing phase.
 113      *
 114      * @return current processing phase
 115      */
 116     @NonNull ModelProcessingPhase getPhase();
 117 }