binding/yang-binding/src/main/java/org/opendaylight/yangtools/yang/binding/Augmentable.java

   1 /*
   2  * Copyright (c) 2013 Cisco Systems, Inc. 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.yangtools.yang.binding;
   9
  10 import java.util.Map;
  11 import java.util.NoSuchElementException;
  12 import java.util.Optional;
  13 import java.util.function.Supplier;
  14 import org.eclipse.jdt.annotation.NonNull;
  15 import org.eclipse.jdt.annotation.Nullable;
  16
  17 /**
  18  * Augmentable (extensible) object which could carry additional data defined by a third-party extension, without
  19  * introducing conflict between various extension.
  20  *
  21  * <p>
  22  * This interface uses extended version of ExtensibleInterface pattern which also adds marker interface for
  23  * augmentations (extensions) - {@link Augmentable}.
  24  *
  25  * @param <T> Base class which should implements this interface and is target for augmentation.
  26  * @author Tony Tkacik
  27  */
  28 public interface Augmentable<T> {
  29     /**
  30      * Returns instance of augmentation, if present.
  31      *
  32      * @param <A> Type capture for augmentation type
  33      * @param augmentationType Type of augmentation to be returned
  34      * @return instance of {@code A}, or {@code null} if the augmentationType is not present
  35      * @throws NullPointerException if {@code augmentationType} is {@code null}
  36      */
  37     default <A extends Augmentation<T>> @Nullable A augmentation(final Class<A> augmentationType) {
  38         return augmentationType.cast(augmentations().get(augmentationType));
  39     }
  40
  41     /**
  42      * Returns instance of augmentation, or throws {@link NoSuchElementException}.
  43      *
  44      * @param <A> Type capture for augmentation type
  45      * @param augmentationType Type of augmentation to be returned
  46      * @return An instance of {@code A}
  47      * @throws NullPointerException if {@code augmentationType} is {@code null}
  48      * @throws NoSuchElementException if the corresponding augmentation is not present
  49      *
  50      * @apiNote
  51      *     The design here follows {@link Optional#orElseThrow()},
  52      */
  53     default <A extends Augmentation<T>> @NonNull A augmentationOrElseThrow(final Class<A> augmentationType) {
  54         final var augmentation = augmentation(augmentationType);
  55         if (augmentation != null) {
  56             return augmentation;
  57         }
  58         throw new NoSuchElementException(augmentationType.getName() + " is not present in " + this);
  59     }
  60
  61     /**
  62      * Returns instance of augmentation, or throws {@link NoSuchElementException}.
  63      *
  64      * @param <A> Type capture for augmentation type
  65      * @param <X> Type of the exception to be thrown
  66      * @param augmentationType Type of augmentation to be returned
  67      * @param exceptionSupplier the supplying function that produces an exception to be thrown
  68      * @return An instance of {@code A}
  69      * @throws NullPointerException if {@code augmentationType} is {@code null}
  70      * @throws X if the corresponding augmentation is not present
  71      *
  72      * @apiNote
  73      *     The design here follows {@link Optional#orElseThrow(Supplier)},
  74      */
  75     default <A extends Augmentation<T>, X extends Throwable> @NonNull A augmentationOrElseThrow(
  76             final Class<A> augmentationType, final Supplier<@NonNull X> exceptionSupplier) throws X {
  77         final var augmentation = augmentation(augmentationType);
  78         if (augmentation != null) {
  79             return augmentation;
  80         }
  81         throw exceptionSupplier.get();
  82     }
  83
  84     /**
  85      * Returns map of all augmentations.
  86      *
  87      * @return map of all augmentations.
  88      */
  89     @NonNull Map<Class<? extends Augmentation<T>>, Augmentation<T>> augmentations();
  90 }