yang/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/Module.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.api;
   9
  10 import java.net.URI;
  11 import java.util.Date;
  12 import java.util.List;
  13 import java.util.Optional;
  14 import java.util.Set;
  15 import javax.annotation.Nonnull;
  16 import javax.annotation.Nullable;
  17 import javax.annotation.concurrent.Immutable;
  18 import org.opendaylight.yangtools.concepts.SemVer;
  19 import org.opendaylight.yangtools.yang.common.QNameModule;
  20 import org.opendaylight.yangtools.yang.common.YangVersion;
  21
  22 /**
  23  * This interface contains the methods for getting the data from the YANG
  24  * module.<br>
  25  * <br>
  26  * <i>Example of YANG module</i> <code><br>
  27  * {@link #getName() <b><font color="#FF0000">module</font></b>} module_name{<br>
  28     &nbsp;&nbsp;{@link #getYangVersion() <b><font color="#8b4513">yang-version</font></b>} "1";<br><br>
  29
  30     &nbsp;&nbsp;{@link #getNamespace() <b><font color="#00FF00">namespace</font></b>} "urn:module:namespace";<br>
  31     &nbsp;&nbsp;{@link #getPrefix() <b><font color="#0000FF">prefix</font></b><a name="prefix"></a>} "prefix";<br><br>
  32
  33     &nbsp;&nbsp;{@link #getDescription() <b><font color="#b8860b">description</font></b>} "description test";<br>
  34     &nbsp;&nbsp;{@link #getReference() <b><font color="#008b8b">reference</font></b>} "reference test";<br><br>
  35
  36     &nbsp;&nbsp;{@link #getOrganization() <b><font color="#606060">organization</font></b>}
  37     "John Doe, john.doe@email.com";<br>
  38     &nbsp;&nbsp;{@link #getContact() <b><font color="#FF9900">contact</font></b>} "http://www.opendaylight.org/";<br>
  39     <br>
  40
  41     &nbsp;&nbsp;{@link #getFeatures() <b><font color="#8b0000">feature</font></b>} feature-test{<br>
  42     &nbsp;&nbsp;&nbsp;&nbsp; description "description of some feature";<br>
  43     &nbsp;&nbsp;}<br>
  44
  45     &nbsp;&nbsp;{@link #getNotifications() <b><font color="#b22222">notification</font></b>} notification-test;<br>
  46     &nbsp;&nbsp;{@link #getRpcs() <b><font color="#d2691e">rpc</font></b>} rpc-test;<br>
  47     <!-- &nbsp;&nbsp;{@link #getDeviations() <b><font color="#b8860b">deviation</font></b>} deviation-test;<br> -->
  48     &nbsp;&nbsp;{@link #getIdentities() <b><font color="#bdb76b">identity</font></b>} identity-test;<br>
  49     &nbsp;&nbsp;{@link #getExtensionSchemaNodes() <b><font color="#808000">extension</font></b>} extension-test;<br>
  50
  51
  52     &nbsp;&nbsp;{@link #getRevision() <b><font color="#339900">revision</font></b>} 2011-08-27 {<br>
  53
  54     &nbsp;&nbsp;{@link #getImports() <b><font color="#9400d3">import</font></b>} other_module {<br>
  55     &nbsp;&nbsp;&nbsp;&nbsp;prefix "other_module_prefix"<br>
  56     &nbsp;&nbsp;&nbsp;&nbsp;revision-date 2011-08-27<br>
  57     &nbsp;&nbsp;}<br><br>
  58
  59     &nbsp;&nbsp;container cont {<br>
  60     &nbsp;&nbsp;}<br>
  61
  62     &nbsp;&nbsp;{@link #getAugmentations() <b><font color="#dc143c">augment</font></b>} "/cont" { ;<br>
  63     &nbsp;&nbsp;}<br>
  64     }
  65
  66     </code>
  67  */
  68 @Immutable
  69 public interface Module extends DataNodeContainer, NotificationNodeContainer {
  70     /**
  71      * Returns the name of the module which is specified as argument of YANG
  72      * {@link Module <b><font color="#FF0000">module</font></b>} keyword.
  73      *
  74      * @return string with the name of the module
  75      */
  76     String getName();
  77
  78     /**
  79      * Returns a {@link QNameModule}, which contains the namespace and
  80      * the revision of the module.
  81      *
  82      * @return QNameModule identifier.
  83      */
  84     QNameModule getQNameModule();
  85
  86     /**
  87      * Returns the namespace of the module which is specified as argument of
  88      * YANG {@link Module <b><font color="#00FF00">namespace</font></b>}
  89      * keyword. If you need both namespace and revision, please consider using
  90      * {@link #getQNameModule()}.
  91      *
  92      * @return URI format of the namespace of the module
  93      */
  94     default URI getNamespace() {
  95         return getQNameModule().getNamespace();
  96     }
  97
  98     /**
  99      * Returns the revision date for the module. If you need both namespace and
 100      * revision, please consider using {@link #getQNameModule()}.
 101      *
 102      * @return date of the module revision which is specified as argument of
 103      *         YANG {@link Module <b><font color="#339900">revison</font></b>}
 104      *         keyword
 105      */
 106     // FIXME: BUG-4688: should return Optional<Revision>
 107     @Nullable default Date getRevision() {
 108         return getQNameModule().getRevision();
 109     }
 110
 111     /**
 112      * Returns the semantic version of yang module.
 113      *
 114      * <p>
 115      * If the semantic version is not specified, default semantic version of
 116      * module is returned.
 117      *
 118      * @return SemVer semantic version of yang module which is specified as
 119      *         argument of
 120      *         (urn:opendaylight:yang:extension:semantic-version?revision
 121      *         =2016-02-02)semantic-version statement
 122      */
 123     Optional<SemVer> getSemanticVersion();
 124
 125     /**
 126      * Returns the prefix of the module.
 127      *
 128      * @return string with the module prefix which is specified as argument of
 129      *         YANG {@link Module <b><font color="#0000FF">prefix</font></b>}
 130      *         keyword
 131      */
 132     String getPrefix();
 133
 134     /**
 135      * Returns the YANG version.
 136      *
 137      * @return YANG version of this module.
 138      */
 139     YangVersion getYangVersion();
 140
 141     /**
 142      * Returns the module description.
 143      *
 144      * @return string with the module description which is specified as argument
 145      *         of YANG {@link Module <b><font
 146      *         color="#b8860b">description</font></b>} keyword
 147      */
 148     String getDescription();
 149
 150     /**
 151      * Returns the module reference.
 152      *
 153      * @return string with the module reference which is specified as argument
 154      *         of YANG {@link Module <b><font
 155      *         color="#008b8b">reference</font></b>} keyword
 156      */
 157     String getReference();
 158
 159     /**
 160      * Returns the module organization.
 161      *
 162      * @return string with the name of the organization specified in the module
 163      *         as the argument of YANG {@link Module <b><font
 164      *         color="#606060">organization</font></b>} keyword
 165      */
 166     String getOrganization();
 167
 168     /**
 169      * Returns the module contact.
 170      *
 171      * <p>
 172      * The contact represents the person or persons to whom technical queries
 173      * concerning this module should be sent, such as their name, postal
 174      * address, telephone number, and electronic mail address.
 175      *
 176      * @return string with the contact data specified in the module as the
 177      *         argument of YANG {@link Module <b><font
 178      *         color="#FF9900">contact</font></b>} keyword
 179      */
 180     String getContact();
 181
 182     /**
 183      * Returns imports which represents YANG modules which are imported to this
 184      * module via <b>import</b> statement.
 185      *
 186      * @return set of module imports which are specified in the module as the
 187      *         argument of YANG {@link Module <b><font
 188      *         color="#9400d3">import</font></b>} keywords.
 189      */
 190     Set<ModuleImport> getImports();
 191
 192     Set<Module> getSubmodules();
 193
 194     /**
 195      * Returns <code>FeatureDefinition</code> instances which contain data from
 196      * <b>feature</b> statements defined in the module.
 197      *
 198      * <p>
 199      * The feature is used to define a mechanism by which portions of the schema
 200      * are marked as conditional.
 201      *
 202      * @return feature statements in lexicographical order which are specified
 203      *         in the module as the argument of YANG {@link Module <b><font
 204      *         color="#8b0000">feature</font></b>} keywords.
 205      */
 206     Set<FeatureDefinition> getFeatures();
 207
 208     /**
 209      * Returns <code>AugmentationSchema</code> instances which contain data from
 210      * <b>augment</b> statements defined in the module.
 211      *
 212      * @return set of the augmentation schema instances which are specified in
 213      *         the module as YANG {@link Module <b><font
 214      *         color="#dc143c">augment</font></b>} keyword and are
 215      *         lexicographically ordered
 216      */
 217     Set<AugmentationSchema> getAugmentations();
 218
 219     /**
 220      * Returns <code>RpcDefinition</code> instances which contain data from
 221      * <b>rpc</b> statements defined in the module.
 222      *
 223      * @return set of the rpc definition instances which are specified in the
 224      *         module as YANG {@link Module <b><font
 225      *         color="#d2691e">rpc</font></b>} keywords and are lexicographicaly
 226      *         ordered
 227      */
 228     Set<RpcDefinition> getRpcs();
 229
 230     /**
 231      * Returns <code>Deviation</code> instances which contain data from
 232      * <b>deviation</b> statements defined in the module.
 233      *
 234      * @return set of the deviation instances
 235      */
 236     Set<Deviation> getDeviations();
 237
 238     /**
 239      * Returns <code>IdentitySchemaNode</code> instances which contain data from
 240      * <b>identity</b> statements defined in the module.
 241      *
 242      * @return set of identity schema node instances which are specified in the
 243      *         module as YANG {@link Module <b><font
 244      *         color="#bdb76b">identity</font></b>} keywords and are
 245      *         lexicographically ordered
 246      */
 247     Set<IdentitySchemaNode> getIdentities();
 248
 249     /**
 250      * Returns <code>ExtensionDefinition</code> instances which contain data
 251      * from <b>extension</b> statements defined in the module.
 252      *
 253      * @return set of extension definition instances which are specified in the
 254      *         module as YANG {@link Module <b><font
 255      *         color="#808000">extension</font></b>} keyword and are
 256      *         lexicographically ordered
 257      */
 258     List<ExtensionDefinition> getExtensionSchemaNodes();
 259
 260     /**
 261      * Returns unknown nodes defined in module.
 262      *
 263      * @return unknown nodes in lexicographical order
 264      */
 265     @Nonnull
 266     List<UnknownSchemaNode> getUnknownSchemaNodes();
 267 }