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.Identifiable;
  19 import org.opendaylight.yangtools.yang.binding.Identifier;
  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 Identifiable<K> & ChildOf<? super T>, K extends Identifier<N>>
  64         @NonNull MatchBuilderPath<O, N> extractChild(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     @FunctionalInterface
 205     public interface LeafReference<P, C> extends Serializable {
 206         /**
 207          * Dummy method to express the method signature of a typical getter. Due to this match we can match any Java
 208          * method reference which takes in {@code parent} and results in {@code child} -- expose the feature of using
 209          * {@code Parent::getChild} method shorthand.
 210          *
 211          * @param parent Parent object
 212          * @return Leaf value
 213          * @deprecated This method is present only for technical realization of taking the method reference and should
 214          *             never be involved directly. See {@code LambdaDecoder} for gory details.
 215          */
 216         @Deprecated(forRemoval = true)
 217         C dummyMethod(P parent);
 218     }
 219
 220     @FunctionalInterface
 221     public interface BooleanLeafReference<P> extends LeafReference<P, Boolean> {
 222
 223     }
 224
 225     @FunctionalInterface
 226     public interface Decimal64LeafReference<P> extends LeafReference<P, Decimal64> {
 227
 228     }
 229
 230     @FunctionalInterface
 231     public interface EmptyLeafReference<P> extends LeafReference<P, Empty> {
 232
 233     }
 234
 235     @FunctionalInterface
 236     public interface StringLeafReference<P> extends LeafReference<P, String> {
 237
 238     }
 239
 240     @FunctionalInterface
 241     public interface Int8LeafReference<P> extends LeafReference<P, Byte> {
 242
 243     }
 244
 245     @FunctionalInterface
 246     public interface Int16LeafReference<P> extends LeafReference<P, Short> {
 247
 248     }
 249
 250     @FunctionalInterface
 251     public interface Int32LeafReference<P> extends LeafReference<P, Integer> {
 252
 253     }
 254
 255     @FunctionalInterface
 256     public interface Int64LeafReference<P> extends LeafReference<P, Long> {
 257
 258     }
 259
 260     @FunctionalInterface
 261     public interface Uint8LeafReference<P> extends LeafReference<P, Uint8> {
 262
 263     }
 264
 265     @FunctionalInterface
 266     public interface Uint16LeafReference<P> extends LeafReference<P, Uint16> {
 267
 268     }
 269
 270     @FunctionalInterface
 271     public interface Uint32LeafReference<P> extends LeafReference<P, Uint32> {
 272
 273     }
 274
 275     @FunctionalInterface
 276     public interface Uint64LeafReference<P> extends LeafReference<P, Uint64> {
 277
 278     }
 279
 280     @FunctionalInterface
 281     public interface IdentityLeafReference<P, T extends BaseIdentity> extends LeafReference<P, T> {
 282
 283     }
 284
 285     @FunctionalInterface
 286     public interface TypeObjectLeafReference<P, T extends TypeObject> extends LeafReference<P, T> {
 287
 288     }
 289 }