model/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/meta/ModelStatement.java

   1 /*
   2  * Copyright (c) 2015 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.meta;
   9
  10 import org.eclipse.jdt.annotation.NonNull;
  11 import org.opendaylight.yangtools.yang.common.Empty;
  12
  13 /**
  14  * Model statement. There are two base types of model statements:
  15  * <ul>
  16  *   <li>{@link DeclaredStatement}, which is to say, a statement as was defined in original source. This representation
  17  *       can be used during computation of effective model or during transformations of the YANG model from one
  18  *       serialization format to another -- for example creating a {@code .yin} file from a {@code .yang} file, or vice
  19  *       versa.
  20  *   </li>
  21  *   <li>{@link EffectiveStatement}, which is to say, a statement in its canonical form after all YANG language
  22  *       constructs have been applied to it. This representation has different traits as compared to the declared form,
  23  *       such as:
  24  *       <ul>
  25  *         <li>its substatement layout may differ, for example to account for implicit {@code case}, {@code input} and
  26  *             {@code output} statements</li>
  27  *         <li>it will omit {@code feature} and statements predicated on {@code if-feature} if the feature in question
  28  *             is not supported</li>
  29  *         <li>it will contain magic entries, like those in {@code ietf-restconf.yang}'s {@code operations} container
  30  *         </li>
  31  *         <li>the effects of a {@code uses} or {@code augment} statement being present<li>
  32  *       </ul>
  33  *
  34  *       This object model lends itself for processing YANG-modeled data without too much hustle. There are two
  35  *       RFC7950-based exceptions to this rule. These are driven by scarceness of use and scalability concerns:
  36  *       <ol>
  37  *         <li>{@code config} statements</li>
  38  *         <li>{@code status} statements</li>
  39  *       </ol>
  40  *
  41  *       While the {@link EffectiveStatement} model implies effective statements should be created so that any statement
  42  *       can be examined for the value, this has a significant scalability impact: for example in the case of a
  43  *       {@code grouping} definition, {@code config} is ignored, whereas in other contexts, even when introduced via
  44  *       a {@code uses} statement, it becomes either {@code true} or {@code false}. A similar situation occurs in case
  45  *       of {@code status} statements, yet it is less severe.
  46  *
  47  *       In both these cases real-life users are very scarce and this information can be computed given a particular
  48  *       {@link EffectiveStatement} tree position and is a sort of a parent reference (albeit very weak). For these two,
  49  *       and perhaps some other, statements the object model manifestation is subject to API contract.
  50  *   </li>
  51  * </ul>
  52  *
  53  * @param <A> Argument type ({@link Empty} if statement does not have argument.)
  54  */
  55 public sealed interface ModelStatement<A> permits DeclaredStatement, EffectiveStatement, AbstractModelStatement {
  56     /**
  57      * Statement Definition of this statement.
  58      *
  59      * @return definition of this statement.
  60      */
  61     @NonNull StatementDefinition statementDefinition();
  62
  63     /**
  64      * Returns statement argument.
  65      *
  66      * @return statement argument.
  67      */
  68     @NonNull A argument();
  69 }