server_migrate_1 x_to_2 x

• Introduction
• Changes that impact the existing code
• Other changes
  • Exception management:
    • For Queries and Mutations
    • For Subscription
  • Server endpoint
  • Support of WebSocket (mandatory for subscriptions)
• Other changes, for information
  • Schema files at runtime
  • Allow the RSocket protocol
  • Internal wiring of the Data Fetchers
• TODO : re-write this part
• Step to remove the DataFetchers
• Current step
• GraphQLServerMain
• CustomGraphQLController
• RuntimeWiring
• DataLoader
• TypeResolver

Work in progress (2.x is about to be released)

TODO - The plugin parameters are still the same as in the 1.x release. This will chang before the first official release, that is: the following parameters will be removed.

• copyRuntimeSources: will be forced to false
• generateBatchLoaderEnvironment: will be forced to true (server only)
• generateDeprecatedRequestResponse: will be forced to false (client only)
• separateUtilityClasses: will be forced to true (both client and server mode)
• skipGenerationIfSchemaHasNotChanged: will be forced to true (both client and server mode)

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.

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.