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.Map;
  16 import java.util.Set;
  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;
  25
  26 /**
  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.
  29  *
  30  * @author Robert Varga
  31  */
  32 @Beta
  33 @NotThreadSafe
  34 public interface YangParser {
  35     /**
  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
  38      * by this parser.
  39      *
  40      * @return Enumeration of supported schema source representations.
  41      */
  42     Collection<Class<? extends SchemaSourceRepresentation>> supportedSourceRepresentations();
  43
  44     /**
  45      * Return the set of all YANG statements semantically supported by this parser instance.
  46      *
  47      * @return Set of all YANG statements semantically supported by this parser instance.
  48      */
  49     Set<QName> supportedStatements();
  50
  51     /**
  52      * Add main source. All main sources are present in resulting SchemaContext.
  53      *
  54      * @param source
  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
  59      */
  60     YangParser addSource(SchemaSourceRepresentation source) throws IOException, YangSyntaxErrorException;
  61
  62     /**
  63      * Add main sources. All main sources are present in resulting SchemaContext.
  64      *
  65      * @param sources
  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
  70      */
  71     default YangParser addSources(final SchemaSourceRepresentation... sources) throws IOException,
  72         YangSyntaxErrorException {
  73         for (SchemaSourceRepresentation source : sources) {
  74             addSource(source);
  75         }
  76         return this;
  77     }
  78
  79     default YangParser addSources(final Collection<? extends SchemaSourceRepresentation> sources) throws IOException,
  80         YangSyntaxErrorException {
  81         for (SchemaSourceRepresentation source : sources) {
  82             addSource(source);
  83         }
  84         return this;
  85     }
  86
  87     YangParser addLibSource(SchemaSourceRepresentation source) throws IOException, YangSyntaxErrorException;
  88
  89     /**
  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.
  92      *
  93      * <p>
  94      * Note: Library sources are not supported in semantic version mode currently.
  95      *
  96      * @param sources
  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
 101      */
 102     default YangParser addLibSources(final SchemaSourceRepresentation... sources) throws IOException,
 103             YangSyntaxErrorException {
 104         for (SchemaSourceRepresentation source : sources) {
 105             addLibSource(source);
 106         }
 107         return this;
 108     }
 109
 110     default YangParser addLibSources(final Collection<SchemaSourceRepresentation> sources) throws IOException,
 111             YangSyntaxErrorException {
 112         for (SchemaSourceRepresentation source : sources) {
 113             addLibSource(source);
 114         }
 115         return this;
 116     }
 117
 118     /**
 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.
 121      *
 122      * @param supportedFeatures
 123      *            Set of supported features in the final SchemaContext.
 124      *            If the set is empty, no features encountered will be supported.
 125      */
 126     YangParser setSupportedFeatures(@Nonnull Set<QName> supportedFeatures);
 127
 128     /**
 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.
 131      *
 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.
 135      */
 136     YangParser setModulesWithSupportedDeviations(
 137             @Nonnull SetMultimap<QNameModule, QNameModule> modulesDeviatedByModules);
 138
 139     /**
 140      * Build the declared view of a combined view of declared statements.
 141      *
 142      * @return Ordered collection of declared statements from requested sources.
 143      * @throws YangSyntaxErrorException When a syntactic error is encountered.
 144      */
 145     List<DeclaredStatement<?>> buildDeclaredModel() throws YangParserException;
 146
 147     /**
 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.
 151      *
 152      * @return Effective module statements indexed by their QNameModule.
 153      * @throws YangSyntaxErrorException When a syntactic error is encountered.
 154      */
 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()");
 158     }
 159
 160     /**
 161      * Build effective {@link SchemaContext}.
 162      *
 163      * @return An effective schema context comprised of configured models.
 164      * @throws YangSyntaxErrorException When a syntactic error is encountered.
 165      */
 166     SchemaContext buildSchemaContext() throws YangParserException;
 167 }