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.concepts.Identifiable;
11 import org.opendaylight.yangtools.yang.common.YangVersion;
12 import org.opendaylight.yangtools.yang.model.repo.api.SourceIdentifier;
15 * Statement stream source, which is used for inference of effective model.
18 * Statement stream source is required to emit its statements using supplied {@link StatementWriter}.
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.
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, 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
41 * {@link #writeLinkageAndStatementDefinitions(StatementWriter, QNameToStatementDefinition, PrefixToModule,
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
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>
53 // FIXME: 6.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> {
57 * Emits only pre-linkage-related statements to supplied {@code writer}.
60 * {@link StatementWriter} which should be used to emit
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.
70 void writePreLinkage(StatementWriter writer, QNameToStatementDefinition stmtDef);
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.
77 * {@link StatementWriter} which should be used to emit
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
87 * @throws SourceException
88 * If source was is not valid, or provided statement writer
89 * failed to write statements.
91 void writeLinkage(StatementWriter writer, QNameToStatementDefinition stmtDef, PrefixToModule preLinkagePrefixes,
92 YangVersion yangVersion);
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.
100 * {@link StatementWriter} which should be used to emit
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.
107 * Map of source-specific prefixes to namespaces
111 * @throws SourceException
112 * If source was is not valid, or provided statement writer
113 * failed to write statements.
115 void writeLinkageAndStatementDefinitions(StatementWriter writer, QNameToStatementDefinition stmtDef,
116 PrefixToModule prefixes, YangVersion yangVersion);
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.
124 * {@link StatementWriter} which should be used to emit
127 * Map of available statement definitions.
129 * Map of source-specific prefixes to namespaces
132 * @throws SourceException
133 * If source was is not valid, or provided statement writer
134 * failed to write statements.
136 void writeFull(StatementWriter writer, QNameToStatementDefinition stmtDef, PrefixToModule prefixes,
137 YangVersion yangVersion);