From a66b49540bc79b1eea08333b02e5a48621a0881a Mon Sep 17 00:00:00 2001 From: Rossen Stoyanchev Date: Wed, 29 Sep 2021 18:25:24 +0100 Subject: [PATCH] Polishing docs and removing unused code --- .../src/docs/asciidoc/index.adoc | 5 +- .../data/method/annotation/Argument.java | 6 +- .../data/method/annotation/BatchMapping.java | 21 ++++--- .../data/method/annotation/QueryMapping.java | 2 +- .../data/method/annotation/SchemaMapping.java | 2 +- .../method/annotation/ValueConstants.java | 36 ----------- .../ArgumentMethodArgumentResolver.java | 1 - .../support/BatchLoaderHandlerMethod.java | 9 +-- ...inuationHandlerMethodArgumentResolver.java | 2 +- .../DataLoaderMethodArgumentResolver.java | 6 +- .../support/MissingArgumentException.java | 63 ------------------- .../support/SourceMethodArgumentResolver.java | 2 +- 12 files changed, 29 insertions(+), 126 deletions(-) delete mode 100644 spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/ValueConstants.java delete mode 100644 spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/support/MissingArgumentException.java diff --git a/spring-graphql-docs/src/docs/asciidoc/index.adoc b/spring-graphql-docs/src/docs/asciidoc/index.adoc index a434d4ba..ddc5dcf1 100644 --- a/spring-graphql-docs/src/docs/asciidoc/index.adoc +++ b/spring-graphql-docs/src/docs/asciidoc/index.adoc @@ -696,8 +696,9 @@ You can explicitly specify the argument name, for example `@Argument("bookInput" it not specified, it defaults to the method parameter name, but this requires the `-parameters` compiler flag with Java 8+ or debugging information from the compiler. -The "required" character of an `@Argument` or its default value is controlled at the schema -level. +The `@Argument` annotation does not have a "required" flag, nor the option to specify a +default value. Both of these can be specified at the GraphQL schema level and are enforced +by the GraphQL Engine. You can use `@Argument` on a `Map` argument, to obtain all argument values. The name attribute on `@Argument` must not be set. diff --git a/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/Argument.java b/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/Argument.java index 5690d67a..b68d5a44 100644 --- a/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/Argument.java +++ b/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/Argument.java @@ -31,9 +31,9 @@ import org.springframework.core.annotation.AliasFor; * and a parameter name is not specified, then the map parameter is populated * via {@link graphql.schema.DataFetchingEnvironment#getArguments()}. * - *

This annotation does not specify whether the input argument is required - * and if it should use a default value: this should be done at the schema - * in order to be enforced by the GraphQL engine itself. + *

Note that this annotation has neither a "required" flag nor the option to + * specify a default value, both of which can be specified at the GraphQL schema + * level and are enforced by the GraphQL Java engine. * * @author Rossen Stoyanchev * @since 1.0.0 diff --git a/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/BatchMapping.java b/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/BatchMapping.java index 4330104c..dfb85436 100644 --- a/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/BatchMapping.java +++ b/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/BatchMapping.java @@ -24,7 +24,7 @@ import java.lang.annotation.Target; import org.springframework.core.annotation.AliasFor; /** - * Annotation for handler methods that batch load field values, given a list + * Annotation for a handler method that batch loads field values, given a list * of source/parent values. For example: * * 

@@ -34,9 +34,10 @@ import org.springframework.core.annotation.AliasFor;
  * }
  *
* - *

The annotated method is registered as a batch loading function and along + *

The annotated method is registered as a batch loading function via + * {@link org.springframework.graphql.execution.BatchLoaderRegistry}, and along * with it, a {@link graphql.schema.DataFetcher} for the field is registered - * transparently that looks up the field through the registered + * transparently that looks up the field value through the registered * {@code DataLoader}. * *

Effectively, a shortcut for: @@ -46,7 +47,7 @@ import org.springframework.core.annotation.AliasFor; * public class BookController { * * public BookController(BatchLoaderRegistry registry) { - * registry.forTypePair(Long.class, Author.class).registerBatchLoader((ids, env) -> ...); + * registry.forTypePair(Long.class, Author.class).registerBatchLoader((ids, environment) -> ...); * } * * @SchemaMapping @@ -60,7 +61,7 @@ import org.springframework.core.annotation.AliasFor; * @author Rossen Stoyanchev * @since 1.0.0 */ -@Target({ElementType.TYPE, ElementType.METHOD}) +@Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) @Documented public @interface BatchMapping { @@ -79,12 +80,12 @@ public @interface BatchMapping { String value() default ""; /** - * Customizes the name of the parent/container type for the GraphQL field. - *

By default, if not specified, it is derived from the class name of the - * List of source/parent values injected into the handler method. - *

This value for this attribute can be initialized from a class-level + * Customizes the name of the source/parent type for the GraphQL field. + *

By default, if not specified, it is based on the simple class name of + * the List of source/parent values injected into the handler method. + *

The value for this attribute can also be inherited from a class-level * {@link SchemaMapping @SchemaMapping}. When used on both levels, the one - * on the method level overrides the one at the class level. + * here overrides the one at the class level. */ String typeName() default ""; diff --git a/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/QueryMapping.java b/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/QueryMapping.java index f5630ede..ef806c86 100644 --- a/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/QueryMapping.java +++ b/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/QueryMapping.java @@ -32,7 +32,7 @@ import org.springframework.core.annotation.AliasFor; * @author Rossen Stoyanchev * @since 1.0.0 */ -@Target(value = {ElementType.TYPE, ElementType.METHOD}) +@Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) @Documented @SchemaMapping(typeName = "Query") diff --git a/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/SchemaMapping.java b/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/SchemaMapping.java index c086111f..9f1042cf 100644 --- a/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/SchemaMapping.java +++ b/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/SchemaMapping.java @@ -52,7 +52,7 @@ public @interface SchemaMapping { String value() default ""; /** - * Customizes the name of the parent/container type for the GraphQL field. + * Customizes the name of the source/parent type for the GraphQL field. *

By default, if not specified, it is derived from the class name of a * {@link DataFetchingEnvironment#getSource() source} argument injected into * the handler method. diff --git a/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/ValueConstants.java b/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/ValueConstants.java deleted file mode 100644 index 60801915..00000000 --- a/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/ValueConstants.java +++ /dev/null @@ -1,36 +0,0 @@ -/* - * Copyright 2002-2021 the original author or authors. - * - * Licensed 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.springframework.graphql.data.method.annotation; - -/** - * Common annotation value constants. - * - * @author Rossen Stoyanchev - * @since 1.0.0 - */ -public interface ValueConstants { - - /** - * Constant defining a value for no default - as a replacement for {@code null} which - * we cannot use in annotation attributes. - *

This is an artificial, fixed value of 16 unicode characters, with its sole purpose - * being to never match a user-declared value. - * @see Argument#defaultValue() - */ - String DEFAULT_NONE = "\n\t\t\n\t\t\n\uE000\uE001\uE002\n\t\t\t\t\n"; - -} diff --git a/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/support/ArgumentMethodArgumentResolver.java b/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/support/ArgumentMethodArgumentResolver.java index 617e19b2..82b0c31c 100644 --- a/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/support/ArgumentMethodArgumentResolver.java +++ b/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/support/ArgumentMethodArgumentResolver.java @@ -26,7 +26,6 @@ import org.springframework.core.MethodParameter; import org.springframework.core.convert.TypeDescriptor; import org.springframework.graphql.data.method.HandlerMethodArgumentResolver; import org.springframework.graphql.data.method.annotation.Argument; -import org.springframework.graphql.data.method.annotation.ValueConstants; import org.springframework.util.Assert; import org.springframework.util.StringUtils; import org.springframework.validation.DataBinder; diff --git a/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/support/BatchLoaderHandlerMethod.java b/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/support/BatchLoaderHandlerMethod.java index bcc1d74e..17f6f457 100644 --- a/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/support/BatchLoaderHandlerMethod.java +++ b/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/support/BatchLoaderHandlerMethod.java @@ -30,9 +30,10 @@ import org.springframework.lang.Nullable; import org.springframework.util.Assert; /** - * An extension of {@link HandlerMethod} for annotated handler methods adapted - * to a batch loader function with a list of values and {@link BatchLoaderEnvironment} - * as their input. + * An extension of {@link HandlerMethod} for annotated handler methods adapted to + * {@link org.dataloader.BatchLoaderWithContext} or + * {@link org.dataloader.MappedBatchLoaderWithContext} with the list of keys and + * {@link BatchLoaderEnvironment} as their input. * * @author Rossen Stoyanchev * @since 1.0.0 @@ -47,7 +48,7 @@ public class BatchLoaderHandlerMethod extends InvocableHandlerMethodSupport { /** * Invoke the underlying batch loading method, resolving its arguments from - * the given keys for batch loading and the {@link BatchLoaderEnvironment}. + * the given keys and the {@link BatchLoaderEnvironment}. * * @param keys the batch loading keys * @param environment the environment available to batch loaders diff --git a/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/support/ContinuationHandlerMethodArgumentResolver.java b/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/support/ContinuationHandlerMethodArgumentResolver.java index 34ec001b..51613f45 100644 --- a/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/support/ContinuationHandlerMethodArgumentResolver.java +++ b/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/support/ContinuationHandlerMethodArgumentResolver.java @@ -33,7 +33,7 @@ public class ContinuationHandlerMethodArgumentResolver implements HandlerMethodA } @Override - public Object resolveArgument(MethodParameter parameter, DataFetchingEnvironment environment) throws Exception { + public Object resolveArgument(MethodParameter parameter, DataFetchingEnvironment environment) { return null; } diff --git a/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/support/DataLoaderMethodArgumentResolver.java b/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/support/DataLoaderMethodArgumentResolver.java index e08fa0e0..a23f5aa6 100644 --- a/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/support/DataLoaderMethodArgumentResolver.java +++ b/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/support/DataLoaderMethodArgumentResolver.java @@ -28,10 +28,10 @@ import org.springframework.lang.Nullable; import org.springframework.util.Assert; /** - * Resolver that retrieves arguments of type {@link DataLoader} from the - * {@link DataFetchingEnvironment}. + * Resolver for a {@link DataLoader} obtained via + * {@link DataFetchingEnvironment#getDataLoader(String)}. * - *

The {@code DataLoader} is looked up by deriving the key using one of the following: + *

The {@code DataLoader} key is based on one of the following: *

    *
  1. The full name of the value type from the DataLoader generic types.
    2. *
  2. The method parameter name.
    3. diff --git a/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/support/MissingArgumentException.java b/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/support/MissingArgumentException.java deleted file mode 100644 index f077b1a5..00000000 --- a/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/support/MissingArgumentException.java +++ /dev/null @@ -1,63 +0,0 @@ -/* - * Copyright 2002-2021 the original author or authors. - * - * Licensed 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.springframework.graphql.data.method.annotation.support; - -import org.springframework.core.MethodParameter; -import org.springframework.core.NestedRuntimeException; - -/** - * Indicates that an input argument value in the method parameters of an - * annotated DataFetcher method is not present. - * - * @author Rossen Stoyanchev - * @since 1.0.0 - */ -@SuppressWarnings("serial") -public class MissingArgumentException extends NestedRuntimeException { - - private final String argumentName; - - private final MethodParameter parameter; - - - public MissingArgumentException(String argumentName, MethodParameter parameter) { - super(""); - this.argumentName = argumentName; - this.parameter = parameter; - } - - - /** - * Return the expected name of the input argument. - */ - public String getArgumentName() { - return this.argumentName; - } - - /** - * Return the method parameter bound to the input argument. - */ - public MethodParameter getParameter() { - return this.parameter; - } - - @Override - public String getMessage() { - return "Required argument '" + this.argumentName +"' for method parameter type " + - this.parameter.getNestedParameterType().getSimpleName() + " is not present"; - } - -} diff --git a/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/support/SourceMethodArgumentResolver.java b/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/support/SourceMethodArgumentResolver.java index d154995b..b3cea6d6 100644 --- a/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/support/SourceMethodArgumentResolver.java +++ b/spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/support/SourceMethodArgumentResolver.java @@ -25,7 +25,7 @@ import org.springframework.graphql.data.method.HandlerMethodArgumentResolver; import org.springframework.util.Assert; /** - * Resolver for parent/container of a field, obtained via + * Resolver for the source/parent of a field, obtained via * {@link DataFetchingEnvironment#getSource()}. * *

    This resolver supports any non-simple value type, also excluding arrays