feat: open FunctionDataFetcher methods for extension (#582)

Open the internal methods to the protected scope so that we can more easily override specific methods to provide more features. Internally to Expedia Group we have the need to provide a CustomFunctionDataFetcher that overrides the get method. However we don't want to have to reimplement all the other methods as well that covert the classes and parse the names. Right now we are actually missing out on using the new feature to use List over array for input types. This could be fixed internally but it is already done in open source so we would like to take advantage of that

Author: smyrick

graphql-kotlin-schema-generator/src/main/kotlin/com/expediagroup/graphql/execution/FunctionDataFetcher.kt

@@ -24,11 +24,14 @@ import com.fasterxml.jackson.databind.ObjectMapper
 import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper
 import graphql.schema.DataFetcher
 import graphql.schema.DataFetchingEnvironment
+import kotlinx.coroutines.CoroutineStart
 import kotlinx.coroutines.GlobalScope
 import kotlinx.coroutines.async
 import kotlinx.coroutines.future.asCompletableFuture
 import java.lang.reflect.InvocationTargetException
 import java.util.concurrent.CompletableFuture
+import kotlin.coroutines.CoroutineContext
+import kotlin.coroutines.EmptyCoroutineContext
 import kotlin.reflect.KFunction
 import kotlin.reflect.KParameter
 import kotlin.reflect.full.callSuspend
@@ -42,19 +45,21 @@ import kotlin.reflect.full.valueParameters
  * @param fn The Kotlin function being invoked
  * @param objectMapper Jackson ObjectMapper that will be used to deserialize environment arguments to the expected function arguments
  */
+@Suppress("Detekt.SpreadOperator")
 open class FunctionDataFetcher(
     private val target: Any?,
     private val fn: KFunction<*>,
     private val objectMapper: ObjectMapper = jacksonObjectMapper()
 ) : DataFetcher<Any> {
 
+    /**
+     * Invoke a suspend function or blocking function, passing in the [target] if not null or default to using the source from the environment.
+     */
     override fun get(environment: DataFetchingEnvironment): Any? {
         val instance = target ?: environment.getSource<Any>()
 
         return instance?.let {
-            val parameterValues = fn.valueParameters
-                .map { param -> mapParameterToValue(param, environment) }
-                .toTypedArray()
+            val parameterValues = getParameterValues(fn, environment)
 
             if (fn.isSuspend) {
                 runSuspendingFunction(it, parameterValues)
@@ -64,36 +69,70 @@ open class FunctionDataFetcher(
         }
     }
 
-    private fun mapParameterToValue(param: KParameter, environment: DataFetchingEnvironment): Any? =
+    /**
+     * Iterate over all the function parameters and map them to the proper input values from the environment
+     */
+    protected open fun getParameterValues(fn: KFunction<*>, environment: DataFetchingEnvironment): Array<Any?> = fn.valueParameters
+        .map { param -> mapParameterToValue(param, environment) }
+        .toTypedArray()
+
+    /**
+     * Retreives the provided parameter value in the operation input to pass to the function to execute.
+     * If the parameter is of a special type then we do not read the input and instead just pass on that value.
+     *
+     * The special values include:
+     *   - If the parameter is annotated with [com.expediagroup.graphql.annotations.GraphQLContext],
+     *     then return the environment context
+     *
+     *   - The entire environment is returned if the parameter is of type [DataFetchingEnvironment]
+     */
+    protected open fun mapParameterToValue(param: KParameter, environment: DataFetchingEnvironment): Any? =
         when {
             param.isGraphQLContext() -> environment.getContext()
             param.isDataFetchingEnvironment() -> environment
             else -> convertParameterValue(param, environment)
         }
 
-    private fun convertParameterValue(param: KParameter, environment: DataFetchingEnvironment): Any? {
+    /**
+     * Called to convert the generic input object to the parameter class.
+     *
+     * This is currently achieved by using a Jackson [ObjectMapper].
+     */
+    protected open fun convertParameterValue(param: KParameter, environment: DataFetchingEnvironment): Any? {
         val name = param.getName()
         val klazz = param.javaTypeClass()
         val argument = environment.arguments[name]
 
         return objectMapper.convertValue(argument, klazz)
     }
 
-    @Suppress("Detekt.SpreadOperator")
-    private fun runSuspendingFunction(it: Any, parameterValues: Array<Any?>): CompletableFuture<Any?> {
-        return GlobalScope.async {
+    /**
+     * Once all parameters values are properly converted, this function will be called to run a suspendable function.
+     * If you need to override the exception handling you can override the entire method.
+     * You can also call it from [get] with different values to override the default corotuine context or start parameter.
+     */
+    protected open fun runSuspendingFunction(
+        instance: Any,
+        parameterValues: Array<Any?>,
+        coroutineContext: CoroutineContext = EmptyCoroutineContext,
+        coroutineStart: CoroutineStart = CoroutineStart.DEFAULT
+    ): CompletableFuture<Any?> {
+        return GlobalScope.async(context = coroutineContext, start = coroutineStart) {
             try {
-                fn.callSuspend(it, *parameterValues)
+                fn.callSuspend(instance, *parameterValues)
             } catch (exception: InvocationTargetException) {
                 throw exception.cause ?: exception
             }
         }.asCompletableFuture()
     }
 
-    @Suppress("Detekt.SpreadOperator")
-    private fun runBlockingFunction(it: Any, parameterValues: Array<Any?>): Any? {
+    /**
+     * Once all parameters values are properly converted, this function will be called to run a simple blocking function.
+     * If you need to override the exception handling you can override this method.
+     */
+    protected open fun runBlockingFunction(instance: Any, parameterValues: Array<Any?>): Any? {
         try {
-            return fn.call(it, *parameterValues)
+            return fn.call(instance, *parameterValues)
         } catch (exception: InvocationTargetException) {
             throw exception.cause ?: exception
         }