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 java.io.IOException;
  15 import org.eclipse.jdt.annotation.NonNull;
  16 import org.eclipse.jdt.annotation.Nullable;
  17 import org.opendaylight.yangtools.yang.binding.Augmentable;
  18 import org.opendaylight.yangtools.yang.binding.Augmentation;
  19 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.PathArgument;
  20 import org.opendaylight.yangtools.yang.data.api.schema.DataContainerNode;
  21 import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode;
  22 import org.opendaylight.yangtools.yang.data.api.schema.stream.NormalizedNodeStreamWriter;
  23
  24 @Beta
  25 public interface BindingAugmentationCodecTreeNode<T extends Augmentation<?>>
  26         extends CommonDataObjectCodecTreeNode<T> {
  27     /**
  28      * Return an {@link Augmentation} instance backed by specified parent data. Implementations are free to return
  29      * either an eager transformation (not retaining {@code parentData}), or a lazy proxy. In both cases they must
  30      * ensure the result has at least one property populated (i.e. is not empty).
  31      *
  32      * @return An Augmentation, or {@code null} if the augmentation would be empty
  33      * @throws NullPointerException if {@code parentData} is {@code null}
  34      * @throws IllegalArgumentException if {@code parentData} is not a compatible parent
  35      */
  36     @Nullable T filterFrom(@NonNull DataContainerNode parentData);
  37
  38     /**
  39      * Return an {@link Augmentation} instance backed by specified parent data. Implementations are free to return
  40      * either an eager transformation (not retaining {@code parentData}), or a lazy proxy. In both cases they must
  41      * ensure the result has at least one property populated (i.e. is not empty).
  42      *
  43      * @return An Augmentation, or {@code null} if the augmentation would be empty
  44      * @throws NullPointerException if {@code parentData} is {@code null}
  45      * @throws IllegalArgumentException if {@code parentData} is not a compatible {@link DataContainerNode}
  46      */
  47     default @Nullable T filterFrom(final @NonNull NormalizedNode parentData) {
  48         if (requireNonNull(parentData) instanceof DataContainerNode parentContainer) {
  49             return filterFrom(parentContainer);
  50         }
  51         throw new IllegalArgumentException("Unsupported parent " + parentData.contract());
  52     }
  53
  54     /**
  55      * Write the contents of an {@link Augmentation} into a writer. The writer must beinitialized at the
  56      * augmentations's {@link Augmentable} parent's equivalent {@link DataContainerNode}.
  57      *
  58      * @param writer Writer to stream to
  59      * @param data Data to stream
  60      * @throws NullPointerException if any argument is {@code null}
  61      * @throws IOException if a streaming error occurs
  62      */
  63     void streamTo(@NonNull NormalizedNodeStreamWriter writer, @NonNull T data) throws IOException;
  64
  65     /**
  66      * Returns the {@link PathArgument}s of items contained in this {@link Augmentation}.
  67      *
  68      * @return A non-empty set of path arguments
  69      */
  70     @NonNull ImmutableSet<PathArgument> childPathArguments();
  71
  72     /**
  73      * Returns the {@link Class}es of items contain in this {@link Augmentation}.
  74      *
  75      * @return A non-empty set of classes
  76      */
  77     @NonNull ImmutableSet<Class<?>> childBindingClasses();
  78 }