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 {@link StatementWriter}.
  19  *
  20  * <p>
  21  * Since YANG allows language extensions defined in sources (which defines how source is serialized), instances of
  22  * extensions present anywhere and forward 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, YangVersion)} -
  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  * YangVersion)}
  43  * - Source MUST emit only statements related to linkage and language extensions
  44  * definitions, which are present in supplied statement definition map. This
  45  * step is used to build statement definitions in order to fully processed
  46  * source.</li>
  47  * <li>
  48  * {@link #writeFull(StatementWriter, QNameToStatementDefinition, PrefixToModule, YangVersion)}
  49  * - Source MUST emit all statements present in source. This step is used to
  50  * build full declared statement model of source.</li>
  51  * </ol>
  52  */
  53 // FIXME: 7.0.0: this is a push parser, essentially traversing the same tree multiple times. Perhaps we should create
  54 //               a visitor/filter or perform some explicit argument binding?
  55 public interface StatementStreamSource extends Identifiable<SourceIdentifier> {
  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} based on specified YANG version.
  74      * Default implementation does not make any differences between versions.
  75      *
  76      * @param writer
  77      *            {@link StatementWriter} which should be used to emit
  78      *            statements.
  79      * @param stmtDef
  80      *            Map of available statement definitions. Only these statements
  81      *            may be written to statement writer, source MUST ignore and
  82      *            MUST NOT emit any other statements.
  83      * @param preLinkagePrefixes
  84      *            Pre-linkage map of source-specific prefixes to namespaces
  85      * @param yangVersion
  86      *            yang version.
  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,
  92             YangVersion yangVersion);
  93
  94     /**
  95      * Emits only linkage and language extension statements to supplied
  96      * {@code writer} based on specified YANG version. Default implementation
  97      * does not make any differences between versions.
  98      *
  99      * @param writer
 100      *            {@link StatementWriter} which should be used to emit
 101      *            statements.
 102      * @param stmtDef
 103      *            Map of available statement definitions. Only these statements
 104      *            may be written to statement writer, source MUST ignore and
 105      *            MUST NOT emit any other statements.
 106      * @param prefixes
 107      *            Map of source-specific prefixes to namespaces
 108      * @param yangVersion
 109      *            YANG version.
 110      *
 111      * @throws SourceException
 112      *             If source was is not valid, or provided statement writer
 113      *             failed to write statements.
 114      */
 115     void writeLinkageAndStatementDefinitions(StatementWriter writer, QNameToStatementDefinition stmtDef,
 116             PrefixToModule prefixes, YangVersion yangVersion);
 117
 118     /**
 119      * Emits every statements present in this statement source to supplied
 120      * {@code writer} based on specified yang version. Default implementation
 121      * does not make any differences between versions.
 122      *
 123      * @param writer
 124      *            {@link StatementWriter} which should be used to emit
 125      *            statements.
 126      * @param stmtDef
 127      *            Map of available statement definitions.
 128      * @param prefixes
 129      *            Map of source-specific prefixes to namespaces
 130      * @param yangVersion
 131      *            yang version.
 132      * @throws SourceException
 133      *             If source was is not valid, or provided statement writer
 134      *             failed to write statements.
 135      */
 136     void writeFull(StatementWriter writer, QNameToStatementDefinition stmtDef, PrefixToModule prefixes,
 137             YangVersion yangVersion);
 138 }