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