yang/yang-parser-spi/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 import org.opendaylight.yangtools.yang.common.YangVersion;
  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  *
  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  *
  25  * <p>
  26  * Steps (in order of invocation) are:
  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 public interface StatementStreamSource {
  53
  54     /**
  55      * Emits only pre-linkage-related statements to supplied {@code writer}.
  56      *
  57      * @param writer
  58      *            {@link StatementWriter} which should be used to emit
  59      *            statements.
  60      * @param stmtDef
  61      *            Map of available statement definitions. Only these statements
  62      *            may be written to statement writer, source MUST ignore and MUST NOT
  63      *            emit any other statements.
  64      * @throws SourceException
  65      *             If source was is not valid, or provided statement writer
  66      *             failed to write statements.
  67      */
  68     void writePreLinkage(StatementWriter writer, QNameToStatementDefinition stmtDef);
  69
  70     /**
  71      * Emits only linkage-related statements to supplied {@code writer}.
  72      *
  73      * @param writer
  74      *            {@link StatementWriter} which should be used to emit
  75      *            statements.
  76      * @param stmtDef
  77      *            Map of available statement definitions. Only these statements
  78      *            may be written to statement writer, source MUST ignore and MUST NOT
  79      *            emit any other statements.
  80      * @param preLinkagePrefixes
  81      *            Pre-linkage map of source-specific prefixes to namespaces
  82      * @throws SourceException
  83      *             If source was is not valid, or provided statement writer
  84      *             failed to write statements.
  85      */
  86     void writeLinkage(StatementWriter writer, QNameToStatementDefinition stmtDef, PrefixToModule preLinkagePrefixes);
  87
  88     /**
  89      * Emits only linkage-related statements to supplied {@code writer} based on specified YANG version.
  90      * Default implementation does not make any differences between versions.
  91      *
  92      * @param writer
  93      *            {@link StatementWriter} which should be used to emit
  94      *            statements.
  95      * @param stmtDef
  96      *            Map of available statement definitions. Only these statements
  97      *            may be written to statement writer, source MUST ignore and
  98      *            MUST NOT emit any other statements.
  99      * @param preLinkagePrefixes
 100      *            Pre-linkage map of source-specific prefixes to namespaces
 101      * @param yangVersion
 102      *            yang version.
 103      * @throws SourceException
 104      *             If source was is not valid, or provided statement writer
 105      *             failed to write statements.
 106      */
 107     default void writeLinkage(final StatementWriter writer, final QNameToStatementDefinition stmtDef,
 108             final PrefixToModule preLinkagePrefixes, final YangVersion yangVersion) {
 109         writeLinkage(writer, stmtDef, preLinkagePrefixes);
 110     }
 111
 112     /**
 113      * Emits only linkage and language extension statements to supplied {@code writer}.
 114      *
 115      * @param writer
 116      *            {@link StatementWriter} which should be used to emit statements.
 117      * @param stmtDef
 118      *            Map of available statement definitions. Only these statements
 119      *            may be written to statement writer, source MUST ignore and MUST NOT
 120      *            emit any other statements.
 121      * @param prefixes
 122      *            Map of source-specific prefixes to namespaces
 123      * @throws SourceException
 124      *             If source was is not valid, or provided statement writer
 125      *             failed to write statements.
 126      */
 127     void writeLinkageAndStatementDefinitions(StatementWriter writer, QNameToStatementDefinition stmtDef,
 128             PrefixToModule prefixes);
 129
 130     /**
 131      * Emits only linkage and language extension statements to supplied
 132      * {@code writer} based on specified YANG version. Default implementation
 133      * does not make any differences between versions.
 134      *
 135      * @param writer
 136      *            {@link StatementWriter} which should be used to emit
 137      *            statements.
 138      * @param stmtDef
 139      *            Map of available statement definitions. Only these statements
 140      *            may be written to statement writer, source MUST ignore and
 141      *            MUST NOT emit any other statements.
 142      * @param prefixes
 143      *            Map of source-specific prefixes to namespaces
 144      * @param yangVersion
 145      *            YANG version.
 146      *
 147      * @throws SourceException
 148      *             If source was is not valid, or provided statement writer
 149      *             failed to write statements.
 150      */
 151     default void writeLinkageAndStatementDefinitions(final StatementWriter writer,
 152             final QNameToStatementDefinition stmtDef, final PrefixToModule prefixes, final YangVersion yangVersion) {
 153         writeLinkageAndStatementDefinitions(writer, stmtDef, prefixes);
 154     }
 155
 156     /**
 157      * Emits every statements present in this statement source to supplied {@code writer}.
 158      *
 159      * @param writer
 160      *            {@link StatementWriter} which should be used to emit
 161      *            statements.
 162      * @param stmtDef
 163      *            Map of available statement definitions.
 164      * @param prefixes
 165      *            Map of source-specific prefixes to namespaces
 166      * @throws SourceException
 167      *             If source was is not valid, or provided statement writer
 168      *             failed to write statements.
 169      */
 170     void writeFull(StatementWriter writer,QNameToStatementDefinition stmtDef, PrefixToModule prefixes);
 171
 172     /**
 173      * Emits every statements present in this statement source to supplied
 174      * {@code writer} based on specified yang version. Default implementation
 175      * does not make any differences between versions.
 176      *
 177      * @param writer
 178      *            {@link StatementWriter} which should be used to emit
 179      *            statements.
 180      * @param stmtDef
 181      *            Map of available statement definitions.
 182      * @param prefixes
 183      *            Map of source-specific prefixes to namespaces
 184      * @param yangVersion
 185      *            yang version.
 186      * @throws SourceException
 187      *             If source was is not valid, or provided statement writer
 188      *             failed to write statements.
 189      */
 190     default void writeFull(final StatementWriter writer, final QNameToStatementDefinition stmtDef,
 191             final PrefixToModule prefixes, final YangVersion yangVersion) {
 192         writeFull(writer, stmtDef, prefixes);
 193     }
 194 }