graphql:graphql

True if the plugin is configured to add the Relay connection capabilities to the field marked by the @RelayConnection directive.

If so, the plugin reads the provided GraphQL schema file(s), and enriches them with the interfaces and types needed to respect the Relay Connection specification. The entry point for that is the @RelayConnection directive.

You'll find all the information on the plugin web site. Please check the server Relay capability page.

This parameter is used only when generateBatchMappingDataFetchers is set to true. It determines the return type of the data fetchers, as defined in the spring-graphql documentation.

The allowed values are (where K is the key type, that is: the parent object, and V is the value to be loaded in batch):

The default value is Flux<V>

For an easier use of this parameter, the comment of the generated data fetchers details the exact expected type.

Flag to enable (or not) the copy of the sources from the graphql-java-runtime library to target source code directory. That is: it allows to control whether the runtime code is embedded in the generated code or not.

Caution: the default value changed since the 2.0 version. In 1.x version, the default value is true. Since 2.0 version, the default value is false.

• If copyRuntimeSources=true: the runtime is copied along with the generated code. The project configuration (pom.xml or build.gradle) must contain the com.graphql-java-generator:graphql-java-dependencies dependency, with the same version as the GraphQL plugin
• If copyRuntimeSources=false: the runtime is NOT copied along with the generated code. The project configuration (pom.xml or build.gradle) must contain the com.graphql-java-generator:graphql-java-runtime dependency, with the same version as the GraphQL plugin

This parameter contains the list of custom scalars implementations. One such implementation must be provided for each custom scalar defined in the GraphQL implemented by the project for its GraphQL schema. It's a list, where the key is the scalar name, as defined in the GraphQL schema, and the value is the full class name of the implementation of graphql.schema.GraphQLScalarType.

This parameter is a list of customScalars. For each one, you must define the name, the javaType and exactly one of these fields: graphQLScalarTypeClass, graphQLScalarTypeStaticField or graphQLScalarTypeGetter.

Here is the detail:

• graphQLTypeName: The type name, as defined in the GraphQL schema, for instance Date
• javaType: The full class name for the java type that contains the data for this type, once in the Java code, for instance java.util.Date
• graphQLScalarTypeClass: The full class name for the graphql.schema.GraphQLScalarType that will manage this Custom Scalar. This class must be a subtype of graphql.schema.GraphQLScalarType. Bu the constructor of graphql.schema.GraphQLScalarType has been deprecated, so you'll find no sample for that in this project
• graphQLScalarTypeStaticField: The full class name followed by the static field name that contains the graphql.schema.GraphQLScalarType that will manage this Custom Scalar. For instance, the graphql-java package provides several custom scalars like graphql.Scalars.GraphQLLong. You can also use the graphql-java-extended-scalars project, that provides other custom scalars like graphql.scalars.ExtendedScalars.NonNegativeInt.
• graphQLScalarTypeGetter: The full class name followed by the static method name that returns the graphql.schema.GraphQLScalarType that will manage this Custom Scalar. For instance: org.mycompany.MyScalars.getGraphQLLong() or com.graphql_java_generator.customscalars.GraphQLScalarTypeDate. This call may contain parameters, provided that this a valid java command.

Please have a look at the allGraphQLCases (both client and server) samples for more information. The allGraphQLCases client pom is a good sample.

(only for server mode) Indicates if the plugin should generate add the org.dataloader.BatchLoaderEnvironment parameter to the batchLoader methods, in DataFetchersDelegate. This parameter allows to get the context of the Batch Loader, including the context associated to the id, when using the id has been added by the org.dataloader.DataLoader.load(java.lang.Object,java.lang.Object) method.

For instance, if you have the method below, for a field named oneWithIdSubType in a DataFetcherDelegate:

@Override
public CompletableFuture<AllFieldCasesWithIdSubtype> oneWithIdSubType(
		DataFetchingEnvironment dataFetchingEnvironment, DataLoader<UUID, AllFieldCasesWithIdSubtype> dataLoader,
		AllFieldCases source, Boolean uppercase) {
	return dataLoader.load(UUID.randomUUID());
}

then, in the AllFieldCasesWithIdSubtype DataFetcherDelegate, you can retrieve the uppercase this way:

@Override
public List<AllFieldCasesWithIdSubtype> batchLoader(List<UUID> keys, BatchLoaderEnvironment environment) {
	List<AllFieldCasesWithIdSubtype> list = new ArrayList<>(keys.size());
	for (UUID id : keys) {
		// Let's manage the uppercase parameter, that was associated with this key
		Boolean uppercase = (Boolean) environment.getKeyContexts().get(id);
		if (uppercase != null && uppercase) {
			item.setName(item.getName().toUpperCase());
		}

		// Do something with the id and the uppercase value
	}
	return list;
}

