binding/binding-data-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.binding.Augmentation;
  14 import org.opendaylight.yangtools.binding.BindingContract;
  15 import org.opendaylight.yangtools.binding.DataContainer;
  16 import org.opendaylight.yangtools.binding.DataObject;
  17 import org.opendaylight.yangtools.binding.DataObjectStep;
  18 import org.opendaylight.yangtools.yang.common.Empty;
  19 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.PathArgument;
  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 {@link PathArgument}.
  80      *
  81      * @param child a {@link PathArgument}
  82      * @return Context of child
  83      * @throws IllegalArgumentException If supplied argument does not represent valid child.
  84      */
  85     @NonNull BindingCodecTreeNode yangPathArgumentChild(@NonNull PathArgument child);
  86
  87     /**
  88      * Returns nested node context using supplied DataObjectStep and adds YANG instance identifiers to
  89      * the supplied list.
  90      *
  91      * @param step A {@link DataObjectStep}
  92      * @param builder a mutable List to receive {@link PathArgument}s. Use {@code null} if such side-product is not
  93      *                needed.
  94      * @return A {@link CommonDataObjectCodecTreeNode}
  95      * @throws IllegalArgumentException if supplied argument does not represent valid child.
  96      */
  97     @NonNull CommonDataObjectCodecTreeNode<?> bindingPathArgumentChild(@NonNull DataObjectStep<?> step,
  98             @Nullable List<PathArgument> builder);
  99
 100     /**
 101      * Return a summary of addressability of potential children. Binding specification does not allow all DOM tree
 102      * elements to be directly addressed, which means some recursive tree operations, like data tree changes do not
 103      * have a one-to-one mapping from DOM to binding in all cases. This method provides an optimization hint to guide
 104      * translation of data structures, allowing for fast paths when all children are known to either be addressable
 105      * or non-addressable.
 106      *
 107      * @return Summary children addressability.
 108      */
 109     @NonNull ChildAddressabilitySummary getChildAddressabilitySummary();
 110
 111     /**
 112      * Enumeration of possible addressability attribute of all children.
 113      */
 114     enum ChildAddressabilitySummary {
 115         /**
 116          * All children are addressable.
 117          */
 118         ADDRESSABLE,
 119         /**
 120          * All children are non-addressable, including the case when this node does not have any children.
 121          */
 122         UNADDRESSABLE,
 123         /**
 124          * Mixed children, some are addressable and some are not.
 125          */
 126         MIXED
 127     }
 128 }