server_migrate_1 x_to_2 x

Introduction
Changes that may impact the existing implementations
Other changes, for information

Work in progress (2.x is about to be released) TODO : Document that the graphql goal is not valid any more

Introduction

This page describe how to migrate a server implementation from a 1.x version to the last 2.x version.

If you're looking for a migration of the client implementation, please check the Client migration from 1.x to 2.x

The 2.x version is based on spring-graphql. Spring and spring-graphql are responsible for the whole transport part. The first versions are a mostly a port to use spring-graphql, with the lower impact possible on your exiting code.

Changes that may impact the existing implementations

A word on Spring dependencies

As the generated code is based on spring-graphql, spring dependencies are mandatory. spring-graphql doesn't choose between spring-mvc and spring-WebFlux. But the implementation that is done, based on spring-graphql, must choose between these two.

The generated code is based on Spring mvc.

As a consequence, in 2.x, the following dependencies are not needed by the generated code:

activation and spring-boot-starter: they are no more directly needd.
graphql-java-spring-mvc (the applications are now web flux apps)
spring-boot-starter-websocket (the Web Socket protocol is managed directly by spring-boot-starter-graphql)

Compatibility with Spring 3

The generated code is compatible with Spring 3. If you use the generateJPAAnnotation plugin parameter with Spring 3, you must set the useJakartaEE9 plugin parameter to true.

TODO : Document this in the Gradle doc for the generateJPAAnnotation plugin parameter.

Mandatory values for these plugin parameters: copyRuntimeSources, generateBatchLoaderEnvironment, generateDeprecatedRequestResponse and skipGenerationIfSchemaHasNotChanged

These parameters must now be unset from your configuration, or have these versions (which is there new default value):

