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 java.io.IOException;
  12 import java.util.Collection;
  13 import java.util.List;
  14 import java.util.Map;
  15 import java.util.Set;
  16 import javax.annotation.Nonnull;
  17 import javax.annotation.concurrent.NotThreadSafe;
  18 import org.opendaylight.yangtools.yang.common.QName;
  19 import org.opendaylight.yangtools.yang.common.QNameModule;
  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.
  27  *
  28  * @author Robert Varga
  29  */
  30 @Beta
  31 @NotThreadSafe
  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
  36      *
  37      * @return Enumeration of supported schema source representations.
  38      */
  39     Collection<Class<? extends SchemaSourceRepresentation>> supportedSourceRepresentations();
  40
  41     /**
  42      * Return the set of all YANG statements semantically supported by this parser instance.
  43      *
  44      * @return Set of all YANG statements semantically supported by this parser instance.
  45      */
  46     Set<QName> supportedStatements();
  47
  48     /**
  49      * Add main source. All main sources are present in resulting SchemaContext.
  50      *
  51      * @param source
  52      *            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     YangParser addSource(final SchemaSourceRepresentation source) throws IOException, YangSyntaxErrorException;
  58
  59     /**
  60      * Add main sources. All main sources are present in resulting SchemaContext.
  61      *
  62      * @param sources
  63      *            which should be added into main sources
  64      * @throws YangSyntaxErrorException when one of the sources fails syntactic analysis
  65      * @throws IOException when an IO error occurs
  66      * @throws IllegalArgumentException if the representation is not supported
  67      */
  68     default YangParser addSources(final SchemaSourceRepresentation... sources) throws IOException,
  69         YangSyntaxErrorException {
  70         for (SchemaSourceRepresentation source : sources) {
  71             addSource(source);
  72         }
  73         return this;
  74     }
  75
  76     default YangParser addSources(final Collection<? extends SchemaSourceRepresentation> sources) throws IOException,
  77         YangSyntaxErrorException {
  78         for (SchemaSourceRepresentation source : sources) {
  79             addSource(source);
  80         }
  81         return this;
  82     }
  83
  84     YangParser addLibSource(SchemaSourceRepresentation source) throws IOException, YangSyntaxErrorException;
  85
  86     /**
  87      * Add library sources. Only library sources required by main sources are present in resulting SchemaContext.
  88      * Any other library sources are ignored and this also applies to error reporting.
  89      *
  90      * <p>
  91      * Note: Library sources are not supported in semantic version mode currently.
  92      *
  93      * @param sources
  94      *            YANG sources which should be added into library sources
  95      * @throws YangSyntaxErrorException when one of the sources fails syntactic analysis
  96      * @throws IOException when an IO error occurs
  97      * @throws IllegalArgumentException if the representation is not supported
  98      */
  99     default YangParser addLibSources(final SchemaSourceRepresentation... sources) throws IOException,
 100             YangSyntaxErrorException {
 101         for (SchemaSourceRepresentation source : sources) {
 102             addLibSource(source);
 103         }
 104         return this;
 105     }
 106
 107     default YangParser addLibSources(final Collection<SchemaSourceRepresentation> sources) throws IOException,
 108             YangSyntaxErrorException {
 109         for (SchemaSourceRepresentation source : sources) {
 110             addLibSource(source);
 111         }
 112         return this;
 113     }
 114
 115     /**
 116      * Set supported features based on which all if-feature statements in the
 117      * parsed YANG modules will be resolved. If this method is not invoked, all features will be supported.
 118      *
 119      * @param supportedFeatures
 120      *            Set of supported features in the final SchemaContext.
 121      *            If the set is empty, no features encountered will be supported.
 122      */
 123     YangParser setSupportedFeatures(@Nonnull final Set<QName> supportedFeatures);
 124
 125     /**
 126      * Set YANG modules which can be deviated by specified modules during the parsing process.
 127      * Map key (QNameModule) denotes a module which can be deviated by the modules in the Map value.
 128      *
 129      * @param modulesDeviatedByModules
 130      *            Map of YANG modules (Map key) which can be deviated by specified modules (Map value) in the final
 131      *            SchemaContext. If the map is empty, no deviations encountered will be supported.
 132      */
 133     YangParser setModulesWithSupportedDeviations(
 134             @Nonnull Map<QNameModule, Set<QNameModule>> modulesDeviatedByModules);
 135
 136     /**
 137      * Build the declared view of a combined view of declared statements.
 138      *
 139      * @return Ordered collection of declared statements from requested sources.
 140      */
 141     List<DeclaredStatement<?>> buildDeclaredModel() throws YangParserException;
 142
 143     /**
 144      * Build effective {@link SchemaContext}
 145      *
 146      * @return An effective schema context comprised of configured models.
 147      * @throws YangSyntaxErrorException When a syntactic error is encountered.
 148      */
 149     SchemaContext buildSchemaContext() throws YangParserException;
 150 }