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 }