binding/mdsal-binding-dom-codec-api/src/main/java/org/opendaylight/mdsal/binding/dom/codec/api/BindingAugmentationCodecTreeNode.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 static java.util.Objects.requireNonNull;
  11
  12 import com.google.common.annotations.Beta;
  13 import com.google.common.collect.ImmutableSet;
  14 import org.eclipse.jdt.annotation.NonNull;
  15 import org.eclipse.jdt.annotation.Nullable;
  16 import org.opendaylight.yangtools.yang.binding.Augmentation;
  17 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeIdentifier;
  18 import org.opendaylight.yangtools.yang.data.api.schema.DataContainerNode;
  19 import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode;
  20
  21 @Beta
  22 public interface BindingAugmentationCodecTreeNode<T extends Augmentation<?>>
  23         extends CommonDataObjectCodecTreeNode<T> {
  24     /**
  25      * Return an {@link Augmentation} instance backed by specified parent data. Implementations are free to return
  26      * either an eager transformation (not retaining {@code parentData}), or a lazy proxy. In both cases they must
  27      * ensure the result has at least one property populated (i.e. is not empty).
  28      *
  29      * @return An Augmentation, or {@code null} if the augmentation would be empty
  30      * @throws NullPointerException if {@code parentData} is {@code null}
  31      * @throws IllegalArgumentException if {@code parentData} is not a compatible parent
  32      */
  33     @Nullable T filterFrom(@NonNull DataContainerNode parentData);
  34
  35     /**
  36      * Return an {@link Augmentation} instance backed by specified parent data. Implementations are free to return
  37      * either an eager transformation (not retaining {@code parentData}), or a lazy proxy. In both cases they must
  38      * ensure the result has at least one property populated (i.e. is not empty).
  39      *
  40      * @return An Augmentation, or {@code null} if the augmentation would be empty
  41      * @throws NullPointerException if {@code parentData} is {@code null}
  42      * @throws IllegalArgumentException if {@code parentData} is not a compatible {@link DataContainerNode}
  43      */
  44     default @Nullable T filterFrom(final @NonNull NormalizedNode parentData) {
  45         if (requireNonNull(parentData) instanceof DataContainerNode parentContainer) {
  46             return filterFrom(parentContainer);
  47         }
  48         throw new IllegalArgumentException("Unsupported parent " + parentData.contract());
  49     }
  50
  51     /**
  52      * Returns the {@link NodeIdentifier}s of items contained in this {@link Augmentation}.
  53      *
  54      * @return A non-empty set of path arguments
  55      */
  56     @NonNull ImmutableSet<NodeIdentifier> childPathArguments();
  57 }