yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/package-info.java

   1 /**
   2  *
   3  * Definition of normalized YANG DOM Model
   4  *
   5  * Normalized DOM Model brings more direct mapping between YANG Model, DOM
   6  * representation of data
   7  *
   8  * <h2>Normalized DOM Model</h2>
   9  *
  10  * <h3>Node Types</h3>
  11  * <ul>
  12  * <li> {@link org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode} -
  13  * Base type representing a node in a tree structure; all nodes are derived from
  14  * it, it contains a leaf identifier and a value.
  15  * <ul>
  16  * <li>
  17  * {@link org.opendaylight.yangtools.yang.data.api.schema.DataContainerNode} -
  18  * Node which contains multiple leafs; it does not have a direct representation
  19  * in the YANG syntax.
  20  * <ul>
  21  * <li> {@link org.opendaylight.yangtools.yang.data.api.schema.ContainerNode} -
  22  * Node, which represents a leaf which can occur only once per parent node; it
  23  * contains multiple child leaves and maps to the <i>container</i> statement in
  24  * YANG.</li>
  25  * <li> {@link org.opendaylight.yangtools.yang.data.api.schema.MapEntryNode} -
  26  * Node which represents a leaf, which can occur multiple times; a leave is
  27  * uniquely identified by the value of its key. A MapEntryNode may contain
  28  * multiple child leaves. MapEntryNode maps to the instance of <i>list</i> in
  29  * YANG.</li>
  30  * <li>
  31  * {@link org.opendaylight.yangtools.yang.data.api.schema.UnkeyedListEntryNode}
  32  * - Node which represents a leaf, which can occur multiple times; a leave is
  33  * uniquely identified by the value of its key. A MapEntryNode may contain
  34  * multiple child leaves. MapEntryNode maps to the instance of <i>list</i> in
  35  * YANG.</li>
  36  * <li> {@link org.opendaylight.yangtools.yang.data.api.schema.ChoiceNode} - Node
  37  * which represents a leaf, which occurs mostly once per parent node, but
  38  * possible values could have different types. Maps to <i>choice</i> statement.
  39  * Types maps to the <i>case</i> statements for that <i>choice</i>.</li>
  40  * <li> {@link org.opendaylight.yangtools.yang.data.api.schema.AugmentationNode}
  41  * - Node which represents a leaf, which occurs mostly once per parent node.</li>
  42  * </ul>
  43  * </li>
  44  * <li> {@link org.opendaylight.yangtools.yang.data.api.schema.LeafNode} - Node
  45  * which represents a leaf, which occurs mostly once per parent node. Contains
  46  * simple value.</li>
  47  * <li> {@link org.opendaylight.yangtools.yang.data.api.schema.LeafSetEntryNode}
  48  * - Node which represents a leaf, which type could occurs multiple times per
  49  * parent node. Maps to to the instances of <i>leaf-list</i> in YANG.</li>
  50  * <li> {@link org.opendaylight.yangtools.yang.data.api.schema.LeafSetNode} -
  51  * Special node, which can occur only once per parent node; its leaves are
  52  * LeafSetEntryNode nodes of specified type. Maps into the <i>leaf-list</i> in
  53  * YANG.</li>
  54  * <li> {@link org.opendaylight.yangtools.yang.data.api.schema.MapNode} - Special
  55  * node, which can occur only once per parent node; its leaves are MapEntryNode
  56  * nodes.
  57  * <ul>
  58  * <li> {@link org.opendaylight.yangtools.yang.data.api.schema.OrderedMapNode} -
  59  * Special node, which can occur only once per parent node; its leaves are
  60  * MapEntryNode nodes.</li>
  61  * </ul>
  62  * </li>
  63  * <li> {@link org.opendaylight.yangtools.yang.data.api.schema.UnkeyedListNode} -
  64  * Special node, which can occur only once per parent node; its leaves are
  65  * MapEntryNode nodes.</li>
  66  * </ul>
  67  * </li>
  68  * </ul>
  69  *
  70  * <h3>Tree / subtree structure</h3> <h4>Grammar representation</h4>
  71  *
  72  * <pre>
  73  *  {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier} = {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.PathArgument}*
  74  *  {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.PathArgument} = {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeIdentifier}| {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeIdentifierWithPredicates}| {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeWithValue} | {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.AugmentationIdentifier}
  75  *
  76  *  TreeRoot = {@link org.opendaylight.yangtools.yang.data.api.schema.DataContainerNode}
  77  *  {@link org.opendaylight.yangtools.yang.data.api.schema.DataContainerNode} = ( {@link org.opendaylight.yangtools.yang.data.api.schema.LeafNode} | {@link org.opendaylight.yangtools.yang.data.api.schema.ChoiceNode} | {@link org.opendaylight.yangtools.yang.data.api.schema.AugmentationNode} | {@link org.opendaylight.yangtools.yang.data.api.schema.MapNode} | {@link org.opendaylight.yangtools.yang.data.api.schema.LeafSetNode})*
  78  *  ContainerDataNode = {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeIdentifier} {@link org.opendaylight.yangtools.yang.data.api.schema.DataContainerNode}
  79  *
  80  *  {@link org.opendaylight.yangtools.yang.data.api.schema.LeafNode} = {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeIdentifier} SimpleValue
  81  *  {@link org.opendaylight.yangtools.yang.data.api.schema.AugmentationNode} = {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.AugmentationIdentifier} {@link org.opendaylight.yangtools.yang.data.api.schema.DataContainerNode}
  82  *  {@link org.opendaylight.yangtools.yang.data.api.schema.MapNode} = {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeIdentifier} {@link org.opendaylight.yangtools.yang.data.api.schema.MapEntryNode}
  83  *  {@link org.opendaylight.yangtools.yang.data.api.schema.MapEntryNode} = {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeIdentifierWithPredicates} {@link org.opendaylight.yangtools.yang.data.api.schema.DataContainerNode}
  84  *
  85  *  // Special nodes
  86  *  {@link org.opendaylight.yangtools.yang.data.api.schema.LeafSetNode} = {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeIdentifier} {@link org.opendaylight.yangtools.yang.data.api.schema.LeafSetEntryNode}*
  87  *  {@link org.opendaylight.yangtools.yang.data.api.schema.ChoiceNode} = {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeIdentifier} {@link org.opendaylight.yangtools.yang.data.api.schema.DataContainerNode}
  88  *  {@link org.opendaylight.yangtools.yang.data.api.schema.LeafSetEntryNode} = {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeWithValue} SimpleValue
  89  * </pre>
  90  *
  91  * The resulting tree organization is following:
  92  *
  93  * <ul>
  94  * <li>(DataContainerNode)
  95  * <ul>
  96  * <li>(0..n) LeafNode</li>
  97  * <li>(0..n) LeafSetNode
  98  * <ul>
  99  * <li>(0..n) LeafSetEntryNode</li>
 100  * </ul>
 101  * </li>
 102  * <li>(0..n) ContainerNode
 103  * <ul>
 104  * <li>(Same as DataContainerNode)</li>
 105  * </ul>
 106  * </li>
 107  * <li>(0..n) ContainerNode
 108  * <ul>
 109  * <li>(Same as DataContainerNode)</li>
 110  * </ul>
 111  * </li>
 112  * <li>(0..n) MapNode
 113  * <ul>
 114  * <li>(0..n) MapEntryNode
 115  * <ul>
 116  * <li>(Same as DataContainerNode)</li>
 117  * </ul>
 118  * </li>
 119  * </ul>
 120  * </li>
 121  * <li>(0..n) AugmentationNode
 122  * <ul>
 123  * <li>(Same as DataContainerNode)</li>
 124  * </ul>
 125  * </li>
 126  * </ul>
 127  * </li>
 128  * </ul>
 129  *
 130  * <h3>Ordering of child nodes</h3>
 131  *
 132  * Ordering of child nodes is not enforced by this API definition, unless
 133  * explicitly stated by subclasses of
 134  * {@link org.opendaylight.yangtools.yang.data.api.schema.OrderedNodeContainer}
 135  * which marks nodes with semantic constrain to preserve user-supplied ordering.
 136  * <p>
 137  * Clients should not expect any specific ordering of child nodes for interfaces
 138  * from this package which does not extend
 139  * {@link org.opendaylight.yangtools.yang.data.api.schema.OrderedNodeContainer},
 140  * since implementations are not required to have well-defined order, which
 141  * allows for more efficient implementations. If such ordering is required by
 142  * clients for serialization / debugability it SHOULD be done externally in
 143  * code using these interfaces.
 144  *
 145  */
 146 package org.opendaylight.yangtools.yang.data.api.schema;