GraphQL Java Kickstart

Getting started

Wed, 07 Nov 2018 00:11:02 +0100

A working version of this example can be found at https://github.com/graphql-java-kickstart/samples/tree/master/servlet-hello-world.

Build with Gradle

First you set up a basic build script. You can use any build system you like, but the code you need to work with Gradle and Maven is included here.

Create a Gradle build file

Make sure mavenCentral is among your repositories. The example build script below uses org.gretty to provide a webserver to show a working example.

Getting started

Wed, 07 Nov 2018 00:11:02 +0100

This project requires at least the following version:

Java 17
Spring Boot 3.x.x (spring-boot-starter-web)

Quick start

To add graphql-spring-boot to your project and get started quickly, do the following.

Build with Gradle

Make sure mavenCentral is amongst your repositories:

repositories {
 mavenCentral()
}

Add the respective starter dependencies you want to use:

dependencies {
 implementation 'com.graphql-java-kickstart:graphql-spring-boot-starter:15.0.0'

 // testing facilities
 testImplementation 'com.graphql-java-kickstart:graphql-spring-boot-starter-test:15.0.0'
}

Build with Maven

Add the respective starter dependencies you want to use:

Getting started

Wed, 07 Nov 2018 00:11:02 +0100

A working Java Spring-Boot application is provided, based off the Star Wars API tests and test data. If you’re using Spring Boot, check out the graphql-spring-boot-starter!

A working Kotlin example can be found in the tests.

Quick start

To add graphql-java-tools to your project and get started quickly, do the following.

Build with Gradle

Make sure mavenCentral is amongst your repositories:

repositories {
 mavenCentral()
}

Add the graphql-java-tools dependency:

dependencies {
 compile 'com.graphql-java-kickstart:graphql-java-tools:13.0.3'
}

Build with Maven

Add the graphql-java-tools dependency:

Dataloaders

Wed, 07 Nov 2018 00:11:02 +0100

It is possible to create context, and consequently dataloaders, in both a request scope and a per query scope by customizing GraphQLContextBuilder and selecting the appropriate ContextSetting with the provided GraphQLConfiguration. A new DataLoaderRegistry should be created in each call to the GraphQLContextBuilder, and the servlet will call the builder at the appropriate times. For example:

public class CustomGraphQLContextBuilder implements GraphQLServletContextBuilder {

 private final DataLoader userDataLoader;
 
 public CustomGraphQLContextBuilder(DataLoader userDataLoader) {
 this.userDataLoader = userDataLoader;
 }
 
 public GraphQLContext build() {
 return new DefaultGraphQLContext();
 }
 
 public GraphQLContext build(HttpServletRequest httpServletRequest, HttpServletResponse httpServletResponse) {
 return DefaultGraphQLServletContext.createServletContext()
 .with(httpServletRequest)
 .with(httpServletResponse)
 .with(buildDataLoaderRegistry())
 .build();
 }
 
 public GraphQLContext build(Session session, HandshakeRequest handshakeRequest) {
 return DefaultGraphQLWebSocketContext.createWebSocketContext()
 .with(session)
 .with(handshakeRequest)
 .with(buildDataLoaderRegistry())
 .build();
 }
 
 private DataLoaderRegistry buildDataLoaderRegistry() {
 DataLoaderRegistry registry = new DataLoaderRegistry();
 registry.register("userDataLoader", userDataLoader);
 return registry;
 }
}

It is then possible to access the DataLoader in the resolvers by accessing the DataLoaderRegistry from context. For example:

Defining a schema

Wed, 07 Nov 2018 00:11:02 +0100

A GraphQL schema can be given either as raw strings:

// My application class
SchemaParser.newParser()
 .schemaString("Query { }")

or as files on the classpath:

// My application class
SchemaParser.newParser()
 .file("my-schema.graphqls")

// my-schema.graphqls
Query { }

Multiple sources will be concatenated together in the order given, allowing you to modularize your schema if desired.

Resolvers and Data Classes

GraphQL Java Tools maps fields on your GraphQL objects to methods and properties on your java objects. For most scalar fields, a POJO with fields and/or getter methods is enough to describe the data to GraphQL. More complex fields (like looking up another object) often need more complex methods with state not provided by the GraphQL context (repositories, connections, etc). GraphQL Java Tools uses the concept of “Data Classes” and “Resolvers” to account for both of these situations.

Servlet Listener

Fri, 15 May 2020 09:28:02 +0100

The GraphQL Servlet library allows you to add a Servlet Listener for listening to the GraphQL request. It provides hooks into the servlet request execution (success, error, and finally):

public class MyServlet extends GraphQLHttpServlet {

 @Override
 protected GraphQLConfiguration getConfiguration() {
 return GraphQLConfiguration.with(createSchema())
 .with(queryInvoker)
 .with(Arrays.asList(listener))
 .build();
 }
}

Instrumentation

The Servlet Listener listens to the servlet request, but not to the GraphQL query execution. If you want to listen to that you should use the Instrumentation provided by GraphQL Java. You can extend SimpleInstrumentation to quickly create a custom implementation and use it when creating the GraphQLConfiguration.

Schema parser options

Wed, 07 Nov 2018 00:11:02 +0100

For advanced use-cases, the schema parser can be tweaked to suit your needs. Use SchemaParserOptions.newBuilder() to build an options object to pass to the parser.

Options:

