2 * Copyright (c) 2015 Cisco Systems, Inc. and others. All rights reserved.
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
8 package org.opendaylight.yangtools.yang.parser.spi.source;
10 import org.opendaylight.yangtools.yang.common.YangVersion;
13 * Statement stream source, which is used for inference of effective model.
16 * Statement stream source is required to emit its statements using supplied
17 * {@link StatementWriter}.
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.
26 * Steps (in order of invocation) are:
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).
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
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
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>
52 public interface StatementStreamSource {
55 * Emits only pre-linkage-related statements to supplied {@code writer}.
58 * {@link StatementWriter} which should be used to emit
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.
68 void writePreLinkage(StatementWriter writer, QNameToStatementDefinition stmtDef);
71 * Emits only linkage-related statements to supplied {@code writer}.
74 * {@link StatementWriter} which should be used to emit
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.
86 void writeLinkage(StatementWriter writer, QNameToStatementDefinition stmtDef, PrefixToModule preLinkagePrefixes);
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.
93 * {@link StatementWriter} which should be used to emit
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
103 * @throws SourceException
104 * If source was is not valid, or provided statement writer
105 * failed to write statements.
107 default void writeLinkage(final StatementWriter writer, final QNameToStatementDefinition stmtDef,
108 final PrefixToModule preLinkagePrefixes, final YangVersion yangVersion) {
109 writeLinkage(writer, stmtDef, preLinkagePrefixes);
113 * Emits only linkage and language extension statements to supplied {@code writer}.
116 * {@link StatementWriter} which should be used to emit statements.
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.
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.
127 void writeLinkageAndStatementDefinitions(StatementWriter writer, QNameToStatementDefinition stmtDef,
128 PrefixToModule prefixes);
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.
136 * {@link StatementWriter} which should be used to emit
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.
143 * Map of source-specific prefixes to namespaces
147 * @throws SourceException
148 * If source was is not valid, or provided statement writer
149 * failed to write statements.
151 default void writeLinkageAndStatementDefinitions(final StatementWriter writer,
152 final QNameToStatementDefinition stmtDef, final PrefixToModule prefixes, final YangVersion yangVersion) {
153 writeLinkageAndStatementDefinitions(writer, stmtDef, prefixes);
157 * Emits every statements present in this statement source to supplied {@code writer}.
160 * {@link StatementWriter} which should be used to emit
163 * Map of available statement definitions.
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.
170 void writeFull(StatementWriter writer,QNameToStatementDefinition stmtDef, PrefixToModule prefixes);
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.
178 * {@link StatementWriter} which should be used to emit
181 * Map of available statement definitions.
183 * Map of source-specific prefixes to namespaces
186 * @throws SourceException
187 * If source was is not valid, or provided statement writer
188 * failed to write statements.
190 default void writeFull(final StatementWriter writer, final QNameToStatementDefinition stmtDef,
191 final PrefixToModule prefixes, final YangVersion yangVersion) {
192 writeFull(writer, stmtDef, prefixes);