/*
* Copyright (c) 2015 Cisco Systems, Inc. and others. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v1.0 which accompanies this distribution,
* and is available at http://www.eclipse.org/legal/epl-v10.html
*/
/**
*
* Definition of normalized YANG DOM Model
*
* Normalized DOM Model brings more direct mapping between YANG Model, DOM
* representation of data
*
* <h2>Normalized DOM Model</h2>
*
* <h3>Node Types</h3>
* <ul>
* <li> {@link org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode} -
* Base type representing a node in a tree structure; all nodes are derived from
* it, it contains a leaf identifier and a value.
* <ul>
* <li>
* {@link org.opendaylight.yangtools.yang.data.api.schema.DataContainerNode} -
* Node which contains multiple leafs; it does not have a direct representation
* in the YANG syntax.
* <ul>
* <li> {@link org.opendaylight.yangtools.yang.data.api.schema.ContainerNode} -
* Node, which represents a leaf which can occur only once per parent node; it
* contains multiple child leaves and maps to the <i>container</i> statement in
* YANG.</li>
* <li> {@link org.opendaylight.yangtools.yang.data.api.schema.MapEntryNode} -
* Node which represents a leaf, which can occur multiple times; a leave is
* uniquely identified by the value of its key. A MapEntryNode may contain
* multiple child leaves. MapEntryNode maps to the instance of <i>list</i> in
* YANG.</li>
* <li>
* {@link org.opendaylight.yangtools.yang.data.api.schema.UnkeyedListEntryNode}
* - Node which represents a leaf, which can occur multiple times; a leave is
* uniquely identified by the value of its key. A MapEntryNode may contain
* multiple child leaves. MapEntryNode maps to the instance of <i>list</i> in
* YANG.</li>
* <li> {@link org.opendaylight.yangtools.yang.data.api.schema.ChoiceNode} - Node
* which represents a leaf, which occurs mostly once per parent node, but
* possible values could have different types. Maps to <i>choice</i> statement.
* Types maps to the <i>case</i> statements for that <i>choice</i>.</li>
* <li> {@link org.opendaylight.yangtools.yang.data.api.schema.AugmentationNode}
* - Node which represents a leaf, which occurs mostly once per parent node.</li>
* </ul>
* </li>
* <li> {@link org.opendaylight.yangtools.yang.data.api.schema.LeafNode} - Node
* which represents a leaf, which occurs mostly once per parent node. Contains
* simple value.</li>
* <li> {@link org.opendaylight.yangtools.yang.data.api.schema.LeafSetEntryNode}
* - Node which represents a leaf, which type could occurs multiple times per
* parent node. Maps to to the instances of <i>leaf-list</i> in YANG.</li>
* <li> {@link org.opendaylight.yangtools.yang.data.api.schema.LeafSetNode} -
* Special node, which can occur only once per parent node; its leaves are
* LeafSetEntryNode nodes of specified type. Maps into the <i>leaf-list</i> in
* YANG.</li>
* <li> {@link org.opendaylight.yangtools.yang.data.api.schema.MapNode} - Special
* node, which can occur only once per parent node; its leaves are MapEntryNode
* nodes.
* <ul>
* <li> {@link org.opendaylight.yangtools.yang.data.api.schema.OrderedMapNode} -
* Special node, which can occur only once per parent node; its leaves are
* MapEntryNode nodes.</li>
* </ul>
* </li>
* <li> {@link org.opendaylight.yangtools.yang.data.api.schema.UnkeyedListNode} -
* Special node, which can occur only once per parent node; its leaves are
* MapEntryNode nodes.</li>
* </ul>
* </li>
* </ul>
*
* <h3>Tree / subtree structure</h3> <h4>Grammar representation</h4>
*
* <pre>
* {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier} = {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.PathArgument}*
* {@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}
*
* TreeRoot = {@link org.opendaylight.yangtools.yang.data.api.schema.DataContainerNode}
* {@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})*
* ContainerDataNode = {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeIdentifier} {@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.YangInstanceIdentifier.NodeIdentifier} SimpleValue
* {@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}
* {@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}
* {@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}
*
* // Special nodes
* {@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}*
* {@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}
* {@link org.opendaylight.yangtools.yang.data.api.schema.LeafSetEntryNode} = {@link org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeWithValue} SimpleValue
* </pre>
*
* The resulting tree organization is following:
*
* <ul>
* <li>(DataContainerNode)
* <ul>
* <li>(0..n) LeafNode</li>
* <li>(0..n) LeafSetNode
* <ul>
* <li>(0..n) LeafSetEntryNode</li>
* </ul>
* </li>
* <li>(0..n) ContainerNode
* <ul>
* <li>(Same as DataContainerNode)</li>
* </ul>
* </li>
* <li>(0..n) ContainerNode
* <ul>
* <li>(Same as DataContainerNode)</li>
* </ul>
* </li>
* <li>(0..n) MapNode
* <ul>
* <li>(0..n) MapEntryNode
* <ul>
* <li>(Same as DataContainerNode)</li>
* </ul>
* </li>
* </ul>
* </li>
* <li>(0..n) AugmentationNode
* <ul>
* <li>(Same as DataContainerNode)</li>
* </ul>
* </li>
* </ul>
* </li>
* </ul>
*
* <h3>Ordering of child nodes</h3>
*
* Ordering of child nodes is not enforced by this API definition, unless
* explicitly stated by subclasses of
* {@link org.opendaylight.yangtools.yang.data.api.schema.OrderedNodeContainer}
* which marks nodes with semantic constrain to preserve user-supplied ordering.
* <p>
* Clients should not expect any specific ordering of child nodes for interfaces
* from this package which does not extend
* {@link org.opendaylight.yangtools.yang.data.api.schema.OrderedNodeContainer},
* since implementations are not required to have well-defined order, which
* allows for more efficient implementations. If such ordering is required by
* clients for serialization / debugability it SHOULD be done externally in
* code using these interfaces.
*
*/
package org.opendaylight.yangtools.yang.data.api.schema;