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