Update yang-parser-api
[yangtools.git] / yang / yang-parser-api / src / main / java / org / opendaylight / yangtools / yang / parser / api / YangParser.java
1 /*
2  * Copyright (c) 2017 Pantheon Technologies, s.r.o. 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.api;
9
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;
15 import java.util.Set;
16 import org.eclipse.jdt.annotation.NonNull;
17 import org.opendaylight.yangtools.yang.common.QName;
18 import org.opendaylight.yangtools.yang.common.QNameModule;
19 import org.opendaylight.yangtools.yang.model.api.EffectiveModelContext;
20 import org.opendaylight.yangtools.yang.model.api.meta.DeclaredStatement;
21 import org.opendaylight.yangtools.yang.model.repo.api.SchemaSourceRepresentation;
22
23 /**
24  * Configurable single-use YANG parser. Each instance can be configured to use a different set of models after
25  * which it is built. Models once added cannot be removed. Implementations are expected to be NOT thread-safe.
26  */
27 @Beta
28 public interface YangParser {
29     /**
30      * Return enumeration of concrete types of {@link SchemaSourceRepresentation} parsers created from this factory
31      * support. Users can use this information prepare the source they have to a representation which will be accepted
32      * by this parser.
33      *
34      * @return Enumeration of supported schema source representations.
35      */
36     @NonNull Collection<Class<? extends SchemaSourceRepresentation>> supportedSourceRepresentations();
37
38     /**
39      * Add main source. All main sources are present in resulting SchemaContext.
40      *
41      * @param source which should be added into main sources
42      * @throws YangSyntaxErrorException when one of the sources fails syntactic analysis
43      * @throws IOException when an IO error occurs
44      * @throws IllegalArgumentException if the representation is not supported
45      */
46     @NonNull YangParser addSource(SchemaSourceRepresentation source) throws IOException, YangSyntaxErrorException;
47
48     /**
49      * Add main sources. All main sources are present in resulting SchemaContext.
50      *
51      * @param sources which should be added into main sources
52      * @throws YangSyntaxErrorException when one of the sources fails syntactic analysis
53      * @throws IOException when an IO error occurs
54      * @throws IllegalArgumentException if the representation is not supported
55      */
56     default @NonNull YangParser addSources(final SchemaSourceRepresentation... sources) throws IOException,
57         YangSyntaxErrorException {
58         for (SchemaSourceRepresentation source : sources) {
59             addSource(source);
60         }
61         return this;
62     }
63
64     default @NonNull YangParser addSources(final Collection<? extends SchemaSourceRepresentation> sources)
65             throws IOException, YangSyntaxErrorException {
66         for (SchemaSourceRepresentation source : sources) {
67             addSource(source);
68         }
69         return this;
70     }
71
72     YangParser addLibSource(SchemaSourceRepresentation source) throws IOException, YangSyntaxErrorException;
73
74     /**
75      * Add library sources. Only library sources required by main sources are present in resulting SchemaContext.
76      * Any other library sources are ignored and this also applies to error reporting.
77      *
78      * <p>
79      * Note: Library sources are not supported in semantic version mode currently.
80      *
81      * @param sources YANG sources which should be added into library sources
82      * @throws YangSyntaxErrorException when one of the sources fails syntactic analysis
83      * @throws IOException when an IO error occurs
84      * @throws IllegalArgumentException if the representation is not supported
85      */
86     default @NonNull YangParser addLibSources(final SchemaSourceRepresentation... sources) throws IOException,
87             YangSyntaxErrorException {
88         for (SchemaSourceRepresentation source : sources) {
89             addLibSource(source);
90         }
91         return this;
92     }
93
94     default @NonNull YangParser addLibSources(final Collection<SchemaSourceRepresentation> sources) throws IOException,
95             YangSyntaxErrorException {
96         for (SchemaSourceRepresentation source : sources) {
97             addLibSource(source);
98         }
99         return this;
100     }
101
102     /**
103      * Set supported features based on which all if-feature statements in the parsed YANG modules will be resolved. If
104      * this method is not invoked, all features will be supported.
105      *
106      * @param supportedFeatures Set of supported features in the final SchemaContext. If the set is empty, no features
107      *                          encountered will be supported.
108      */
109     @NonNull YangParser setSupportedFeatures(@NonNull Set<QName> supportedFeatures);
110
111     /**
112      * Set YANG modules which can be deviated by specified modules during the parsing process. Map key (QNameModule)
113      * denotes a module which can be deviated by the modules in the Map value.
114      *
115      * @param modulesDeviatedByModules Map of YANG modules (Map key) which can be deviated by specified modules (Map
116      *                                 value) in the final SchemaContext. If the map is empty, no deviations encountered
117      *                                 will be supported.
118      */
119     @NonNull YangParser setModulesWithSupportedDeviations(
120             @NonNull SetMultimap<QNameModule, QNameModule> modulesDeviatedByModules);
121
122     /**
123      * Build the declared view of a combined view of declared statements.
124      *
125      * @return Ordered collection of declared statements from requested sources.
126      * @throws YangSyntaxErrorException When a syntactic error is encountered.
127      */
128     @NonNull List<DeclaredStatement<?>> buildDeclaredModel() throws YangParserException;
129
130     /**
131      * Build the effective view of a combined view of effective statements. Note that this representation, unlike
132      * {@link #buildDeclaredModel()} does not expose submodules as top-level contracts. These are available from their
133      * respective parent modules.
134      *
135      * @return Effective module statements indexed by their QNameModule.
136      * @throws YangSyntaxErrorException When a syntactic error is encountered.
137      */
138     @NonNull EffectiveModelContext buildEffectiveModel() throws YangParserException;
139 }