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;
15 * Statement stream source, which is used for inference of effective model.
18 * Statement stream source is required to emit its statements using supplied
19 * {@link StatementWriter}.
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.
27 * Steps (in order of invocation) are:
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).
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
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
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>
55 public interface StatementStreamSource {
59 * Emits only pre-linkage-related statements to supplied {@code writer}.
62 * {@link StatementWriter} which should be used to emit
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.
69 * @throws SourceException
70 * If source was is not valid, or provided statement writer
71 * failed to write statements.
73 void writePreLinkage(StatementWriter writer, QNameToStatementDefinition stmtDef) throws SourceException;
77 * Emits only linkage-related statements to supplied {@code writer}.
80 * {@link StatementWriter} which should be used to emit
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
89 * @throws SourceException
90 * If source was is not valid, or provided statement writer
91 * failed to write statements.
93 void writeLinkage(StatementWriter writer, QNameToStatementDefinition stmtDef, PrefixToModule preLinkagePrefixes) throws SourceException;
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.
102 * {@link StatementWriter} which should be used to emit
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
113 * @throws SourceException
114 * If source was is not valid, or provided statement writer
115 * failed to write statements.
117 default void writeLinkage(final StatementWriter writer, final QNameToStatementDefinition stmtDef,
118 final PrefixToModule preLinkagePrefixes, final YangVersion yangVersion) {
119 writeLinkage(writer, stmtDef, preLinkagePrefixes);
124 * Emits only linkage and language extension statements to supplied
128 * {@link StatementWriter} which should be used to emit
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.
135 * Map of source-specific prefixes to namespaces
137 * @throws SourceException
138 * If source was is not valid, or provided statement writer
139 * failed to write statements.
141 void writeLinkageAndStatementDefinitions(StatementWriter writer, QNameToStatementDefinition stmtDef, PrefixToModule prefixes) throws SourceException;
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.
150 * {@link StatementWriter} which should be used to emit
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.
157 * Map of source-specific prefixes to namespaces
161 * @throws SourceException
162 * If source was is not valid, or provided statement writer
163 * failed to write statements.
165 default void writeLinkageAndStatementDefinitions(final StatementWriter writer,
166 final QNameToStatementDefinition stmtDef, final PrefixToModule prefixes, final YangVersion yangVersion) {
167 writeLinkageAndStatementDefinitions(writer, stmtDef, prefixes);
172 * Emits every statements present in this statement source to supplied
176 * {@link StatementWriter} which should be used to emit
179 * Map of available statement definitions.
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.
186 void writeFull(StatementWriter writer,QNameToStatementDefinition stmtDef, PrefixToModule prefixes) throws SourceException;
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.
195 * {@link StatementWriter} which should be used to emit
198 * Map of available statement definitions.
200 * Map of source-specific prefixes to namespaces
203 * @throws SourceException
204 * If source was is not valid, or provided statement writer
205 * failed to write statements.
207 default void writeFull(final StatementWriter writer, final QNameToStatementDefinition stmtDef,
208 final PrefixToModule prefixes, final YangVersion yangVersion) {
209 writeFull(writer, stmtDef, prefixes);