Remove Augmentation{Identifier,Node}
[yangtools.git] / 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;