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