model/yang-model-api/src/main/java/org/opendaylight/yangtools/yang/model/api/stmt/SchemaTreeAwareEffectiveStatement.java

   1 /*
   2  * Copyright (c) 2018 Pantheon Technologies, s.r.o. 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 package org.opendaylight.yangtools.yang.model.api.stmt;
   9
  10 import java.util.Arrays;
  11 import java.util.Collection;
  12 import java.util.Iterator;
  13 import java.util.List;
  14 import java.util.NoSuchElementException;
  15 import java.util.Optional;
  16 import org.eclipse.jdt.annotation.NonNull;
  17 import org.opendaylight.yangtools.yang.common.QName;
  18 import org.opendaylight.yangtools.yang.model.api.meta.DeclaredStatement;
  19 import org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement;
  20 import org.opendaylight.yangtools.yang.model.api.stmt.SchemaNodeIdentifier.Descendant;
  21
  22 /**
  23  * Interface implemented by all {@link EffectiveStatement}s which can contain a {@code schema tree} child. This tree
  24  * can be walked using {@link SchemaNodeIdentifier}, looking up each component of
  25  * {@link SchemaNodeIdentifier#getNodeIdentifiers()} using {@link #findSchemaTreeNode(QName)}.
  26  *
  27  * @param <A> Argument type
  28  * @param <D> Class representing declared version of this statement.
  29  */
  30 public interface SchemaTreeAwareEffectiveStatement<A, D extends DeclaredStatement<A>> extends EffectiveStatement<A, D> {
  31     /**
  32      * Enumerate all {@code schema node}s defined within this node.
  33      *
  34      * @return All substatements participating on the {@code schema tree}
  35      */
  36     @NonNull Collection<SchemaTreeEffectiveStatement<?>> schemaTreeNodes();
  37
  38     /**
  39      * Find a {@code schema tree} child {@link SchemaTreeEffectiveStatement}, as identified by its QName argument.
  40      *
  41      * @param qname Child identifier
  42      * @return Schema tree child, or empty
  43      * @throws NullPointerException if {@code qname} is null
  44      */
  45     @NonNull Optional<SchemaTreeEffectiveStatement<?>> findSchemaTreeNode(@NonNull QName qname);
  46
  47     /**
  48      * Find a {@code schema tree} child {@link SchemaTreeEffectiveStatement}, as identified by its QName argument.
  49      *
  50      * @param <E> Effective substatement type
  51      * @param type Effective substatement class
  52      * @param qname Child identifier
  53      * @return Schema tree child, or empty
  54      * @throws NullPointerException if any argument is null
  55      */
  56     default <E> @NonNull Optional<E> findSchemaTreeNode(final @NonNull Class<E> type, final @NonNull QName qname) {
  57         return DefaultMethodHelpers.filterOptional(findSchemaTreeNode(qname), type);
  58     }
  59
  60     /**
  61      * Find a {@code schema tree} child {@link SchemaTreeEffectiveStatement}, as identified by its QName argument.
  62      *
  63      * @param qnames Child identifiers
  64      * @return Schema tree child, or empty
  65      * @throws NullPointerException if {@code qnames} is null or contains a null element
  66      * @throws NoSuchElementException if {@code qnames} is empty
  67      */
  68     default @NonNull Optional<SchemaTreeEffectiveStatement<?>> findSchemaTreeNode(final @NonNull QName... qnames) {
  69         return findSchemaTreeNode(Arrays.asList(qnames));
  70     }
  71
  72     /**
  73      * Find a {@code schema tree} child {@link SchemaTreeEffectiveStatement}, as identified by its QName argument.
  74      *
  75      * @param <E> Effective substatement type
  76      * @param type Effective substatement class
  77      * @param qnames Child identifiers
  78      * @return Schema tree child, or empty
  79      * @throws NullPointerException if any argument is null or if {@code qnames} contains a null element
  80      * @throws NoSuchElementException if {@code qnames} is empty
  81      */
  82     default <E> @NonNull Optional<E> findSchemaTreeNode(final @NonNull Class<E> type, final @NonNull QName... qnames) {
  83         return DefaultMethodHelpers.filterOptional(findSchemaTreeNode(Arrays.asList(qnames)), type);
  84     }
  85
  86     /**
  87      * Find a {@code schema tree} child {@link SchemaTreeEffectiveStatement}, as identified by its QName argument.
  88      *
  89      * @param qnames Child identifiers
  90      * @return Schema tree child, or empty
  91      * @throws NullPointerException if {@code qnames} is null or contains a null element
  92      * @throws NoSuchElementException if {@code qnames} is empty
  93      */
  94     default @NonNull Optional<SchemaTreeEffectiveStatement<?>> findSchemaTreeNode(final @NonNull List<QName> qnames) {
  95         final Iterator<QName> it = qnames.iterator();
  96         SchemaTreeAwareEffectiveStatement<?, ?> parent = this;
  97         while (true) {
  98             final var found = parent.findSchemaTreeNode(it.next());
  99             if (!it.hasNext() || found.isEmpty()) {
 100                 return found;
 101             }
 102             final SchemaTreeEffectiveStatement<?> node = found.orElseThrow();
 103             if (node instanceof SchemaTreeAwareEffectiveStatement<?, ?> aware) {
 104                 parent = aware;
 105             } else {
 106                 return Optional.empty();
 107             }
 108         }
 109     }
 110
 111     /**
 112      * Find a {@code schema tree} child {@link SchemaTreeEffectiveStatement}, as identified by its QName argument.
 113      *
 114      * @param <E> Effective substatement type
 115      * @param type Effective substatement class
 116      * @param qnames Child identifiers
 117      * @return Schema tree child, or empty
 118      * @throws NullPointerException if {@code qnames} is null or contains a null element
 119      * @throws NoSuchElementException if {@code qnames} is empty
 120      */
 121     default <E> @NonNull Optional<E> findSchemaTreeNode(final @NonNull Class<E> type,
 122             final @NonNull List<QName> qnames) {
 123         return DefaultMethodHelpers.filterOptional(findSchemaTreeNode(qnames), type);
 124     }
 125
 126     /**
 127      * Find a {@code schema tree} child {@link SchemaTreeEffectiveStatement}, as identified by its
 128      * {@link Descendant descendant schema node identifier}.
 129      *
 130      * @implSpec
 131      *     Default implementation defers to {@link #findSchemaTreeNode(List)}.
 132      *
 133      * @param descendant Descendant schema node identifier
 134      * @return Schema tree child, or empty
 135      * @throws NullPointerException if {@code descendant} is null
 136      */
 137     default @NonNull Optional<SchemaTreeEffectiveStatement<?>> findSchemaTreeNode(
 138             final @NonNull Descendant descendant) {
 139         return findSchemaTreeNode(descendant.getNodeIdentifiers());
 140     }
 141
 142     /**
 143      * Find a {@code schema tree} child {@link SchemaTreeEffectiveStatement}, as identified by its
 144      * {@link Descendant descendant schema node identifier}.
 145      *
 146      * @implSpec
 147      *     Default implementation defers to {@link #findSchemaTreeNode(Class, List)}.
 148      *
 149      * @param <E> Effective substatement type
 150      * @param type Effective substatement class
 151      * @param descendant Descendant schema node identifier
 152      * @return Schema tree child, or empty
 153      * @throws NullPointerException if {@code descendant} is null
 154      */
 155     default <E> @NonNull Optional<E> findSchemaTreeNode(final @NonNull Class<E> type,
 156             final @NonNull Descendant descendant) {
 157         return findSchemaTreeNode(type, descendant.getNodeIdentifiers());
 158     }
 159 }