contextClass: If you use a custom context object to execute your queries, let the parser know about it so that it can add it to data fetchers as an argument.
Make sure to also provide your context instance to the execution input:
```
var executionInput = ExecutionInput.newExecutionInput()
 .query(query)
 .variables(variables)
 .graphQLContext(Map.of(CustomContext.class, context));
```
genericWrappers: Allows defining your own generic classes that should be unwrapped when matching Java types to GraphQL types. You must supply the class and the index (zero-indexed) of the wrapped generic type. For example: If you want to unwrap type argument T of Future<T>, you must pass Future.class and 0.

Relay

Wed, 07 Nov 2018 00:11:02 +0100

Relay requires quite some boilerplate type definitions to be defined. They are all the same apart from type of the node the Relay connection targets. This results in schemas with a lot of duplication, like the following:

type Query {
 users(first: Int, after: String): UserConnection
 organizations(first: Int, after: String): OrganizationConnection
}

type UserConnection {
 edges: [UserEdge]
 pageInfo: PageInfo
}

type UserEdge {
 cursor: String
 node: User
}

type PageInfo {
 hasPreviousPage: Boolean!
 hasNextPage: Boolean!
}

type User {
 id: ID!
 name: String
}

type OrganizationConnection {
 edges: [OrganizationEdge]
 pageInfo: PageInfo
}

type OrganizationEdge {
 cursor: String
 node: Organization
}

type Organization {
 id: ID!
}

Using the Type Definition Factory

In version 5.4 of graphql-java-tools the Type Definition Factory has been introduced. This has been added with this particular use case in mind, but can be used for any type of definition that you’d want to add dynamically instead of defining it statically in the SDL.

Type Definition Factory

Wed, 07 Nov 2018 00:11:02 +0100

The Type Definition Factory has been added with to be able to dynamically add type definitions to the schema instead of having to define them manually in the SDL. There are a couple of use cases where the types that have to be defined are very much alike and only certain parts are different. For example the connection and edge types used by Relay. Since generics isn’t supported in the definition language this type definition factory has been added.

Type Definition Factory

Wed, 07 Nov 2018 00:11:02 +0100

The Type Definition Factory has been added to allow to dynamically add type definitions to the schema instead of having to define them manually in the SDL. There are a couple of use cases where the types that have to be defined are very much alike and only certain parts are different. For example the connection and edge types used by Relay. Since generics aren’t supported in the definition language this type definition factory has been added.

Directives

Wed, 07 Nov 2018 00:11:02 +0100

See Schema Directives for a detailed explanation about directives including examples on how to define them in the SDL and to create the required classes.

To add your custom SchemaDirectiveWiring to graphql-spring-boot create a bean of type SchemaDirective to have it automatically passed along to the SchemaParser

SchemaDirective.create("uppercase", new UppercaseDirective())

Basic usage

Let’s say you defined a custom directive to make text uppercase in a resource schema.graphqls:

directive @uppercase on FIELD_DEFINITION

type Query {
 hello: String @uppercase
}

And the actual implementation is the following:

Directives

Wed, 07 Nov 2018 00:11:02 +0100

See Schema Directives for a detailed explanation about directives including examples on how to define them in the SDL and to create the required classes.

To add your custom SchemaDirectiveWiring to graphql-java-tools pass it along when creating the SchemaParser using

SchemaParser.newParser().directive("name", new MySchemaDirectiveWiring()).build()

Basic usage

Let’s say you defined a custom directive to make text uppercase in a resource schema.graphqls:

directive @uppercase on FIELD_DEFINITION

type Query {
 hello: String @uppercase
}

And the actual implementation is the following:

Embedded Editors

Mon, 17 May 2021 07:00:00 -0500

The following GraphQL Embedded Editors are bundled for convenience:

Altair
- Configuration Parameters
GraphQL Playground
- Configuration Parameters
GraphiQL
- Configuration Parameters
GraphQL Voyager
- Configuration Parameters

Altair

Altair becomes accessible at the root /altair if the graphql.altair.enabled property is true.

Note that GraphQL server must be available at /graphql/\* context to be discovered by Altair.

Configuration Parameters

Available Spring Boot configuration parameters (either application.yml or application.properties):

graphql:
 altair:
 enabled: true
 mapping: /altair
 subscriptions:
 timeout: 30
 reconnect: false
 static:
 base-path: /
 page-title: Altair
 cdn:
 enabled: false
 version: 4.0.2
 options:
 endpoint-url: /graphql
 subscriptions-endpoint: /subscriptions
 initial-settings:
 theme: dracula
 initial-headers:
 Authorization: "Bearer <your-token>"
 resources:
 initial-query: defaultQuery.graphql
 initial-variables: variables.graphql
 initial-pre-request-script: pre-request.graphql
 initial-post-request-script: post-request.graphql

GraphQL Playground

GraphQL Playground becomes accessible at root /playground (or as configured in graphql.playground.mapping) if the graphql.playground.enabled property is true.

OSGi

Fri, 15 May 2020 09:28:02 +0100

The OsgiGraphQLHttpServlet uses a “provider” model to supply the servlet with the required objects:

GraphQLQueryProvider: Provides query fields to the GraphQL schema.
GraphQLMutationProvider: Provides mutation fields to the GraphQL schema.
GraphQLTypesProvider: Provides type information to the GraphQL schema.
ExecutionStrategyProvider: Provides an execution strategy for running each query.
GraphQLContextBuilder: Builds a context for running each query.

Examples

You can now find some example on how to use graphql-java-servlet.

Requirements

The OSGi examples use Maven as a build tool because it requires plugins that are not (yet) available for Gradle. Therefore you will need Maven 3.2+.