MethodInvokers.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */

  18. package org.apache.commons.lang3.function;

  20. import java.lang.invoke.MethodHandle;
  21. import java.lang.invoke.MethodHandleProxies;
  22. import java.lang.invoke.MethodHandles;
  23. import java.lang.reflect.Method;
  24. import java.util.Objects;
  25. import java.util.function.BiConsumer;
  26. import java.util.function.BiFunction;
  27. import java.util.function.Function;
  28. import java.util.function.Supplier;

  30. import org.apache.commons.lang3.exception.UncheckedIllegalAccessException;

  32. /**
  33.  * Converts {@link Method} objects to lambdas.
  34.  * <p>
  35.  * More specifically, produces instances of single-method interfaces which redirect calls to methods; see
  36.  * {@link #asInterfaceInstance(Class, Method)}.
  37.  * </p>
  38.  * <h2>Calling supplier methods with no arguments</h2>
  39.  * <p>
  40.  * If the interface's single-method defines no arguments, use {@link #asFunction(Method)} and then apply the function
  41.  * passing in the object to receive the method call.
  42.  * </p>
  43.  * <p>
  44.  * For example to invoke {@link String#length()}:
  45.  * </p>
  46.  *
  47.  * <pre>{@code
  48.  * final Method method = String.class.getMethod("length");
  49.  * final Function<String, Integer> function = MethodInvokers.asFunction(method);
  50.  * assertEquals(3, function.apply("ABC"));
  51.  * }</pre>
  52.  *
  53.  * <h2>Calling function methods with one argument</h2>
  54.  * <p>
  55.  * If the interface's single-method defines one argument, use {@link #asBiFunction(Method)} and then apply the function
  56.  * passing in the object to receive the method call. The second argument to the function is the only argument to the
  57.  * method.
  58.  * </p>
  59.  * <p>
  60.  * For example to invoke {@link String#charAt(int)}:
  61.  * </p>
  62.  *
  63.  * <pre>{@code
  64.  * final Method method = String.class.getMethod("charAt", int.class);
  65.  * final BiFunction<String, Integer, Character> function = MethodInvokers.asBiFunction(method);
  66.  * assertEquals('C', function.apply("ABC", 2));
  67.  * }</pre>
  68.  *
  69.  * @since 3.13.0
  70.  */
  71. public final class MethodInvokers {

  73.     /**
  74.      * Produces a {@link BiConsumer} for a given <em>consumer</em> Method. For example, a classic setter method (as opposed
  75.      * to a fluent setter). You call the BiConsumer with two arguments: (1) the object receiving the method call, and (2)
  76.      * the method argument.
  77.      *
  78.      * @param <T> the type of the first argument to the operation: The type containing the Method.
  79.      * @param <U> the type of the second argument to the operation: The type of the method argument.
  80.      * @param method the method to invoke.
  81.      * @return a correctly-typed wrapper for the given target.
  82.      */
  83.     @SuppressWarnings("unchecked")
  84.     public static <T, U> BiConsumer<T, U> asBiConsumer(final Method method) {
  85.         return asInterfaceInstance(BiConsumer.class, method);
  86.     }

  88.     /**
  89.      * Produces a {@link BiFunction} for a given a <em>function</em> Method. You call the BiFunction with two arguments: (1)
  90.      * the object receiving the method call, and (2) the method argument. The BiFunction return type must match the method's
  91.      * return type.
  92.      * <p>
  93.      * For example to invoke {@link String#charAt(int)}:
  94.      * </p>
  95.      *
  96.      * <pre>{@code
  97.      * final Method method = String.class.getMethod("charAt", int.class);
  98.      * final BiFunction<String, Integer, Character> function = MethodInvokers.asBiFunction(method);
  99.      * assertEquals('C', function.apply("ABC", 2));
  100.      * }</pre>
  101.      *
  102.      * @param <T> the type of the first argument to the function: The type containing the method.
  103.      * @param <U> the type of the second argument to the function: the method argument type.
  104.      * @param <R> the type of the result of the function: The method return type.
  105.      * @param method the method to invoke.
  106.      * @return a correctly-typed wrapper for the given target.
  107.      */
  108.     @SuppressWarnings("unchecked")
  109.     public static <T, U, R> BiFunction<T, U, R> asBiFunction(final Method method) {
  110.         return asInterfaceInstance(BiFunction.class, method);
  111.     }

  113.     /**
  114.      * Produces a {@link FailableBiConsumer} for a given <em>consumer</em> Method. For example, a classic setter method (as
  115.      * opposed to a fluent setter). You call the FailableBiConsumer with two arguments: (1) the object receiving the method
  116.      * call, and (2) the method argument.
  117.      *
  118.      * @param <T> the type of the first argument to the operation: The type containing the Method.
  119.      * @param <U> the type of the second argument to the operation: The type of the method argument.
  120.      * @param method the method to invoke.
  121.      * @return a correctly-typed wrapper for the given target.
  122.      */
  123.     @SuppressWarnings("unchecked")
  124.     public static <T, U> FailableBiConsumer<T, U, Throwable> asFailableBiConsumer(final Method method) {
  125.         return asInterfaceInstance(FailableBiConsumer.class, method);
  126.     }

  128.     /**
  129.      * Produces a {@link FailableBiFunction} for a given a <em>function</em> Method. You call the FailableBiFunction with
  130.      * two arguments: (1) the object receiving the method call, and (2) the method argument. The BiFunction return type must
  131.      * match the method's return type.
  132.      *
  133.      * @param <T> the type of the first argument to the function: The type containing the method.
  134.      * @param <U> the type of the second argument to the function: the method argument type.
  135.      * @param <R> the type of the result of the function: The method return type.
  136.      * @param method the method to invoke.
  137.      * @return a correctly-typed wrapper for the given target.
  138.      */
  139.     @SuppressWarnings("unchecked")
  140.     public static <T, U, R> FailableBiFunction<T, U, R, Throwable> asFailableBiFunction(final Method method) {
  141.         return asInterfaceInstance(FailableBiFunction.class, method);
  142.     }

  144.     /**
  145.      * Produces a {@link FailableFunction} for a given a <em>supplier</em> Method. You call the Function with one argument:
  146.      * the object receiving the method call. The FailableFunction return type must match the method's return type.
  147.      *
  148.      * @param <T> the type of the first argument to the function: The type containing the method.
  149.      * @param <R> the type of the result of the function: The method return type.
  150.      * @param method the method to invoke.
  151.      * @return a correctly-typed wrapper for the given target.
  152.      */
  153.     @SuppressWarnings("unchecked")
  154.     public static <T, R> FailableFunction<T, R, Throwable> asFailableFunction(final Method method) {
  155.         return asInterfaceInstance(FailableFunction.class, method);
  156.     }

  158.     /**
  159.      * Produces a {@link FailableSupplier} for a given a <em>supplier</em> Method. The FailableSupplier return type must
  160.      * match the method's return type.
  161.      * <p>
  162.      * Only works with static methods.
  163.      * </p>
  164.      *
  165.      * @param <R> The Method return type.
  166.      * @param method the method to invoke.
  167.      * @return a correctly-typed wrapper for the given target.
  168.      */
  169.     @SuppressWarnings("unchecked")
  170.     public static <R> FailableSupplier<R, Throwable> asFailableSupplier(final Method method) {
  171.         return asInterfaceInstance(FailableSupplier.class, method);
  172.     }

  174.     /**
  175.      * Produces a {@link Function} for a given a <em>supplier</em> Method. You call the Function with one argument: the
  176.      * object receiving the method call. The Function return type must match the method's return type.
  177.      * <p>
  178.      * For example to invoke {@link String#length()}:
  179.      * </p>
  180.      *
  181.      * <pre>{@code
  182.      * final Method method = String.class.getMethod("length");
  183.      * final Function<String, Integer> function = MethodInvokers.asFunction(method);
  184.      * assertEquals(3, function.apply("ABC"));
  185.      * }</pre>
  186.      *
  187.      * @param <T> the type of the first argument to the function: The type containing the method.
  188.      * @param <R> the type of the result of the function: The method return type.
  189.      * @param method the method to invoke.
  190.      * @return a correctly-typed wrapper for the given target.
  191.      */
  192.     @SuppressWarnings("unchecked")
  193.     public static <T, R> Function<T, R> asFunction(final Method method) {
  194.         return asInterfaceInstance(Function.class, method);
  195.     }

  197.     /**
  198.      * Produces an instance of the given single-method interface which redirects its calls to the given method.
  199.      * <p>
  200.      * For the definition of "single-method", see {@link MethodHandleProxies#asInterfaceInstance(Class, MethodHandle)}.
  201.      * </p>
  202.      *
  203.      * @param <T> The interface type.
  204.      * @param interfaceClass a class object representing {@code T}.
  205.      * @param method the method to invoke.
  206.      * @return a correctly-typed wrapper for the given target.
  207.      * @see MethodHandleProxies#asInterfaceInstance(Class, MethodHandle)
  208.      */
  209.     public static <T> T asInterfaceInstance(final Class<T> interfaceClass, final Method method) {
  210.         return MethodHandleProxies.asInterfaceInstance(Objects.requireNonNull(interfaceClass, "interfaceClass"), unreflectUnchecked(method));
  211.     }

  213.     /**
  214.      * Produces a {@link Supplier} for a given a <em>supplier</em> Method. The Supplier return type must match the method's
  215.      * return type.
  216.      * <p>
  217.      * Only works with static methods.
  218.      * </p>
  219.      *
  220.      * @param <R> The Method return type.
  221.      * @param method the method to invoke.
  222.      * @return a correctly-typed wrapper for the given target.
  223.      */
  224.     @SuppressWarnings("unchecked")
  225.     public static <R> Supplier<R> asSupplier(final Method method) {
  226.         return asInterfaceInstance(Supplier.class, method);
  227.     }

  229.     /**
  230.      * Throws NullPointerException if {@code method} is {@code null}.
  231.      *
  232.      * @param method The method to test.
  233.      * @return The given method.
  234.      * @throws NullPointerException if {@code method} is {@code null}.
  235.      */
  236.     private static Method requireMethod(final Method method) {
  237.         return Objects.requireNonNull(method, "method");
  238.     }

  240.     private static MethodHandle unreflect(final Method method) throws IllegalAccessException {
  241.         return MethodHandles.lookup().unreflect(requireMethod(method));
  242.     }

  244.     private static MethodHandle unreflectUnchecked(final Method method) {
  245.         try {
  246.             return unreflect(method);
  247.         } catch (final IllegalAccessException e) {
  248.             throw new UncheckedIllegalAccessException(e);
  249.         }
  250.     }

  252.     /**
  253.      * No need to create instances.
  254.      */
  255.     private MethodInvokers() {
  256.         // noop
  257.     }

  259. }
Created with JaCoCo 0.8.12.202403310830