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