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