Bump odlparent to 8.1.4

[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 60e076d22c6146675b2858c1642648792f17328d..d1c7eb62be978213a5140e3fdac1d2c6abef2d5b 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,8 +16,7 @@ import java.util.Collection;
 import java.util.Iterator;
 import java.util.NoSuchElementException;
 import java.util.Optional;
-import java.util.Set;
-import javax.annotation.Nullable;
+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
-    @Nullable default 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
+     * @throws NullPointerException if {@code name} is null
+     * @deprecated Use {@link #dataChildByName(QName)} or {@link #findDataChildByName(QName)} instead. This method will
+     *             be repurposed to assert existence in the next major release.
+     */
+    @Deprecated(forRemoval = true)
+    default @Nullable DataSchemaNode getDataChildByName(final QName name) {
+        return dataChildByName(name);
+    }
+
     /**
      * Returns the child node corresponding to the specified name.
      *
@@ -82,12 +98,40 @@ public interface DataNodeContainer {
      */
     Optional<DataSchemaNode> findDataChildByName(QName name);
 
+    /**
+     * 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.
+     *
+     * @param first QName of first child
+     * @param others QNames of subsequent children
+     * @return child node of this DataNodeContainer if child with given name is present, empty otherwise
+     * @throws NullPointerException if any argument is null
+     */
+    default Optional<DataSchemaNode> findDataChildByName(final QName first, final QName... others) {
+        Optional<DataSchemaNode> optCurrent = findDataChildByName(first);
+        for (QName qname : others) {
+            if (optCurrent.isPresent()) {
+                final DataSchemaNode current = optCurrent.get();
+                if (current instanceof DataNodeContainer) {
+                    optCurrent = ((DataNodeContainer) current).findDataChildByName(qname);
+                    continue;
+                }
+            }
+
+            return Optional.empty();
+        }
+        return optCurrent;
+    }
+
     /**
      * Returns grouping nodes used ny this container.
      *
      * @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
@@ -110,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;
@@ -153,7 +197,7 @@ public interface DataNodeContainer {
         DataNodeContainer parent = this;
         do {
             final Optional<DataSchemaNode> optChild = parent.findDataTreeChild(requireNonNull(it.next()));
-            if (!optChild.isPresent() || !it.hasNext()) {
+            if (optChild.isEmpty() || !it.hasNext()) {
                 return optChild;
             }