client_migrate_1 x_to_2 x

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

TODO : update the OAuth document (no more need of the ServerOAuth2AuthorizedClientExchangeFilterFunction)

Introduction

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

If you're looking for a migration of the server implementation, please check the Server 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 allows to easily move from 1.x to 2.x versions.

Main changes

Basic configuration (GraphQL schema, server url...)

(unchanged) The schema file is searched at the

TODO schema file

The

• In 1.x releases of the plugin the GraphQL endpoint's path is configured by the graphql.url entry in the Spring configuration file (application.yml or application.properties)
  • [for servers only] In the 2.x releases, this configuration is manager by spring. So the relevant configuration entry is spring.graphql.path in the Spring configuration file. Its default value is /graphql
  • [for client only] As there seems to be no way to define two GraphQL server urls in Spring GraphQL yet, the configuration entry remains graphql.endpointXXXXXX.url, where XXXXXX is the suffix defined in your pom.xml or gradle.plugin (it may be undefined, and is then empty)
  • Note: take care that Spring's properties ends with path, whereas the client is an url.
• Exception management for Subscription
  • It is slightly different, as connection errors are now received by the callback, as the IO are now non blocking.

Spring GraphQlClient

Behind the query, mutation and subscription executors that are generated by the plugin, all requests are actually executed by a Spring GraphQlClient bean. There generated autoconfiguration class contains one or two such beans:

• A bean named httpGraphQlClient that is used to execute queries and mutations.
  • The beans uses the generated Spring WebClient bean to execute the requests over http.
• A bean named webSocketGraphQlClient (only if subscriptions are defined in the GraphQL schema), that is used to execute subscriptions

Like all the beans defined in the generated Spring auto configuration class, these beans can be overriden in your own Spring configuration. You'll just have to create a bean of the same name and type, and mark is as @Primary (caution: the generated autoconfiguration class MUST NOT be scanned by your Spring configuration, otherwise it becomes a standard Configuration class, and the @Primary annotation won't work). This allows to, for instance:

• Define the CodecCustomizer
• Provide your own HttpClient
• Add an ExchangeFilterFunction, like the ServerOAuth2AuthorizedClientExchangeFilterFunction to manage OAuth on websocket for subscriptions (see below)

Support removed for javax.ws.rs.client.Client

The javax.ws.rs.client.Client is no more accepted. The Spring stack must be used instead.

OAuth

OAuth is now supported by the standard Spring Boot parameters.

@SpringBootApplication annotation (and removal of GraphQLConfiguration)

The GraphQLConfiguration class has been removed. It was used to manage GraphQL configuration for non Spring apps based on the Jersey http client. The support for these apps has been removed, as the generated code is based on Spring. Non-spring apps are still supported, provided that they are encapsulated in a Spring app, like documented in the non Spring app page.

An impact is the use of the @SpringBootApplication annotation, on the main app class. The GraphqlClientUtils should be used instead, along with the QueryExecutor that must be loaded as Spring Bean, like this:

@SpringBootApplication(scanBasePackageClasses = { SpringMain.class, GraphqlClientUtils.class, QueryExecutor.class })
public class SpringMain {
	... Do something that uses GraphQL
}

How to get the query, mutation and subscription executors

The generated Executors are Spring beans, and should now be retrieved only as Spring bean, like this:

@Component
public class MyComponent {

	@Autowired
	QueryExecutor queryExecutor;

	public void doSomething(){
		List<Character> withoutParameters() = queryExecutor.withoutParameters("{appearsIn name }");
		...
	}
}

The GraphQLRequest class

It is used to execute full requests. It is now suffixed by the schema suffix defined in the springBeanSuffix defined in the plugin configuration, which is an empty string by default.

TODO finish here

Sample of the ServerOAuth2AuthorizedClientExchangeFilterFunction

For instance:

	// AllGraphQLCases is the value of the springBeanSuffix plugin parameter
	// If you attack only one GraphQL server, this parameter may remain unset (that is: an empty string)
	@Bean
	@Primary
	ServerOAuth2AuthorizedClientExchangeFilterFunction serverOAuth2AuthorizedClientExchangeFilterFunctionAllGraphQLCases(
			ReactiveClientRegistrationRepository clientRegistrations) {
		ServerOAuth2AuthorizedClientExchangeFilterFunction oauth = new ServerOAuth2AuthorizedClientExchangeFilterFunction(
				clientRegistrations, new UnAuthenticatedServerOAuth2AuthorizedClientRepository());
		oauth.setDefaultClientRegistrationId("provider_test");
		return oauth;
	}

	@Bean
	@Primary
	public WebClient webClientAllGraphQLCases(String graphqlEndpointAl	lGraphQLCases, //
			CodecCustomizer defaultCodecCustomizer, //
			@Autowired(required = false) @Qualifier("httpClientAllGraphQLCases") HttpClient httpClientAllGraphQLCases,
			@Autowired(required = false) @Qualifier("serverOAuth2AuthorizedClientExchangeFilterFunctionAllGraphQLCases") ServerOAuth2AuthorizedClientExchangeFilterFunction serverOAuth2AuthorizedClientExchangeFilterFunctionAllGraphQLCases) {
		return WebClient.builder()//
				.baseUrl(graphqlEndpointAllGraphQLCases)//
				.defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)
				.defaultUriVariables(Collections.singletonMap("url", graphqlEndpointAllGraphQLCases))
				.filter(serverOAuth2AuthorizedClientExchangeFilterFunctionAllGraphQLCases)//
				.build();
	}

Query and Mutation

• The GraphQLRequestExecutionException has been updated. It now contains a getErrors() method, that allows to retrieve the list of errors returned by the GraphQL server.
• Protocol choice for GraphQL queries and mutations: the new queryMutationExecutionProtocol plugin parameter allows to choose between http (default) and webSocket. s

Subscription

The SubscriptionClient now contains only the unsubscribe() method. The getSession() (that allows to retrieve the WebSocketSession has been removed, as all the web socket management is now done by spring-graphql)

The SubscriptionCallback interface is unchanged. But its onError(Throwable) method is now called with a GraphQLRequestExecutionException: its getErrors() method allows to retrieve the list of errors returned by the GraphQL server.