binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/YangModuleInfo.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.binding;
   9
  10 import com.google.common.base.MoreObjects;
  11 import com.google.common.collect.ImmutableList;
  12 import com.google.common.io.ByteSource;
  13 import com.google.common.io.CharSource;
  14 import java.io.IOException;
  15 import java.io.InputStream;
  16 import java.nio.charset.StandardCharsets;
  17 import java.util.Collection;
  18 import org.eclipse.jdt.annotation.NonNullByDefault;
  19 import org.opendaylight.yangtools.concepts.Immutable;
  20 import org.opendaylight.yangtools.yang.common.QName;
  21
  22 /**
  23  * Information and model capture for Binding V1. Instances of this class identify a packaged model and allow access
  24  * to its YANG text. They also contain references to {@link YangModuleInfo} instances as observed at code generation
  25  * time.
  26  *
  27  * <p>
  28  * The purpose of this class is to ensure package resolution order in OSGi environments, as implementations of this
  29  * interface are required to be co-located with generated code. When this module relies on some imports, that dependency
  30  * is expressed across jars via an implementation requirement to reference YangModuleInfos.
  31  */
  32 @NonNullByDefault
  33 public interface YangModuleInfo extends Immutable {
  34     /**
  35      * Returns YANG module name, as a composite {@link QName}. Module's namespace and revision maps to
  36      * {@link QName#getModule()} and module name maps to {@link QName#getLocalName()}.
  37      *
  38      * @return YANG module name.
  39      */
  40     QName getName();
  41
  42     /**
  43      * Return an open stream containing YANG text for this module. The stream is required to be UTF-8 encoded.
  44      *
  45      * @return An open stream.
  46      * @throws IOException If the stream cannot be opened.
  47      */
  48     InputStream openYangTextStream() throws IOException;
  49
  50     /**
  51      * Return {@link YangModuleInfo} objects for all modules which are imported by this module. Default implementation
  52      * returns an empty list.
  53      *
  54      * @return {@link YangModuleInfo} objects of all imported modules.
  55      */
  56     default Collection<YangModuleInfo> getImportedModules() {
  57         return ImmutableList.of();
  58     }
  59
  60     /**
  61      * Return a {@link ByteSource} accessing the YANG text of the module.
  62      *
  63      * @return A ByteSource.
  64      */
  65     default ByteSource getYangTextByteSource() {
  66         return new ByteSource() {
  67             @Override
  68             public InputStream openStream() throws IOException {
  69                 return openYangTextStream();
  70             }
  71
  72             @Override
  73             public String toString() {
  74                 return MoreObjects.toStringHelper(this).add("name", getName()).toString();
  75             }
  76         };
  77     }
  78
  79     /**
  80      * Return a {@link CharSource} accessing the YANG text of the module.
  81      *
  82      * @return A CharSource.
  83      */
  84     default CharSource getYangTextCharSource() {
  85         return getYangTextByteSource().asCharSource(StandardCharsets.UTF_8);
  86     }
  87 }