copyRuntimeSources: will be forced to false (it must be done manually with 2.0RC1, if you're using Spring Boot 3)
generateBatchLoaderEnvironment: will be forced to true (server only)
generateDeprecatedRequestResponse: will be forced to false (client only)
skipGenerationIfSchemaHasNotChanged: will be forced to true (both client and server mode)

A build error will be thrown, if it's not the case.

separateUtilityClasses default value is now true

This parameter separates the utility classes generates by the plugin, from the generated classes that match the GraphQL schema (POJO...). This allows a better code structure, and may avoid some class name conflict. But changing this may have impact on existing code.

So, in 2.x versions:

Its default value changed from false to true
It is recommended to accept this default value, and adapt your code, as this separates the generated code that maps the GraphQL schema from the utility code that helps to start the server or execute the requests.
You can define its value to false, to avoid impact on your code.

Change your plugin from `dependencies` to `runtime`

A note about the copyRuntimeSources plugin parameter. If its previous value was unset, or set to true, then you must change your project dependency from dependencies to runtime. That is: change graphql-java-server-dependencies:pom (or graphql-java-client-dependencies:pom) to graphql-java-server-runtime:jar (or graphql-java-server-runtime:jar).

For instance, if you're using the plugin for a server, you must change:

		<dependency>
			<groupId>com.graphql-java-generator</groupId>
			<artifactId>graphql-java-server-dependencies</artifactId>
			<version>Plugin's version</version>
			<type>pom</type>
		</dependency>

to this:

		<dependency>
			<groupId>com.graphql-java-generator</groupId>
			<artifactId>graphql-java-server-runtime</artifactId>
			<version>Plugin's version</version>
		</dependency>

That is: change dependencies to runtime, and remove <type>pom</type>.

For Gradle, if you're using the plugin for a server, you must change:

    implementation "com.graphql-java-generator:graphql-java-server-dependencies:${project.pluginRuntimeVersion}"

to this:

    implementation "com.graphql-java-generator:graphql-java-server-runtime:${project.pluginRuntimeVersion}"

Gradle plugin

Change of the id plugin

The id changed from com.graphql_java_generator.graphql-gradle-plugin to com.graphql-java-generator.graphql-gradle-plugin

So the plugins section of the build.gradle is now:


plugins {
	// Starting from 2.0RC1, the top level domain changed from "com.graphql_java_generator" to "com.graphql-java-generator"
	id "com.graphql-java-generator.graphql-gradle-plugin" version "${graphQLPluginVersion}"
...
}

Add the generated resources

To run the project from your IDE, you must add the generated source folder and (which is new to 2.x version) the generated resources folder, like this:

sourceSets.main.java.srcDirs += '/build/generated/sources/graphqlGradlePlugin'
sourceSets.main.resources.srcDirs += '/build/generated/resources/graphqlGradlePlugin'

Local path of the server endpoint

In 1.x versions, the plugin allows to define the GraphQL endpoint's path with the graphql.url entry in the Spring configuration file (application.yml or application.properties) For servers only, in 2.x releases, this configuration is manager by spring. So the relevant configuration entry becomes spring.graphql.path in the Spring configuration file. For instance, for an application.properties file:

spring.graphql.path=/another-graphql-endpoint-path

In both 1.x and 2.x releases, the default value is /graphql

Exception management:

For Queries and Mutations

Like stated in the spring-graphql project, you can register a DataFetcherExceptionResolverAdapter that allows proper Exception management in your GraphQL server. There is a sample in the provided graphql-maven-plugin-samples-allGraphQLCases-server sample module. You just have to create a subclass of DataFetcherExceptionResolverAdapter, and override one of the resolveToSingleError or resolveToMultipleErrors methods.

Don't forget to add the @Component annotation, to register it.

For Subscription

It is undocumented, but the same mecanism exists for subscriptions exceptions. The class to override is SubscriptionExceptionResolverAdapter.

Support of WebSocket (mandatory for subscriptions)

The web socket transport is mandatory for subscription. To allow it, a line like this must be added in the application.properties (or application.yml ) file:

spring.graphql.websocket.path=/graphql

For spring-mvc, you also need add this dependency to your pom or gradle file:

		<!-- Mandatory to enable Web Sockets for Spring-mvc application (mandatory for subscription) -->
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-websocket</artifactId>
		</dependency>

Other changes, for information

Schema files at runtime

The schema files are copied to the default spring-graphql folder (that is: the ./graphql folder in the classpath), as this is the default path wher spring-graphql looks for the GraphQL schema file.

Allow the RSocket protocol

RSocket is also supported (see the spring-graphql doc for more information on how to do this)

Internal wiring of the Data Fetchers

The main change between the original graphql-java implementation and the Spring logic is the way to wire the Data Fetchers to the GraphQL engine.

In 1.x branch (with graphql-java), this was done in the generated GraphQLWiring class. It used to wire the code for custom scalars and all GraphQL type, unions... Then, the GraphQLDataFetchers class would wire each DataFetcherDelegateXxxx method to the relevant non-scalar field.
spring-graphql uses a different logic: * The GraphQLWiring spring component still exists. But it only wires the custom scalar implementations. The custom scalars to use are declared in the plugin configuration, that in the pom.xml or build.gradle file, like in 1.x releases. * The Controllers: GraphQL web applications must declare a Controller for each GraphQL object, union... This is done by classes XxxxController that are generated by the plugin. These Controllers are responsible for managing each non-scalar field. * To keep compatibility with code written for 1.x releases of the plugin, the plugin generates these XxxxController classes. They are responsible for calling the DataFetchersDelegateXxxx components (including the BatchLoaders), and then reuse the code written for the 1.x release * It is planned to be able to override the default generated Controllers

Overriding of `GraphQLDataFetchers`

In 2.x, it is no more possible to override the GraphQLDataFetchers spring component.

With spring-graphql, the wiring between the GraphQL requests and the server code is done in the Spring Controllers. It is planned to be able to override theses Controllers.

Manage exceptions `DataFetcherExceptionResolver`

It is possible to define a DataFetcherExceptionResolver. It is a custom Spring component that allows to manage the Exceptions thrown by the application, and define which ones must be sent as GraphQL Errors in the GraphQL response. The default behavior is to mask them into a generic server error.

You'll find a sample in the graphql-maven-plugin-samples-allGraphQLCases-server module of the 2.x branch. The org.allGraphQLCases.server.config.MyDataFetcherExceptionResolverAdapter checks if the thrown exception is an instance of GraphQlException, that is an Exception defined in this project. If it is the case, then it either maps to a new GraphQLError, or to the actual thrown exception (that implements GraphQLError).

GraphiQL

GraphiQL is available in spring-graphql. It is inactive by default.

It can be enabled with the spring.graphql.graphiql.enabled property, to define in the spring configuration file (application.properties or application.yml). It is then available at this path: /graphiql.

So there is no more need of the com.graphql-java-kickstart:graphiql-spring-boot-starter dependency.

Give access to the GraphQL schema

The spring.graphql.schema.printer.enabled property allows to expose the schema file in text format at /graphql/schema, to define in the spring configuration file (application.properties or application.yml).

Batch Loader / DataLoader

The Batch Loader is the capacity to use that is a very important optimization, on server side. You'll find the details in the java dataloader github page and in the graphql-java site.

The plugin doc for this subject is available in this wiki. Whether you use the 1.x and 2.x version of the plugin, your code implementation is the same.

What's change here is the way the plugin wires the Batch Loader method. With spring-graphql, the Batch Loader method are registered in a Spring BatchLoaderRegistry, within the constructor of the generated Controller, when needed. You'll find samples of that in the code generated for the graphql-maven-plugin-samples-Forum-server sample, for instance the TopicController.