binding/mdsal-binding-dom-codec-api/src/main/java/org/opendaylight/mdsal/binding/dom/codec/api/BindingDataContainerCodecTreeNode.java

   1 /*
   2  * Copyright (c) 2023 PANTHEON.tech, 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.mdsal.binding.dom.codec.api;
   9
  10 import java.util.List;
  11 import org.eclipse.jdt.annotation.NonNull;
  12 import org.eclipse.jdt.annotation.Nullable;
  13 import org.opendaylight.yangtools.yang.binding.Augmentation;
  14 import org.opendaylight.yangtools.yang.binding.BindingContract;
  15 import org.opendaylight.yangtools.yang.binding.DataContainer;
  16 import org.opendaylight.yangtools.yang.binding.DataObject;
  17 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
  18 import org.opendaylight.yangtools.yang.common.Empty;
  19 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier;
  20
  21 /**
  22  * A {@link BindingObjectCodecTreeNode} which corresponds to a {@link DataContainer} construct.
  23  *
  24  * @param <T> DataContainer type
  25  */
  26 public non-sealed interface BindingDataContainerCodecTreeNode<T extends DataContainer>
  27         extends BindingObjectCodecTreeNode, BindingDataObjectCodecTreeParent<Empty> {
  28     /**
  29      * Returns binding class of interface which represents API of current schema node. The result is same as invoking
  30      * {@link BindingContract#implementedInterface()} on instance of data.
  31      *
  32      * @return interface which defines API of binding representation of data.
  33      */
  34     @Override
  35     Class<T> getBindingClass();
  36
  37     /**
  38      * Returns child context as if it was walked by {@link BindingStreamEventWriter}. This means that to enter case,
  39      * one must issue getChild(ChoiceClass).getChild(CaseClass).
  40      *
  41      * <p>
  42      * This method differs from {@link #getStreamChild(Class)}, that is less strict for interfaces representing
  43      * augmentation and cases, that may return {@link BindingCodecTreeNode} even if augmentation interface containing
  44      * same data was supplied and does not represent augmentation of this node.
  45      *
  46      * @param childClass Child class by Binding Stream navigation
  47      * @return Context of child or {@code null} is supplied class is not applicable in context.
  48      * @throws NullPointerException if {@code childClass} is {@code null}
  49      */
  50     <E extends DataObject> @Nullable BindingDataContainerCodecTreeNode<E> streamChild(@NonNull Class<E> childClass);
  51
  52     default <A extends Augmentation<?>> @Nullable BindingAugmentationCodecTreeNode<A> streamAugmentation(
  53             final @NonNull Class<A> childClass) {
  54         final var result = streamChild(childClass);
  55         if (result instanceof BindingAugmentationCodecTreeNode) {
  56             return (BindingAugmentationCodecTreeNode<A>) result;
  57         } else if (result == null) {
  58             return null;
  59         } else {
  60             throw new IllegalArgumentException(
  61                 "Child " + childClass.getName() + " results in non-Augmentation " + result);
  62         }
  63     }
  64
  65     default <E extends DataObject> @Nullable BindingDataObjectCodecTreeNode<E> streamDataObject(
  66             final @NonNull Class<E> childClass) {
  67         final var result = streamChild(childClass);
  68         if (result instanceof BindingDataObjectCodecTreeNode) {
  69             return (BindingDataObjectCodecTreeNode<E>) result;
  70         } else if (result == null) {
  71             return null;
  72         } else {
  73             throw new IllegalArgumentException(
  74                 "Child " + childClass.getName() + " results in non-DataObject " + result);
  75         }
  76     }
  77
  78     /**
  79      * Returns nested node context using supplied YANG Instance Identifier.
  80      *
  81      * @param child
  82      *            Yang Instance Identifier Argument
  83      * @return Context of child
  84      * @throws IllegalArgumentException
  85      *             If supplied argument does not represent valid child.
  86      */
  87     @NonNull BindingCodecTreeNode yangPathArgumentChild(YangInstanceIdentifier.@NonNull PathArgument child);
  88
  89     /**
  90      * Returns nested node context using supplied Binding Instance Identifier and adds YANG instance identifiers to
  91      * the supplied list.
  92      *
  93      * @param arg
  94      *            Binding Instance Identifier Argument
  95      * @param builder
  96      *            Mutable instance of list, which is appended by YangInstanceIdentifiers
  97      *            as tree is walked. Use null if such side-product is not needed.
  98      * @return Context of child
  99      * @throws IllegalArgumentException
 100      *             If supplied argument does not represent valid child.
 101      */
 102     @NonNull CommonDataObjectCodecTreeNode<?> bindingPathArgumentChild(InstanceIdentifier.@NonNull PathArgument arg,
 103             @Nullable List<YangInstanceIdentifier.PathArgument> builder);
 104
 105     /**
 106      * Return a summary of addressability of potential children. Binding specification does not allow all DOM tree
 107      * elements to be directly addressed, which means some recursive tree operations, like data tree changes do not
 108      * have a one-to-one mapping from DOM to binding in all cases. This method provides an optimization hint to guide
 109      * translation of data structures, allowing for fast paths when all children are known to either be addressable
 110      * or non-addressable.
 111      *
 112      * @return Summary children addressability.
 113      */
 114     @NonNull ChildAddressabilitySummary getChildAddressabilitySummary();
 115
 116     /**
 117      * Enumeration of possible addressability attribute of all children.
 118      */
 119     enum ChildAddressabilitySummary {
 120         /**
 121          * All children are addressable.
 122          */
 123         ADDRESSABLE,
 124         /**
 125          * All children are non-addressable, including the case when this node does not have any children.
 126          */
 127         UNADDRESSABLE,
 128         /**
 129          * Mixed children, some are addressable and some are not.
 130          */
 131         MIXED
 132     }
 133 }