/**
* Model statement. There are two base types of model statements:
* <ul>
- * <li>{@link DeclaredStatement} - Statement representation as was defined in original source. This representation
- * could be used during computation of effective model or during transforming YANG model from one serialization
- * format to another.
+ * <li>{@link DeclaredStatement}, which is to say, a statement as was defined in original source. This representation
+ * can be used during computation of effective model or during transformations of the YANG model from one
+ * serialization format to another -- for example creating a {@code .yin} file from a {@code .yang} file, or vice
+ * versa.
* </li>
- * <li>{@link EffectiveStatement} - Representation of effective statement - this statement may be different from
- * declared, in such way, that it contains additional substatements, provides access to model namespaces. Some
- * effective statements may be not directly declared in YANG source, but could be inferred by semantic processing
- * of other statements (for example {@code uses}, {@code augment} and others).
+ * <li>{@link EffectiveStatement}, which is to say, a statement in its canonical form after all YANG language
+ * constructs have been applied to it. This representation has different traits as compared to the declared form,
+ * such as:
+ * <ul>
+ * <li>its substatement layout may differ, for example to account for implicit {@code case}, {@code input} and
+ * {@code output} statements</li>
+ * <li>it will omit {@code feature} and statements predicated on {@code if-feature} if the feature in question
+ * is not supported</li>
+ * <li>it will contain magic entries, like those in {@code ietf-restconf.yang}'s {@code operations} container
+ * </li>
+ * <li>the effects of a {@code uses} or {@code augment} statement being present<li>
+ * </ul>
+ *
+ * This object model lends itself for processing YANG-modeled data without too much hustle. There are two
+ * RFC7950-based exceptions to this rule. These are driven by scarceness of use and scalability concerns:
+ * <ol>
+ * <li>{@code config} statements</li>
+ * <li>{@code status} statements</li>
+ * </ol>
+ *
+ * While the {@link EffectiveStatement} model implies effective statements should be created so that any statement
+ * can be examined for the value, this has a significant scalability impact: for example in the case of a
+ * {@code grouping} definition, {@code config} is ignored, whereas in other contexts, even when introduced via
+ * a {@code uses} statement, it becomes either {@code true} or {@code false}. A similar situation occurs in case
+ * of {@code status} statements, yet it is less severe.
+ *
+ * In both these cases real-life users are very scarce and this information can be computed given a particular
+ * {@link EffectiveStatement} tree position and is a sort of a parent reference (albeit very weak). For these two,
+ * and perhaps some other, statements the object model manifestation is subject to API contract.
* </li>
* </ul>
*
/**
* Effective representation of a {@code config} statement.
+ *
+ * <p>
+ * Note that unlike almost all other representations, these statements are only ever a reflection of a declared
+ * {@code config} statement. The truly effective status of a particular statement within a tree depends on its parent
+ * statements. As an example, given this YANG module:
+ * <pre>
+ * <code>
+ * module foo {
+ *
+ * grouping foo {
+ * leaf baz {
+ * type string;
+ * }
+ * }
+ *
+ * container bar {
+ * config false;
+ * uses foo;
+ * }
+ *
+ * uses bar;
+ * }
+ * </code>
+ * </pre>
+ * The object model will only reflect the {@code config} statement in {@code container bar}, but will not be present in
+ * {@code bar}'s {@code baz} leaf. The real effective {@code config} of {@code leaf baz} is a tri-state value:
+ * <ol>
+ * <li>within {@code grouping foo} it is not applicable, that is to say undefined</li>
+ * <li>within {@code container bar} it is inherited, that is to say {@code false}</li>
+ * <li>within {@code module foo} it is inherited from default, that is to say {@code true}</li>
+ * </ol>
+ *
+ * <p>
+ * Users are advised to use utility classes related to statement inference which consider parent/child relationships
+ * of statements.
*/
public interface ConfigEffectiveStatement extends EffectiveStatement<Boolean, ConfigStatement> {
@Override
/**
* Effective representation of a {@code status} statement.
+ *
+ * <p>
+ * Note that unlike almost all other representations, these statements are only ever a reflection of a declared
+ * {@code status} statement. The truly effective status of a particular statement within a tree depends on its parent
+ * statements. As an example, given this YANG module:
+ * <pre>
+ * <code>
+ * module foo {
+ *
+ * grouping foo {
+ * leaf baz {
+ * type string;
+ * }
+ * }
+ *
+ * container bar {
+ * status deprecated;
+ * uses foo;
+ * }
+ *
+ * uses foo;
+ * }
+ * </code>
+ * </pre>
+ * The object model will only reflect the {@code status} statement in {@code container bar}, but will not be present in
+ * {@code bar}'s {@code baz} leaf. Users are advised to use utility classes related to statement inference which
+ * consider parent/child relationships of statements.
*/
public interface StatusEffectiveStatement extends EffectiveStatement<Status, StatusStatement> {
@Override
Code Review / yangtools.git / commitdiff