yang/yang-parser-impl/src/main/java/org/opendaylight/yangtools/yang/parser/spi/source/StatementStreamSource.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 /**
  11  *
  12  * Statement stream source, which is used for inference of effective model.
  13  *
  14  * <p>
  15  * Statement stream source is required to emit its statements using supplied
  16  * {@link StatementWriter}.
  17  * </p>
  18  * <p>
  19  * Since YANG allows language extensions defined in sources (which defines how
  20  * source is serialized), instances of extensions present anywhere and forward
  21  * references, each source needs to be processed in three steps, where each step
  22  * uses different set of supported statements.
  23  * <p>
  24  * Steps (in order of invocation) are:
  25  *
  26  * <ol>
  27  * <li>{@link #writeLinkage(StatementWriter, QNameToStatementDefinition)} -
  28  * Source MUST emit only statements related in linkage, which are present in
  29  * supplied statement definition map. This step is used to build cross-source
  30  * linkage and visibility relationship, and to determine XMl namespaces and
  31  * prefixes.</li>
  32  * <li>
  33  * {@link #writeLinkageAndStatementDefinitions(StatementWriter, QNameToStatementDefinition, PrefixToModule)}
  34  * - Source MUST emit only statements related to linkage and language extensions
  35  * definitions, which are present in supplied statement definition map. This
  36  * step is used to build statement definitions in order to fully processed
  37  * source.</li>
  38  * <li>
  39  * {@link #writeFull(StatementWriter, QNameToStatementDefinition, PrefixToModule)}
  40  * - Source MUST emit all statements present in source. This step is used to
  41  * build full declared statement model of source.</li>
  42  * </ol>
  43  *
  44  */
  45 public interface StatementStreamSource {
  46
  47     /**
  48      *
  49      * Emits only linkage-related statements to supplied {@code writer}.
  50      *
  51      * @param writer
  52      *            {@link StatementWriter} which should be used to emit
  53      *            statements.
  54      * @param stmtDef
  55      *            Map of available statement definitions. Only these statements
  56      *            may be written to statement writer, source MUST ignore and MUST NOT
  57      *            emit any other statements.
  58      *
  59      * @throws SourceException
  60      *             If source was is not valid, or provided statement writer
  61      *             failed to write statements.
  62      */
  63     void writeLinkage(StatementWriter writer, QNameToStatementDefinition stmtDef) throws SourceException;
  64
  65     /**
  66      *
  67      * Emits only linkage and language extension statements to supplied
  68      * {@code writer}.
  69      *
  70      * @param writer
  71      *            {@link StatementWriter} which should be used to emit
  72      *            statements.
  73      * @param stmtDef
  74      *            Map of available statement definitions. Only these statements
  75      *            may be written to statement writer, source MUST ignore and MUST NOT
  76      *            emit any other statements.
  77      * @param prefixes
  78      *            Map of source-specific prefixes to namespaces
  79      *
  80      * @throws SourceException
  81      *             If source was is not valid, or provided statement writer
  82      *             failed to write statements.
  83      */
  84     void writeLinkageAndStatementDefinitions(StatementWriter writer, QNameToStatementDefinition stmtDef, PrefixToModule prefixes) throws SourceException;
  85
  86     /**
  87      *
  88      * Emits every statements present in this statement source to supplied
  89      * {@code writer}.
  90      *
  91      * @param writer
  92      *            {@link StatementWriter} which should be used to emit
  93      *            statements.
  94      * @param stmtDef
  95      *            Map of available statement definitions.
  96      * @param prefixes
  97      *            Map of source-specific prefixes to namespaces
  98      * @throws SourceException
  99      *             If source was is not valid, or provided statement writer
 100      *             failed to write statements.
 101      */
 102     void writeFull(StatementWriter writer,QNameToStatementDefinition stmtDef, PrefixToModule prefixes) throws SourceException;
 103 }