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