src/main/java/org/apache/commons/lang3/function/MethodInvokers.java

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

package org.apache.commons.lang3.function;

import java.lang.invoke.MethodHandle;
import java.lang.invoke.MethodHandleProxies;
import java.lang.invoke.MethodHandles;
import java.lang.reflect.Method;
import java.util.Objects;
import java.util.function.BiConsumer;
import java.util.function.BiFunction;
import java.util.function.Function;
import java.util.function.Supplier;

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

/**
 * Converts {@link Method} objects to lambdas.
 * <p>
 * More specifically, produces instances of single-method interfaces which redirect calls to methods; see
 * {@link #asInterfaceInstance(Class, Method)}.
 * </p>
 * <h2>Calling supplier methods with no arguments</h2>
 * <p>
 * If the interface's single-method defines no arguments, use {@link #asFunction(Method)} and then apply the function
 * passing in the object to receive the method call.
 * </p>
 * <p>
 * For example to invoke {@link String#length()}:
 * </p>
 *
 * <pre>{@code
 * final Method method = String.class.getMethod("length");
 * final Function<String, Integer> function = MethodInvokers.asFunction(method);
 * assertEquals(3, function.apply("ABC"));
 * }</pre>
 *
 * <h2>Calling function methods with one argument</h2>
 * <p>
 * If the interface's single-method defines one argument, use {@link #asBiFunction(Method)} and then apply the function
 * passing in the object to receive the method call. The second argument to the function is the only argument to the
 * method.
 * </p>
 * <p>
 * For example to invoke {@link String#charAt(int)}:
 * </p>
 *
 * <pre>{@code
 * final Method method = String.class.getMethod("charAt", int.class);
 * final BiFunction<String, Integer, Character> function = MethodInvokers.asBiFunction(method);
 * assertEquals('C', function.apply("ABC", 2));
 * }</pre>
 *
 * @since 3.13.0
 */
public final class MethodInvokers {

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

    /**
     * Produces a {@link BiFunction} for a given a <em>function</em> Method. You call the BiFunction with two arguments: (1)
     * the object receiving the method call, and (2) the method argument. The BiFunction return type must match the method's
     * return type.
     * <p>
     * For example to invoke {@link String#charAt(int)}:
     * </p>
     *
     * <pre>{@code
     * final Method method = String.class.getMethod("charAt", int.class);
     * final BiFunction<String, Integer, Character> function = MethodInvokers.asBiFunction(method);
     * assertEquals('C', function.apply("ABC", 2));
     * }</pre>
     *
     * @param <T> the type of the first argument to the function: The type containing the method.
     * @param <U> the type of the second argument to the function: the method argument type.
     * @param <R> the type of the result of the function: The method return type.
     * @param method the method to invoke.
     * @return a correctly-typed wrapper for the given target.
     */
    @SuppressWarnings("unchecked")
    public static <T, U, R> BiFunction<T, U, R> asBiFunction(final Method method) {
        return asInterfaceInstance(BiFunction.class, method);
    }

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

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

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

    /**
     * Produces a {@link FailableSupplier} for a given a <em>supplier</em> Method. The FailableSupplier return type must
     * match the method's return type.
     * <p>
     * Only works with static methods.
     * </p>
     *
     * @param <R> The Method return type.
     * @param method the method to invoke.
     * @return a correctly-typed wrapper for the given target.
     */
    @SuppressWarnings("unchecked")
    public static <R> FailableSupplier<R, Throwable> asFailableSupplier(final Method method) {
        return asInterfaceInstance(FailableSupplier.class, method);
    }

    /**
     * Produces a {@link Function} for a given a <em>supplier</em> Method. You call the Function with one argument: the
     * object receiving the method call. The Function return type must match the method's return type.
     * <p>
     * For example to invoke {@link String#length()}:
     * </p>
     *
     * <pre>{@code
     * final Method method = String.class.getMethod("length");
     * final Function<String, Integer> function = MethodInvokers.asFunction(method);
     * assertEquals(3, function.apply("ABC"));
     * }</pre>
     *
     * @param <T> the type of the first argument to the function: The type containing the method.
     * @param <R> the type of the result of the function: The method return type.
     * @param method the method to invoke.
     * @return a correctly-typed wrapper for the given target.
     */
    @SuppressWarnings("unchecked")
    public static <T, R> Function<T, R> asFunction(final Method method) {
        return asInterfaceInstance(Function.class, method);
    }

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

    /**
     * Produces a {@link Supplier} for a given a <em>supplier</em> Method. The Supplier return type must match the method's
     * return type.
     * <p>
     * Only works with static methods.
     * </p>
     *
     * @param <R> The Method return type.
     * @param method the method to invoke.
     * @return a correctly-typed wrapper for the given target.
     */
    @SuppressWarnings("unchecked")
    public static <R> Supplier<R> asSupplier(final Method method) {
        return asInterfaceInstance(Supplier.class, method);
    }

    /**
     * Throws NullPointerException if {@code method} is {@code null}.
     *
     * @param method The method to test.
     * @return The given method.
     * @throws NullPointerException if {@code method} is {@code null}.
     */
    private static Method requireMethod(final Method method) {
        return Objects.requireNonNull(method, "method");
    }

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

    private static MethodHandle unreflectUnchecked(final Method method) {
        try {
            return unreflect(method);
        } catch (final IllegalAccessException e) {
            throw new UncheckedIllegalAccessException(e);
        }
    }

    /**
     * No need to create instances.
     */
    private MethodInvokers() {
        // noop
    }

}