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