2 * Copyright (c) 2017 Pantheon Technologies, s.r.o. 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.model.parser.api;
10 import com.google.common.annotations.Beta;
11 import com.google.common.collect.SetMultimap;
12 import java.io.IOException;
13 import java.util.Collection;
14 import java.util.List;
17 import javax.annotation.Nonnull;
18 import javax.annotation.concurrent.NotThreadSafe;
19 import org.opendaylight.yangtools.yang.common.QName;
20 import org.opendaylight.yangtools.yang.common.QNameModule;
21 import org.opendaylight.yangtools.yang.model.api.SchemaContext;
22 import org.opendaylight.yangtools.yang.model.api.meta.DeclaredStatement;
23 import org.opendaylight.yangtools.yang.model.api.stmt.ModuleEffectiveStatement;
24 import org.opendaylight.yangtools.yang.model.repo.api.SchemaSourceRepresentation;
27 * Configurable single-use YANG parser. Each instance can be configured to use a different set of models after
28 * which it is built. Models once added cannot be removed.
30 * @author Robert Varga
34 public interface YangParser {
36 * Return enumeration of concrete types of {@link SchemaSourceRepresentation} parsers created from this factory
37 * support. Users can use this information prepare the source they have to a representation which will be accepted
40 * @return Enumeration of supported schema source representations.
42 Collection<Class<? extends SchemaSourceRepresentation>> supportedSourceRepresentations();
45 * Return the set of all YANG statements semantically supported by this parser instance.
47 * @return Set of all YANG statements semantically supported by this parser instance.
49 Set<QName> supportedStatements();
52 * Add main source. All main sources are present in resulting SchemaContext.
55 * which should be added into main sources
56 * @throws YangSyntaxErrorException when one of the sources fails syntactic analysis
57 * @throws IOException when an IO error occurs
58 * @throws IllegalArgumentException if the representation is not supported
60 YangParser addSource(final SchemaSourceRepresentation source) throws IOException, YangSyntaxErrorException;
63 * Add main sources. All main sources are present in resulting SchemaContext.
66 * which should be added into main sources
67 * @throws YangSyntaxErrorException when one of the sources fails syntactic analysis
68 * @throws IOException when an IO error occurs
69 * @throws IllegalArgumentException if the representation is not supported
71 default YangParser addSources(final SchemaSourceRepresentation... sources) throws IOException,
72 YangSyntaxErrorException {
73 for (SchemaSourceRepresentation source : sources) {
79 default YangParser addSources(final Collection<? extends SchemaSourceRepresentation> sources) throws IOException,
80 YangSyntaxErrorException {
81 for (SchemaSourceRepresentation source : sources) {
87 YangParser addLibSource(SchemaSourceRepresentation source) throws IOException, YangSyntaxErrorException;
90 * Add library sources. Only library sources required by main sources are present in resulting SchemaContext.
91 * Any other library sources are ignored and this also applies to error reporting.
94 * Note: Library sources are not supported in semantic version mode currently.
97 * YANG sources which should be added into library sources
98 * @throws YangSyntaxErrorException when one of the sources fails syntactic analysis
99 * @throws IOException when an IO error occurs
100 * @throws IllegalArgumentException if the representation is not supported
102 default YangParser addLibSources(final SchemaSourceRepresentation... sources) throws IOException,
103 YangSyntaxErrorException {
104 for (SchemaSourceRepresentation source : sources) {
105 addLibSource(source);
110 default YangParser addLibSources(final Collection<SchemaSourceRepresentation> sources) throws IOException,
111 YangSyntaxErrorException {
112 for (SchemaSourceRepresentation source : sources) {
113 addLibSource(source);
119 * Set supported features based on which all if-feature statements in the
120 * parsed YANG modules will be resolved. If this method is not invoked, all features will be supported.
122 * @param supportedFeatures
123 * Set of supported features in the final SchemaContext.
124 * If the set is empty, no features encountered will be supported.
126 YangParser setSupportedFeatures(@Nonnull final Set<QName> supportedFeatures);
129 * Set YANG modules which can be deviated by specified modules during the parsing process.
130 * Map key (QNameModule) denotes a module which can be deviated by the modules in the Map value.
132 * @param modulesDeviatedByModules
133 * Map of YANG modules (Map key) which can be deviated by specified modules (Map value) in the final
134 * SchemaContext. If the map is empty, no deviations encountered will be supported.
136 YangParser setModulesWithSupportedDeviations(
137 @Nonnull SetMultimap<QNameModule, QNameModule> modulesDeviatedByModules);
140 * Build the declared view of a combined view of declared statements.
142 * @return Ordered collection of declared statements from requested sources.
143 * @throws YangSyntaxErrorException When a syntactic error is encountered.
145 List<DeclaredStatement<?>> buildDeclaredModel() throws YangParserException;
148 * Build the effective view of a combined view of effective statements. Note that this representation, unlike
149 * {@link #buildDeclaredModel()} does not expose submodules as top-level contracts. These are available from their
150 * respective parent modules.
152 * @return Effective module statements indexed by their QNameModule.
153 * @throws YangSyntaxErrorException When a syntactic error is encountered.
155 // FIXME: 3.0.0: Make this method non-default
156 default Map<QNameModule, ModuleEffectiveStatement> buildEffectiveModel() throws YangParserException {
157 throw new UnsupportedOperationException(getClass() + " does not implement buildEffectiveModel()");
161 * Build effective {@link SchemaContext}
163 * @return An effective schema context comprised of configured models.
164 * @throws YangSyntaxErrorException When a syntactic error is encountered.
166 SchemaContext buildSchemaContext() throws YangParserException;