For more complex cases, you can store a java.util.Map with all the needed values, instead of just the parameter value.

The default value changed since 2.0 version: it is false in 1.x version, and true since the 2.0 version

If this parameter is set to true, the spring GraphQL controller methods will be annotated with the @BatchMapping (instead of the @SchemaMapping). This allows to manage the of the N+1 select problem: so this allows much better performances, by highly diminishing the number of executed requests (avoid to execute several times the same "sub-query")

• The @BatchMapping annotation may be applied to all data fetchers without argument(s) that return either a List, a Type, an Interface or an Union.
• The return type must be defined in the controller: it may not be `Object`, as spring-graphql builds the proper BatchLoader while loading the controllers, when the server starts. The return type for this method is managed by the batchMappingMethodReturnType plugin parameter
• DataLoader is managed transparently by spring (instead of having to declare it in the generated controller, and having it as a parameter in the generated data fetchers)
• The batch mapping is generalized on all data fetchers
• The DataFetchersDelegate method's signature changes
• The generateBatchLoaderEnvironment, generateDataFetcherForEveryFieldsWithArguments and generateDataLoaderForLists plugin parameters are ignored

A typical method signature for a data fetcher would be as below, where the return type is controller by the batchMappingMethodReturnType plugin parameter :

public Flux topics(//
		BatchLoaderEnvironment batchLoaderEnvironment, //
		GraphQLContext graphQLContext, //
		List
   boards);

  
 

Please note that the @BatchMapping annotation is a shortcut to avoid boilerplate code, for the most common cases. See this discussion for more information on this. For most complex cases, the use of a DataLoader is recommended by the spring-graphql case. And in these cases, the plugin will generate a method with the @SchemaMapping annotation

(only for server mode, since 2.5) Defines if a data fetcher is needed for every GraphQL field that has input argument, and add them in the generated POJOs. This allows a better compatibility with spring-graphql, and an easy access to the field's parameters.

With this argument to false, the data fetchers are generated only for field which type is a type (not a scalar or an enum), and for the query, mutation and subscription types.

With this argument to true, the data fetchers are generated for all GraphQL fields which type is a type (not a scalar or an enum) or that has one or arguments

This parameter is available since version 2.5. Its default value is false in 2.x versions for backward compatibility with existing implementations based on the plugin. But the recommended value is true.

(only for server mode) Defines how the methods in the data fetchers delegates are generated. The detailed information is available in the Wiki server page

When generateDataLoaderForLists is false (default mode), the data loaders are used only for fields that don't return a list. In other words, for fields which type is a sub-object with an id, two methods are generated: one which returns a java.util.concurrent.CompletableFuture, and one which returns a none java.util.concurrent.CompletableFuture result (that is used by the generated code only if no data loader is available).

When generateDataLoaderForLists is true, the above behavior is extended to fields that are a list.

Note: if set to true, this plugin parameter make the use of data loader mandatory for every field which type is a list of GraphQL objects, which have an id. This may not be suitable, for instance when your data is stored in a relational database, where you would need a first query to retrieve the ids and push them into the data loader, then another one to retrieve the associated values. If you want to use data loader for only some of particular fields, you should consider using the generateDataLoaderForLists. You'll find more information on the Wiki server page.

This parameter is available since version 1.18.4

(since 1.7.1 version) Default value is _true_ for 1.x version, and _false_ for version 2.0 and after.

If this parameter is set to true, the plugin generates a XxxxResponse class for each query/mutation/subscription, and (if separateUtilityClasses is true) Xxxx classes in the util subpackage. This allows to keep compatibility with code Developed with the 1.x versions of the plugin.

The recommended way to use the plugin is to directly use the Xxxx query/mutation/subscription executor classes, where Xxxx is the query/mutation/subscription name defined in the GraphQL schema. To do this, set this parameter to _false_, and use the plugin as described in the wiki client page.

(only for server mode) Indicates whether the plugin should generate the JPA annotations, for generated objects.

Note: if the generated code must be used with Spring 3, you must set the useJakartaEE9 plugin parameter to true.

Default value is false

This parameter marks a list of GraphQL mappings as ignored, so that they are not generated by the plugin. These ignored mappings can then be defined by the specific implementation.

The other way to it is to create a spring GraphQL Controller, that overrides the controller generated by the plugin. But this may lead to this error: Ambiguous mapping. Cannot map 'xxxController' method [...] to 'Type.field': there is already 'yyy' bean method [...] mapped.

