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 import org.opendaylight.yangtools.yang.common.YangVersion;
  11
  12
  13 /**
  14  *
  15  * Statement stream source, which is used for inference of effective model.
  16  *
  17  * <p>
  18  * Statement stream source is required to emit its statements using supplied
  19  * {@link StatementWriter}.
  20  * </p>
  21  * <p>
  22  * Since YANG allows language extensions defined in sources (which defines how
  23  * source is serialized), instances of extensions present anywhere and forward
  24  * references, each source needs to be processed in three steps, where each step
  25  * uses different set of supported statements.
  26  * <p>
  27  * Steps (in order of invocation) are:
  28  *
  29  * <ol>
  30  * <li>{@link #writePreLinkage(StatementWriter, QNameToStatementDefinition)} -
  31  * Source MUST emit only statements related in pre-linkage, which are present in
  32  * supplied statement definition map. This step is used as preparatory cross-source
  33  * relationship resolution phase which collects available module names and namespaces.
  34  * It is necessary in order to correct resolution of unknown statements used by linkage
  35  * phase (e.g. openconfig version of yang modules).
  36  * </li>
  37  * <li>{@link #writeLinkage(StatementWriter, QNameToStatementDefinition, PrefixToModule)} -
  38  * Source MUST emit only statements related in linkage, which are present in
  39  * supplied statement definition map. This step is used to build cross-source
  40  * linkage and visibility relationship, and to determine XMl namespaces and
  41  * prefixes.</li>
  42  * <li>
  43  * {@link #writeLinkageAndStatementDefinitions(StatementWriter, QNameToStatementDefinition, PrefixToModule)}
  44  * - Source MUST emit only statements related to linkage and language extensions
  45  * definitions, which are present in supplied statement definition map. This
  46  * step is used to build statement definitions in order to fully processed
  47  * source.</li>
  48  * <li>
  49  * {@link #writeFull(StatementWriter, QNameToStatementDefinition, PrefixToModule)}
  50  * - Source MUST emit all statements present in source. This step is used to
  51  * build full declared statement model of source.</li>
  52  * </ol>
  53  *
  54  */
  55 public interface StatementStreamSource {
  56
  57     /**
  58     *
  59     * Emits only pre-linkage-related statements to supplied {@code writer}.
  60     *
  61     * @param writer
  62     *            {@link StatementWriter} which should be used to emit
  63     *            statements.
  64     * @param stmtDef
  65     *            Map of available statement definitions. Only these statements
  66     *            may be written to statement writer, source MUST ignore and MUST NOT
  67     *            emit any other statements.
  68     *
  69     * @throws SourceException
  70     *             If source was is not valid, or provided statement writer
  71     *             failed to write statements.
  72     */
  73     void writePreLinkage(StatementWriter writer, QNameToStatementDefinition stmtDef) throws SourceException;
  74
  75     /**
  76      *
  77      * Emits only linkage-related statements to supplied {@code writer}.
  78      *
  79      * @param writer
  80      *            {@link StatementWriter} which should be used to emit
  81      *            statements.
  82      * @param stmtDef
  83      *            Map of available statement definitions. Only these statements
  84      *            may be written to statement writer, source MUST ignore and MUST NOT
  85      *            emit any other statements.
  86      * @param preLinkagePrefixes
  87      *            Pre-linkage map of source-specific prefixes to namespaces
  88      *
  89      * @throws SourceException
  90      *             If source was is not valid, or provided statement writer
  91      *             failed to write statements.
  92      */
  93     void writeLinkage(StatementWriter writer, QNameToStatementDefinition stmtDef, PrefixToModule preLinkagePrefixes) throws SourceException;
  94
  95     /**
  96      *
  97      * Emits only linkage-related statements to supplied {@code writer} based on
  98      * specified yang version. Default implementation does not make any
  99      * differences between versions.
 100      *
 101      * @param writer
 102      *            {@link StatementWriter} which should be used to emit
 103      *            statements.
 104      * @param stmtDef
 105      *            Map of available statement definitions. Only these statements
 106      *            may be written to statement writer, source MUST ignore and
 107      *            MUST NOT emit any other statements.
 108      * @param preLinkagePrefixes
 109      *            Pre-linkage map of source-specific prefixes to namespaces
 110      * @param yangVersion
 111      *            yang version.
 112      *
 113      * @throws SourceException
 114      *             If source was is not valid, or provided statement writer
 115      *             failed to write statements.
 116      */
 117     default void writeLinkage(final StatementWriter writer, final QNameToStatementDefinition stmtDef,
 118             final PrefixToModule preLinkagePrefixes, final YangVersion yangVersion) {
 119         writeLinkage(writer, stmtDef, preLinkagePrefixes);
 120     }
 121
 122     /**
 123      *
 124      * Emits only linkage and language extension statements to supplied
 125      * {@code writer}.
 126      *
 127      * @param writer
 128      *            {@link StatementWriter} which should be used to emit
 129      *            statements.
 130      * @param stmtDef
 131      *            Map of available statement definitions. Only these statements
 132      *            may be written to statement writer, source MUST ignore and MUST NOT
 133      *            emit any other statements.
 134      * @param prefixes
 135      *            Map of source-specific prefixes to namespaces
 136      *
 137      * @throws SourceException
 138      *             If source was is not valid, or provided statement writer
 139      *             failed to write statements.
 140      */
 141     void writeLinkageAndStatementDefinitions(StatementWriter writer, QNameToStatementDefinition stmtDef, PrefixToModule prefixes) throws SourceException;
 142
 143     /**
 144      *
 145      * Emits only linkage and language extension statements to supplied
 146      * {@code writer} based on specified yang version. Default implementation
 147      * does not make any differences between versions.
 148      *
 149      * @param writer
 150      *            {@link StatementWriter} which should be used to emit
 151      *            statements.
 152      * @param stmtDef
 153      *            Map of available statement definitions. Only these statements
 154      *            may be written to statement writer, source MUST ignore and
 155      *            MUST NOT emit any other statements.
 156      * @param prefixes
 157      *            Map of source-specific prefixes to namespaces
 158      * @param yangVersion
 159      *            yang version.
 160      *
 161      * @throws SourceException
 162      *             If source was is not valid, or provided statement writer
 163      *             failed to write statements.
 164      */
 165     default void writeLinkageAndStatementDefinitions(final StatementWriter writer,
 166             final QNameToStatementDefinition stmtDef, final PrefixToModule prefixes, final YangVersion yangVersion) {
 167         writeLinkageAndStatementDefinitions(writer, stmtDef, prefixes);
 168     }
 169
 170     /**
 171      *
 172      * Emits every statements present in this statement source to supplied
 173      * {@code writer}.
 174      *
 175      * @param writer
 176      *            {@link StatementWriter} which should be used to emit
 177      *            statements.
 178      * @param stmtDef
 179      *            Map of available statement definitions.
 180      * @param prefixes
 181      *            Map of source-specific prefixes to namespaces
 182      * @throws SourceException
 183      *             If source was is not valid, or provided statement writer
 184      *             failed to write statements.
 185      */
 186     void writeFull(StatementWriter writer,QNameToStatementDefinition stmtDef, PrefixToModule prefixes) throws SourceException;
 187
 188     /**
 189      *
 190      * Emits every statements present in this statement source to supplied
 191      * {@code writer} based on specified yang version. Default implementation
 192      * does not make any differences between versions.
 193      *
 194      * @param writer
 195      *            {@link StatementWriter} which should be used to emit
 196      *            statements.
 197      * @param stmtDef
 198      *            Map of available statement definitions.
 199      * @param prefixes
 200      *            Map of source-specific prefixes to namespaces
 201      * @param yangVersion
 202      *            yang version.
 203      * @throws SourceException
 204      *             If source was is not valid, or provided statement writer
 205      *             failed to write statements.
 206      */
 207     default void writeFull(final StatementWriter writer, final QNameToStatementDefinition stmtDef,
 208             final PrefixToModule prefixes, final YangVersion yangVersion) {
 209         writeFull(writer, stmtDef, prefixes);
 210     }
 211 }