001/*
002 * Copyright 2022-2026 Revetware LLC.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package com.soklet;
018
019import org.jspecify.annotations.NonNull;
020import org.jspecify.annotations.Nullable;
021
022import java.util.List;
023
024/**
025 * Contract for determining parameter values to inject when invoking <em>Resource Methods</em>.
026 * <p>
027 * It is unusual for applications to provide their own {@link ResourceMethodParameterProvider} implementations.
028 * <p>
029 * However, should it be necessary, documentation is available at <a href="https://www.soklet.com/docs/request-handling#resource-method-parameter-injection">https://www.soklet.com/docs/request-handling#resource-method-parameter-injection</a>.
030 *
031 * @author <a href="https://www.revetkn.com">Mark Allen</a>
032 */
033@FunctionalInterface
034public interface ResourceMethodParameterProvider {
035        /**
036         * For the given {@code request} and {@code resourceMethod}, vends the list of parameters to use when invoking the
037         * underlying Java method located at {@link ResourceMethod#getMethod()}.
038         * <p>
039         * The size of the returned list of parameters must exactly match the number of parameters required by the Java method signature.
040         *
041         * @param request        the HTTP request
042         * @param resourceMethod the <em>Resource Method</em> associated with the HTTP request
043         * @return the list of parameters to use when performing Java method invocation, or the empty list if no parameters are necessary
044         */
045        @NonNull
046        List<@Nullable Object> parameterValuesForResourceMethod(@NonNull Request request,
047                                                                                                                                                                                                                                        @NonNull ResourceMethod resourceMethod);
048}