Add DataNodeContainer.dataChildByName()

[yangtools.git] / yang / yang-model-api / src / main / java / org / opendaylight / yangtools / yang / model / api / DataNodeContainer.java

diff --git a/yang/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/DataNodeContainer.java b/yang/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/DataNodeContainer.java
index 845a3188dd03ee7f1cacbe39f7eaec6b49a71902..748d004895d56663443d0cb558b6329d1f845f77 100644 (file)
--- a/yang/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/DataNodeContainer.java
+++ b/yang/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/DataNodeContainer.java
@@ -16,7 +16,6 @@ import java.util.Collection;
 import java.util.Iterator;
 import java.util.NoSuchElementException;
 import java.util.Optional;
-import java.util.Set;
 import org.eclipse.jdt.annotation.Nullable;
 import org.opendaylight.yangtools.yang.common.QName;
 
@@ -29,7 +28,7 @@ public interface DataNodeContainer {
      *
      * @return typedef statements in lexicographical order
      */
-    Set<TypeDefinition<?>> getTypeDefinitions();
+    Collection<? extends TypeDefinition<?>> getTypeDefinitions();
 
     /**
      * Returns set of all child nodes defined within this DataNodeContainer. Although the return type is a collection,
@@ -42,14 +41,14 @@ public interface DataNodeContainer {
      *
      * @return child nodes in lexicographical order
      */
-    Collection<DataSchemaNode> getChildNodes();
+    Collection<? extends DataSchemaNode> getChildNodes();
 
     /**
      * Returns set of all groupings defined within this DataNodeContainer.
      *
      * @return grouping statements in lexicographical order
      */
-    Set<GroupingDefinition> getGroupings();
+    Collection<? extends GroupingDefinition> getGroupings();
 
     /**
      * Returns the child node corresponding to the specified name.
@@ -61,14 +60,31 @@ public interface DataNodeContainer {
      *
      * @param name QName of child
      * @return child node of this DataNodeContainer if child with given name is present, null otherwise
-     * @deprecated Use {@link #findDataChildByName(QName)} instead.
      * @throws NullPointerException if {@code name} is null
      */
-    @Deprecated
-    default @Nullable DataSchemaNode getDataChildByName(final QName name) {
+    default @Nullable DataSchemaNode dataChildByName(final QName name) {
         return findDataChildByName(name).orElse(null);
     }
 
+    /**
+     * Returns the child node corresponding to the specified name.
+     *
+     * <p>
+     * Note that the nodes searched are <strong>NOT</strong> {@code data nodes}, but rather {@link DataSchemaNode}s,
+     * hence {@link ChoiceSchemaNode} and {@link CaseSchemaNode} are returned instead of their matching children. This
+     * is consistent with {@code schema tree}.
+     *
+     * @param name QName of child
+     * @return child node of this DataNodeContainer if child with given name is present, null otherwise
+     * @deprecated Use {@link #dataChildByName(QName)} or {@link #findDataChildByName(QName)} instead. This method will
+     *             be repurposed to assert existence in the next major release.
+     * @throws NullPointerException if {@code name} is null
+     */
+    @Deprecated(forRemoval = true)
+    default @Nullable DataSchemaNode getDataChildByName(final QName name) {
+        return dataChildByName(name);
+    }
+
     /**
      * Returns the child node corresponding to the specified name.
      *
@@ -115,7 +131,7 @@ public interface DataNodeContainer {
      *
      * @return Set of all uses nodes defined within this DataNodeContainer
      */
-    Set<UsesNode> getUses();
+    Collection<? extends UsesNode> getUses();
 
     /**
      * Returns a {@code data node} identified by a QName. This method is distinct from
@@ -138,7 +154,7 @@ public interface DataNodeContainer {
         // hence we have to resort to a full search.
         for (DataSchemaNode child : getChildNodes()) {
             if (child instanceof ChoiceSchemaNode) {
-                for (CaseSchemaNode choiceCase : ((ChoiceSchemaNode) child).getCases().values()) {
+                for (CaseSchemaNode choiceCase : ((ChoiceSchemaNode) child).getCases()) {
                     final Optional<DataSchemaNode> caseChild = choiceCase.findDataTreeChild(name);
                     if (caseChild.isPresent()) {
                         return caseChild;