The parameter may contain:

• The '*' character: this would mark all controllers and DataFetchersDeleagate to be ignored. That is: none would be generated, and it's up to the specific implementation to manage them. In this mode, you still benefit of the POJO generation, the type wiring, the custom scalars mapping...
• A list of:
• GraphQL type name: The full controller class for this type is ignored, and won't be generated
• GraphQL type's field name: The method in the controller of this type, for this field, is ignored, and won't be generated. The field must be written like this: {type name}.{field name}

The accepted separators for the values are: comma, space, carriage return, end of line, space, tabulation. At least one separator must exist between two values in the list. Here is a sample:

         Type1, Type2.field1
         	Type3
         	Type4.field2
         
 

For field mapping, there must be no separator other than '.' between the type name and the field name. For instance, the following type declaration are invalid: 'type .field', 'type. field'

To implement the ignored mappings, you'll have to follow the [spring-graphql documentation](https://docs.spring.io/spring-graphql/reference/controllers.html).

The javaTypeForIDType is the java class that is used in the generated code for GraphQL fields that are of the GraphQL ID type. The default value is java.util.UUID. Valid values are: java.lang.String, java.lang.Long and java.util.UUID.

This parameter is only valid for the server mode. When generating the client code, the ID is always generated as a String type, as recommended in the GraphQL doc.

In other words: when in server mode and javaTypeForIDType is not set, all GraphQL ID fields are UUID attributes in java. When in server mode and javaTypeForIDType is set to the X type, all GraphQL ID fields are X attributes in java.

Note: you can override this, by using the schema personalization capability. For more information, please have a look at the Schema Personalization doc page.

(only for server mode) A comma separated list of package names, without double quotes, that will also be parsed by Spring, to discover Spring beans, Spring repositories and JPA entities when the server starts. You should use this parameter only for packages that are not subpackage of the package defined in the _packageName_ parameter and not subpackage of com.graphql_java_generator

This allows for instance, to set packageName to your.app.package.graphql, and to define your Spring beans, like the DataFetcherDelegates or your Spring data repositories in any other folder, by setting for instance scanBasePackages to your.app.package.impl, your.app.package.graphql, or just your.app.package

The folder which contains the GraphQL schema file(s) , typically /src/main/resources of the current project. That's where the GraphQL schema(s) are expected to be: in this folder, or one of these subfolders. If the jsonSchemaFilename is set, then this parameter controls where this json schema file is.

Caution: this default value for this folder is /src/main/resources, for compatibility with first versions of this plugin. It's different from the spring-graphql default one, which is /src/main/resources/graphql

The pattern to find the graphql schema file(s). The default value is "/*.graphqls" meaning that the maven plugin will search all graphqls files in the "/src/main/resources" folder (please check also the schemaFileFolder plugin parameter).

You can put the star (*) joker in the filename, to retrieve several files at ones, for instance /myschema*.graphqls will retrieve the /src/main/resources/myschema.graphqls and /src/main/resources/myschema_extend.graphqls files.

schemaPersonalizationFile is the file name where the GraphQL maven plugin will find personalization that it must apply before generating the code. Since the 2.2 release, it is available for both client and server. Before, it applies to the server mode only.

This allows to:

• Add or modify fields
• Add interface and annotation to classes (GraphQL types, input types, interfaces, unions and enums) or fields.

See the doc on the project's wiki for more details.

Indicates whether the utility classes (that is: the classes that are not match an item in the GraphQL schema) are generated in the same package than the classes that matches the GraphQL schema.

The classes that map the GraphQL schema (type, input type, interfaces, unions...) are generated in the package defined in the packageName plugin parameter, then:

• If false (default for versions 1.x), the utility classes are generated in the the same package
• If true (default for version 2.0 and after), the utility classes are generated in the util subpackage of this package

This parameter is now deprecated: it's value used in the plugin is always true, that is: if the generated sources or resources are older than the GraphQL schema file(s), then there is no source or resource generation. In clear, the source and resource generation is executed only if the provided input (GraphQL schema...) has been updated since the last plugin execution.

Map of the code templates to be used: this allows to override the default templates, and control exactly what code is generated by the plugin.

You can override any of the Velocity templates of the project. The list of templates is defined in the enum CodeTemplate, that you can check here.

You can find a sample in the CustomTemplates client sample.

Important notice: Please note that the default templates may change in the future. And some of these modifications would need to be reported into the custom templates. We'll try to better expose a stable public API in the future.