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  * </ul>
  46  * </li>
  47  * <li> {@link org.opendaylight.yangtools.yang.data.api.schema.LeafNode} - Node
  48  * which represents a leaf, which occurs mostly once per parent node. Contains
  49  * simple value.</li>
  50  * <li> {@link org.opendaylight.yangtools.yang.data.api.schema.LeafSetEntryNode}
  51  * - Node which represents a leaf, which type could occurs multiple times per
  52  * parent node. Maps to to the instances of <i>leaf-list</i> in YANG.</li>
  53  * <li> {@link org.opendaylight.yangtools.yang.data.api.schema.LeafSetNode} -
  54  * Special node, which can occur only once per parent node; its leaves are
  55  * LeafSetEntryNode nodes of specified type. Maps into the <i>leaf-list</i> in
  56  * YANG.</li>
  57  * <li> {@link org.opendaylight.yangtools.yang.data.api.schema.MapNode} - Special
  58  * node, which can occur only once per parent node; its leaves are MapEntryNode
  59  * nodes.
  60  * <ul>
  61  * <li> {@link org.opendaylight.yangtools.yang.data.api.schema.UserMapNode} -
  62  * Special node, which can occur only once per parent node; its leaves are
  63  * MapEntryNode nodes.</li>
  64  * </ul>
  65  * </li>
  66  * <li> {@link org.opendaylight.yangtools.yang.data.api.schema.UnkeyedListNode} -
  67  * Special node, which can occur only once per parent node; its leaves are
  68  * MapEntryNode nodes.</li>
  69  * </ul>
  70  * </li>
  71  * </ul>
  72  *
  73  * <h3>Tree / subtree structure</h3> <h4>Grammar representation</h4>
  74  *
  75  * <pre>
  76  *  {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier} =
  77  *    {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.PathArgument}*
  78  *  {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.PathArgument} =
  79  *    {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeIdentifier}
  80  *    | {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeIdentifierWithPredicates}
  81  *    | {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeWithValue}
  82  *
  83  *  TreeRoot = {@link org.opendaylight.yangtools.yang.data.api.schema.DataContainerNode}
  84  *  {@link org.opendaylight.yangtools.yang.data.api.schema.DataContainerNode} =
  85  *    ( {@link org.opendaylight.yangtools.yang.data.api.schema.LeafNode}
  86  *     | {@link org.opendaylight.yangtools.yang.data.api.schema.ChoiceNode}
  87  *     | {@link org.opendaylight.yangtools.yang.data.api.schema.MapNode}
  88  *     | {@link org.opendaylight.yangtools.yang.data.api.schema.LeafSetNode})*
  89  *  ContainerDataNode =
  90  *    {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeIdentifier}
  91  *    {@link org.opendaylight.yangtools.yang.data.api.schema.DataContainerNode}
  92  *
  93  *  {@link org.opendaylight.yangtools.yang.data.api.schema.LeafNode} =
  94  *    {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeIdentifier} SimpleValue
  95  *  {@link org.opendaylight.yangtools.yang.data.api.schema.MapNode} =
  96  *    {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeIdentifier}
  97  *    {@link org.opendaylight.yangtools.yang.data.api.schema.MapEntryNode}
  98  *  {@link org.opendaylight.yangtools.yang.data.api.schema.MapEntryNode} =
  99  *    {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeIdentifierWithPredicates}
 100  *    {@link org.opendaylight.yangtools.yang.data.api.schema.DataContainerNode}
 101  *
 102  *  // Special nodes
 103  *  {@link org.opendaylight.yangtools.yang.data.api.schema.LeafSetNode} =
 104  *    {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeIdentifier}
 105  *    {@link org.opendaylight.yangtools.yang.data.api.schema.LeafSetEntryNode}*
 106  *  {@link org.opendaylight.yangtools.yang.data.api.schema.ChoiceNode} =
 107  *    {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeIdentifier}
 108  *    {@link org.opendaylight.yangtools.yang.data.api.schema.DataContainerNode}
 109  *  {@link org.opendaylight.yangtools.yang.data.api.schema.LeafSetEntryNode} =
 110  *    {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeWithValue} SimpleValue
 111  * </pre>
 112  *
 113  * <p>
 114  * The resulting tree organization is following:
 115  *
 116  * <ul>
 117  * <li>(DataContainerNode)
 118  * <ul>
 119  * <li>(0..n) LeafNode</li>
 120  * <li>(0..n) LeafSetNode
 121  * <ul>
 122  * <li>(0..n) LeafSetEntryNode</li>
 123  * </ul>
 124  * </li>
 125  * <li>(0..n) ContainerNode
 126  * <ul>
 127  * <li>(Same as DataContainerNode)</li>
 128  * </ul>
 129  * </li>
 130  * <li>(0..n) ContainerNode
 131  * <ul>
 132  * <li>(Same as DataContainerNode)</li>
 133  * </ul>
 134  * </li>
 135  * <li>(0..n) MapNode
 136  * <ul>
 137  * <li>(0..n) MapEntryNode
 138  * <ul>
 139  * <li>(Same as DataContainerNode)</li>
 140  * </ul>
 141  * </li>
 142  * </ul>
 143  * </li>
 144  * </ul>
 145  * </li>
 146  * </ul>
 147  *
 148  * <h3>Ordering of child nodes</h3>
 149  * Ordering of child nodes is not enforced by this API definition, unless
 150  * explicitly stated by subclasses of
 151  * {@link org.opendaylight.yangtools.yang.data.api.schema.OrderedNodeContainer}
 152  * which marks nodes with semantic constrain to preserve user-supplied ordering.
 153  *
 154  * <p>
 155  * Clients should not expect any specific ordering of child nodes for interfaces
 156  * from this package which does not extend
 157  * {@link org.opendaylight.yangtools.yang.data.api.schema.OrderedNodeContainer},
 158  * since implementations are not required to have well-defined order, which
 159  * allows for more efficient implementations. If such ordering is required by
 160  * clients for serialization / debugability it SHOULD be done externally in
 161  * code using these interfaces.
 162  */
 163 package org.opendaylight.yangtools.yang.data.api.schema;