yang/yang-parser-api/src/main/java/org/opendaylight/yangtools/yang/model/parser/api/YangModelParser.java

   1 /*
   2  * Copyright (c) 2013 Cisco Systems, Inc. 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 org.opendaylight.yangtools.yang.model.api.Module;
  11 import org.opendaylight.yangtools.yang.model.api.SchemaContext;
  12 import org.opendaylight.yangtools.yang.model.api.type.UnknownTypeDefinition;
  13
  14 import java.io.File;
  15 import java.io.InputStream;
  16 import java.util.Collection;
  17 import java.util.List;
  18 import java.util.Map;
  19 import java.util.Set;
  20
  21 /**
  22  * Yang Model Parser interface is designed for parsing yang models and convert
  23  * the information to Data Schema Tree.
  24  *
  25  */
  26 // refactor methods returning input streams, after introducing
  27 public interface YangModelParser {
  28
  29     /**
  30      * Parse yangFile file and all yang files found in directory.
  31      *
  32      * @param yangFile
  33      *            file to parse
  34      * @param directory
  35      *            directory which contains additional yang files
  36      * @return Set of Yang Modules
  37      * @deprecated Use {@link YangContextParser#parseFile(File, File)} instead
  38      */
  39     @Deprecated
  40     Set<Module> parseYangModels(final File yangFile, final File directory);
  41
  42     /**
  43      * Parse one or more Yang model files and return the definitions of Yang
  44      * modules defined in *.yang files; <br>
  45      * This method SHOULD be used if user need to parse multiple yang models
  46      * that are referenced either through import or include statements.
  47      *
  48      * @param yangFiles
  49      *            yang files to parse
  50      * @return Set of Yang Modules
  51      * @deprecated Use {@link YangContextParser#parseFiles(Collection)} instead
  52      */
  53     @Deprecated
  54     Set<Module> parseYangModels(final List<File> yangFiles);
  55
  56     /**
  57      * Parse one or more Yang model files and return the definitions of Yang
  58      * modules defined in *.yang files. <br>
  59      * This method SHOULD be used if user has already parsed context and need to
  60      * parse additinal yang models which can have dependencies on models in this
  61      * context.
  62      *
  63      * @param yangFiles
  64      *            yang files to parse
  65      * @param context
  66      *            SchemaContext containing already parsed yang models
  67      * @return Set of Yang Modules
  68      * @deprecated Use {@link YangContextParser#parseFiles(Collection, SchemaContext)} instead
  69      */
  70     @Deprecated
  71     Set<Module> parseYangModels(final List<File> yangFiles, final SchemaContext context);
  72
  73     /**
  74      * Equivalent to {@link #parseYangModels(List)} that returns parsed modules
  75      * mapped to Files from which they were parsed.
  76      *
  77      * @param yangFiles
  78      *            yang files to parse
  79      * @return Map of Yang Modules
  80      */
  81     Map<File, Module> parseYangModelsMapped(final Collection<File> yangFiles);
  82
  83     /**
  84      * Parse one or more Yang model streams and return the definitions of Yang
  85      * modules defined in *.yang files; <br>
  86      * This method SHOULD be used if user need to parse multiple yang models
  87      * that are referenced either through import or include statements.
  88      *
  89      * @param yangModelStreams
  90      *            yang streams to parse
  91      * @return Set of Yang Modules
  92      * @deprecated Use {@link YangContextParser#parseSources(Collection)} instead
  93      */
  94     @Deprecated
  95     Set<Module> parseYangModelsFromStreams(final List<InputStream> yangModelStreams);
  96
  97     /**
  98      * Parse one or more Yang model streams and return the definitions of Yang
  99      * modules defined in *.yang files. <br>
 100      * This method SHOULD be used if user has already parsed context and need to
 101      * parse additinal yang models which can have dependencies on models in this
 102      * context.
 103      *
 104      * @param yangModelStreams
 105      *            yang streams to parse
 106      * @param context
 107      *            SchemaContext containing already parsed yang models
 108      * @return Set of Yang Modules
 109      * @deprecated Use {@link YangContextParser#parseSources(Collection, SchemaContext)} instead
 110      */
 111     @Deprecated
 112     Set<Module> parseYangModelsFromStreams(final List<InputStream> yangModelStreams, final SchemaContext context);
 113
 114     /**
 115      * Equivalent to {@link #parseYangModels(List)} that returns parsed modules
 116      * mapped to IputStreams from which they were parsed.
 117      *
 118      * @param yangModelStreams
 119      *            yang streams to parse
 120      * @return Map of Yang Modules
 121      */
 122     //TODO: when working with input streams do not swallow IOException, it should be propagated without having to wrap it in a runtime exception
 123     //FIXME: it is not defined in which state are the returning streams.
 124     Map<InputStream, Module> parseYangModelsFromStreamsMapped(final Collection<InputStream> yangModelStreams);
 125
 126     /**
 127      * Creates {@link SchemaContext} from specified Modules. The modules SHOULD
 128      * not contain any unresolved Schema Nodes or Type Definitions. By
 129      * unresolved Schema Nodes or Type Definitions we mean that the Module
 130      * should not contain ANY Schema Nodes that contains
 131      * {@link UnknownTypeDefinition} and all dependencies although via import or
 132      * include definitions are resolved.
 133      *
 134      * @param modules
 135      *            Set of Yang Modules
 136      * @return Schema Context instance constructed from whole Set of Modules.
 137      */
 138     SchemaContext resolveSchemaContext(final Set<Module> modules);
 139 }