binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/binding/api/query/MatchBuilderPath.java

   1 /*
   2  * Copyright (c) 2020 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.api.query;
   9
  10 import com.google.common.annotations.Beta;
  11 import java.io.Serializable;
  12 import org.eclipse.jdt.annotation.NonNull;
  13 import org.opendaylight.yangtools.concepts.Mutable;
  14 import org.opendaylight.yangtools.yang.binding.BaseIdentity;
  15 import org.opendaylight.yangtools.yang.binding.ChildOf;
  16 import org.opendaylight.yangtools.yang.binding.ChoiceIn;
  17 import org.opendaylight.yangtools.yang.binding.DataObject;
  18 import org.opendaylight.yangtools.yang.binding.Key;
  19 import org.opendaylight.yangtools.yang.binding.KeyAware;
  20 import org.opendaylight.yangtools.yang.binding.TypeObject;
  21 import org.opendaylight.yangtools.yang.common.Decimal64;
  22 import org.opendaylight.yangtools.yang.common.Empty;
  23 import org.opendaylight.yangtools.yang.common.Uint16;
  24 import org.opendaylight.yangtools.yang.common.Uint32;
  25 import org.opendaylight.yangtools.yang.common.Uint64;
  26 import org.opendaylight.yangtools.yang.common.Uint8;
  27
  28 @Beta
  29 public interface MatchBuilderPath<O extends DataObject, T extends DataObject> extends Mutable {
  30     /**
  31      * Descend match into a child container.
  32      *
  33      * @param <N> Child container type
  34      * @param childClass Child container type class
  35      * @return This builder
  36      * @throws NullPointerException if childClass is null
  37      */
  38     <N extends ChildOf<? super T>> @NonNull MatchBuilderPath<O, N> childObject(Class<N> childClass);
  39
  40     /**
  41      * Descend match into a child container in a particular case.
  42      *
  43      * @param <C> Case type
  44      * @param <N> Child container type
  45      * @param childClass Child container type class
  46      * @return This builder
  47      * @throws NullPointerException if any argument is null
  48      */
  49     <C extends ChoiceIn<? super T> & DataObject, N extends ChildOf<? super C>>
  50         @NonNull MatchBuilderPath<O, N> extractChild(Class<C> caseClass, Class<N> childClass);
  51
  52     /**
  53      * Add a child path component to the specification of what needs to be extracted, specifying an exact match in
  54      * a keyed list. This method, along with its alternatives, can be used to specify which object type to select from
  55      * the root path.
  56      *
  57      * @param <N> List type
  58      * @param <K> Key type
  59      * @param listKey List key
  60      * @return This builder
  61      * @throws NullPointerException if childClass is null
  62      */
  63     <N extends KeyAware<K> & ChildOf<? super T>, K extends Key<N>> @NonNull MatchBuilderPath<O, N> extractChild(
  64         Class<@NonNull N> listItem, K listKey);
  65
  66     /**
  67      * Match an {@code boolean} leaf's value.
  68      *
  69      * @param methodRef method reference to the getter method
  70      * @return A {@link ValueMatchBuilder}
  71      * @throws NullPointerException if methodRef is null
  72      */
  73     @NonNull ValueMatchBuilder<O, Boolean> leaf(BooleanLeafReference<T> methodRef);
  74
  75     /**
  76      * Match an {@code decimal64} leaf's value.
  77      *
  78      * @param methodRef method reference to the getter method
  79      * @return A {@link ValueMatchBuilder}
  80      * @throws NullPointerException if methodRef is null
  81      */
  82     @NonNull ComparableMatchBuilder<O, Decimal64> leaf(Decimal64LeafReference<T> methodRef);
  83
  84     /**
  85      * Match an {@code empty} leaf's value.
  86      *
  87      * @param methodRef method reference to the getter method
  88      * @return A {@link ValueMatchBuilder}
  89      * @throws NullPointerException if methodRef is null
  90      */
  91     @NonNull ValueMatchBuilder<O, Empty> leaf(EmptyLeafReference<T> methodRef);
  92
  93     /**
  94      * Match an {@code string} leaf's value.
  95      *
  96      * @param methodRef method reference to the getter method
  97      * @return A {@link StringMatchBuilder}
  98      * @throws NullPointerException if methodRef is null
  99      */
 100     @NonNull StringMatchBuilder<O> leaf(StringLeafReference<T> methodRef);
 101
 102     /**
 103      * Match an {@code int8} leaf's value.
 104      *
 105      * @param methodRef method reference to the getter method
 106      * @return A {@link ComparableMatchBuilder}
 107      * @throws NullPointerException if methodRef is null
 108      */
 109     @NonNull ComparableMatchBuilder<O, Byte> leaf(Int8LeafReference<T> methodRef);
 110
 111     /**
 112      * Match an {@code int16} leaf's value.
 113      *
 114      * @param methodRef method reference to the getter method
 115      * @return A {@link ComparableMatchBuilder}
 116      * @throws NullPointerException if methodRef is null
 117      */
 118     @NonNull ComparableMatchBuilder<O, Short> leaf(Int16LeafReference<T> methodRef);
 119
 120     /**
 121      * Match an {@code int32} leaf's value.
 122      *
 123      * @param methodRef method reference to the getter method
 124      * @return A {@link ComparableMatchBuilder}
 125      * @throws NullPointerException if methodRef is null
 126      */
 127     @NonNull ComparableMatchBuilder<O, Integer> leaf(Int32LeafReference<T> methodRef);
 128
 129     /**
 130      * Match an {@code int64} leaf's value.
 131      *
 132      * @param methodRef method reference to the getter method
 133      * @return A {@link ComparableMatchBuilder}
 134      * @throws NullPointerException if methodRef is null
 135      */
 136     @NonNull ComparableMatchBuilder<O, Long> leaf(Int64LeafReference<T> methodRef);
 137
 138     /**
 139      * Match an {@code uint8} leaf's value.
 140      *
 141      * @param methodRef method reference to the getter method
 142      * @return A {@link ComparableMatchBuilder}
 143      * @throws NullPointerException if methodRef is null
 144      */
 145     @NonNull ComparableMatchBuilder<O, Uint8> leaf(Uint8LeafReference<T> methodRef);
 146
 147     /**
 148      * Match an {@code uint16} leaf's value.
 149      *
 150      * @param methodRef method reference to the getter method
 151      * @return A {@link ComparableMatchBuilder}
 152      * @throws NullPointerException if methodRef is null
 153      */
 154     @NonNull ComparableMatchBuilder<O, Uint16> leaf(Uint16LeafReference<T> methodRef);
 155
 156     /**
 157      * Match an {@code uint32} leaf's value.
 158      *
 159      * @param methodRef method reference to the getter method
 160      * @return A {@link ComparableMatchBuilder}
 161      * @throws NullPointerException if methodRef is null
 162      */
 163     @NonNull ComparableMatchBuilder<O, Uint32> leaf(Uint32LeafReference<T> methodRef);
 164
 165     /**
 166      * Match an {@code uint64} leaf's value.
 167      *
 168      * @param methodRef method reference to the getter method
 169      * @return A {@link ComparableMatchBuilder}
 170      * @throws NullPointerException if methodRef is null
 171      */
 172     @NonNull ComparableMatchBuilder<O, Uint64> leaf(Uint64LeafReference<T> methodRef);
 173
 174     /**
 175      * Match an {@code identityref} leaf's value.
 176      *
 177      * @param methodRef method reference to the getter method
 178      * @return A {@link ValueMatchBuilder}
 179      * @throws NullPointerException if methodRef is null
 180      */
 181     <I extends BaseIdentity> @NonNull ValueMatchBuilder<O, I> leaf(IdentityLeafReference<T, I> methodRef);
 182
 183     /**
 184      * Match a generic leaf value.
 185      *
 186      * @param methodRef method reference to the getter method
 187      * @return A {@link ValueMatchBuilder}
 188      * @throws NullPointerException if methodRef is null
 189      */
 190     <C extends TypeObject> @NonNull ValueMatchBuilder<O, C> leaf(TypeObjectLeafReference<T, C> methodRef);
 191
 192     /**
 193      * Base interface for capturing binding getter method references through lambda expressions. This interface should
 194      * never be used directly, but rather through one of its specializations.
 195      *
 196      * <p>
 197      * This interface uncharacteristically extends {@link Serializable} for the purposes of making the resulting lambda
 198      * also Serializable. This part is critical for the process of introspection into the lambda and identifying the
 199      * method being invoked.
 200      *
 201      * @param <P> Parent type
 202      * @param <C> Child type
 203      */
 204     sealed interface LeafReference<P, C> extends Serializable {
 205         /**
 206          * Dummy method to express the method signature of a typical getter. Due to this match we can match any Java
 207          * method reference which takes in {@code parent} and results in {@code child} -- expose the feature of using
 208          * {@code Parent::getChild} method shorthand.
 209          *
 210          * @param parent Parent object
 211          * @return Leaf value
 212          * @deprecated This method is present only for technical realization of taking the method reference and should
 213          *             never be involved directly. See {@code LambdaDecoder} for gory details.
 214          */
 215         @Deprecated(forRemoval = true)
 216         C dummyMethod(P parent);
 217     }
 218
 219     @FunctionalInterface
 220     non-sealed interface BooleanLeafReference<P> extends LeafReference<P, Boolean> {
 221         // Nothing here
 222     }
 223
 224     @FunctionalInterface
 225     non-sealed interface Decimal64LeafReference<P> extends LeafReference<P, Decimal64> {
 226         // Nothing here
 227     }
 228
 229     @FunctionalInterface
 230     non-sealed interface EmptyLeafReference<P> extends LeafReference<P, Empty> {
 231         // Nothing here
 232     }
 233
 234     @FunctionalInterface
 235     non-sealed interface StringLeafReference<P> extends LeafReference<P, String> {
 236         // Nothing here
 237     }
 238
 239     @FunctionalInterface
 240     non-sealed interface Int8LeafReference<P> extends LeafReference<P, Byte> {
 241         // Nothing here
 242     }
 243
 244     @FunctionalInterface
 245     non-sealed interface Int16LeafReference<P> extends LeafReference<P, Short> {
 246         // Nothing here
 247     }
 248
 249     @FunctionalInterface
 250     non-sealed interface Int32LeafReference<P> extends LeafReference<P, Integer> {
 251         // Nothing here
 252     }
 253
 254     @FunctionalInterface
 255     non-sealed interface Int64LeafReference<P> extends LeafReference<P, Long> {
 256         // Nothing here
 257     }
 258
 259     @FunctionalInterface
 260     non-sealed interface Uint8LeafReference<P> extends LeafReference<P, Uint8> {
 261         // Nothing here
 262     }
 263
 264     @FunctionalInterface
 265     non-sealed interface Uint16LeafReference<P> extends LeafReference<P, Uint16> {
 266         // Nothing here
 267     }
 268
 269     @FunctionalInterface
 270     non-sealed interface Uint32LeafReference<P> extends LeafReference<P, Uint32> {
 271         // Nothing here
 272     }
 273
 274     @FunctionalInterface
 275     non-sealed interface Uint64LeafReference<P> extends LeafReference<P, Uint64> {
 276         // Nothing here
 277     }
 278
 279     @FunctionalInterface
 280     non-sealed interface IdentityLeafReference<P, T extends BaseIdentity> extends LeafReference<P, T> {
 281         // Nothing here
 282     }
 283
 284     @FunctionalInterface
 285     non-sealed interface TypeObjectLeafReference<P, T extends TypeObject> extends LeafReference<P, T> {
 286         // Nothing here
 287     }
 288 }