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  *
  13  * Statement stream source, which is used for inference of effective model.
  14  *
  15  * <p>
  16  * Statement stream source is required to emit its statements using supplied
  17  * {@link StatementWriter}.
  18  * </p>
  19  * <p>
  20  * Since YANG allows language extensions defined in sources (which defines how
  21  * source is serialized), instances of extensions present anywhere and forward
  22  * references, each source needs to be processed in three steps, where each step
  23  * uses different set of supported statements.
  24  * <p>
  25  * Steps (in order of invocation) are:
  26  *
  27  * <ol>
  28  * <li>{@link #writePreLinkage(StatementWriter, QNameToStatementDefinition)} -
  29  * Source MUST emit only statements related in pre-linkage, which are present in
  30  * supplied statement definition map. This step is used as preparatory cross-source
  31  * relationship resolution phase which collects available module names and namespaces.
  32  * It is necessary in order to correct resolution of unknown statements used by linkage
  33  * phase (e.g. semantic version of yang modules).
  34  * </li>
  35  * <li>{@link #writeLinkage(StatementWriter, QNameToStatementDefinition, PrefixToModule)} -
  36  * Source MUST emit only statements related in linkage, which are present in
  37  * supplied statement definition map. This step is used to build cross-source
  38  * linkage and visibility relationship, and to determine XMl namespaces and
  39  * prefixes.</li>
  40  * <li>
  41  * {@link #writeLinkageAndStatementDefinitions(StatementWriter, QNameToStatementDefinition, PrefixToModule)}
  42  * - Source MUST emit only statements related to linkage and language extensions
  43  * definitions, which are present in supplied statement definition map. This
  44  * step is used to build statement definitions in order to fully processed
  45  * source.</li>
  46  * <li>
  47  * {@link #writeFull(StatementWriter, QNameToStatementDefinition, PrefixToModule)}
  48  * - Source MUST emit all statements present in source. This step is used to
  49  * build full declared statement model of source.</li>
  50  * </ol>
  51  *
  52  */
  53 public interface StatementStreamSource {
  54
  55     /**
  56     *
  57     * Emits only pre-linkage-related statements to supplied {@code writer}.
  58     *
  59     * @param writer
  60     *            {@link StatementWriter} which should be used to emit
  61     *            statements.
  62     * @param stmtDef
  63     *            Map of available statement definitions. Only these statements
  64     *            may be written to statement writer, source MUST ignore and MUST NOT
  65     *            emit any other statements.
  66     *
  67     * @throws SourceException
  68     *             If source was is not valid, or provided statement writer
  69     *             failed to write statements.
  70     */
  71     void writePreLinkage(StatementWriter writer, QNameToStatementDefinition stmtDef) throws SourceException;
  72
  73     /**
  74      *
  75      * Emits only linkage-related statements to supplied {@code writer}.
  76      *
  77      * @param writer
  78      *            {@link StatementWriter} which should be used to emit
  79      *            statements.
  80      * @param stmtDef
  81      *            Map of available statement definitions. Only these statements
  82      *            may be written to statement writer, source MUST ignore and MUST NOT
  83      *            emit any other statements.
  84      * @param preLinkagePrefixes
  85      *            Pre-linkage map of source-specific prefixes to namespaces
  86      *
  87      * @throws SourceException
  88      *             If source was is not valid, or provided statement writer
  89      *             failed to write statements.
  90      */
  91     void writeLinkage(StatementWriter writer, QNameToStatementDefinition stmtDef, PrefixToModule preLinkagePrefixes) throws SourceException;
  92
  93     /**
  94      *
  95      * Emits only linkage and language extension statements to supplied
  96      * {@code writer}.
  97      *
  98      * @param writer
  99      *            {@link StatementWriter} which should be used to emit
 100      *            statements.
 101      * @param stmtDef
 102      *            Map of available statement definitions. Only these statements
 103      *            may be written to statement writer, source MUST ignore and MUST NOT
 104      *            emit any other statements.
 105      * @param prefixes
 106      *            Map of source-specific prefixes to namespaces
 107      *
 108      * @throws SourceException
 109      *             If source was is not valid, or provided statement writer
 110      *             failed to write statements.
 111      */
 112     void writeLinkageAndStatementDefinitions(StatementWriter writer, QNameToStatementDefinition stmtDef, PrefixToModule prefixes) throws SourceException;
 113
 114     /**
 115      *
 116      * Emits every statements present in this statement source to supplied
 117      * {@code writer}.
 118      *
 119      * @param writer
 120      *            {@link StatementWriter} which should be used to emit
 121      *            statements.
 122      * @param stmtDef
 123      *            Map of available statement definitions.
 124      * @param prefixes
 125      *            Map of source-specific prefixes to namespaces
 126      * @throws SourceException
 127      *             If source was is not valid, or provided statement writer
 128      *             failed to write statements.
 129      */
 130     void writeFull(StatementWriter writer,QNameToStatementDefinition stmtDef, PrefixToModule prefixes) throws SourceException;
 131 }