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