Package graphql

Class GraphQL

java.lang.Object

graphql.GraphQL

@PublicApi
@NullMarked
public class GraphQL
extends Object

This class is where all graphql-java query execution begins. It combines the objects that are needed to make a successful graphql query, with the most important being the schema and the execution strategy

Building this object is very cheap and can be done on each execution if necessary. Building the schema is often not as cheap, especially if it's parsed from graphql IDL schema format via SchemaParser.

The data for a query is returned via ExecutionResult.getData() and any errors encountered as placed in ExecutionResult.getErrors().

Runtime Exceptions

Runtime exceptions can be thrown by the graphql engine if certain situations are encountered. These are not errors in execution but rather totally unacceptable conditions in which to execute a graphql query.

• CoercingSerializeException - is thrown when a value cannot be serialised by a Scalar type, for example a String value being coerced as an Int.
• UnresolvedTypeException - is thrown if a TypeResolver fails to provide a concrete object type given an interface or union type.
• InvalidSchemaException - is thrown if the schema is not valid when built via GraphQLSchema.Builder.build()
• GraphQLException - is thrown as a general purpose runtime exception, for example if the code cant access a named field when examining a POJO.
• AssertException - is thrown as a low level code assertion exception for truly unexpected code conditions

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	GraphQL.Builder

Method Summary

Modifier and Type	Method	Description
ExecutionResult	execute(ExecutionInput executionInput)	Executes the graphql query using the provided input object
ExecutionResult	execute(ExecutionInput.Builder executionInputBuilder)	Executes the graphql query using the provided input object builder
ExecutionResult	execute(String query)	Executes the specified graphql query/mutation/subscription
ExecutionResult	execute(UnaryOperator<ExecutionInput.Builder> builderFunction)	Executes the graphql query using calling the builder function and giving it a new builder.
CompletableFuture<ExecutionResult>	executeAsync(ExecutionInput executionInput)	Executes the graphql query using the provided input object
CompletableFuture<ExecutionResult>	executeAsync(ExecutionInput.Builder executionInputBuilder)	Executes the graphql query using the provided input object builder
CompletableFuture<ExecutionResult>	executeAsync(UnaryOperator<ExecutionInput.Builder> builderFunction)	Executes the graphql query using the provided input object builder
GraphQLSchema	getGraphQLSchema()
ExecutionIdProvider	getIdProvider()
Instrumentation	getInstrumentation()
ExecutionStrategy	getMutationStrategy()
PreparsedDocumentProvider	getPreparsedDocumentProvider()
ExecutionStrategy	getQueryStrategy()
ExecutionStrategy	getSubscriptionStrategy()
ValueUnboxer	getValueUnboxer()
boolean	isDoNotAutomaticallyDispatchDataLoader()
static GraphQL.Builder	newGraphQL(GraphQLSchema graphQLSchema)	Helps you build a GraphQL object ready to execute queries
GraphQL	transform(Consumer<GraphQL.Builder> builderConsumer)	This helps you transform the current GraphQL object into another one by starting a builder with all the current values and allows you to transform it how you want.
static GraphQLUnusualConfiguration	unusualConfiguration()	This allows you to control "unusual" aspects of the GraphQL system including some JVM wide settings
static GraphQLUnusualConfiguration.GraphQLContextConfiguration	unusualConfiguration(ExecutionInput executionInput)	This allows you to control "unusual" per execution aspects of the GraphQL system
static GraphQLUnusualConfiguration.GraphQLContextConfiguration	unusualConfiguration(ExecutionInput.Builder executionInputBuilder)	This allows you to control "unusual" per execution aspects of the GraphQL system
static GraphQLUnusualConfiguration.GraphQLContextConfiguration	unusualConfiguration(GraphQLContext graphQLContext)	This allows you to control "unusual" per execution aspects of the GraphQL system
static GraphQLUnusualConfiguration.GraphQLContextConfiguration	unusualConfiguration(GraphQLContext.Builder graphQLContextBuilder)	This allows you to control "unusual" per execution aspects of the GraphQL system

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

unusualConfiguration

public static GraphQLUnusualConfiguration unusualConfiguration()

This allows you to control "unusual" aspects of the GraphQL system including some JVM wide settings

This is named unusual because in general we don't expect you to have to make ths configuration by default, but you can opt into certain features or disable them if you want to.

Returns:

a GraphQLUnusualConfiguration object

unusualConfiguration

public static GraphQLUnusualConfiguration.GraphQLContextConfiguration unusualConfiguration(ExecutionInput executionInput)

This allows you to control "unusual" per execution aspects of the GraphQL system

This is named unusual because in general we don't expect you to have to make ths configuration by default, but you can opt into certain features or disable them if you want to.

Returns:

a GraphQLUnusualConfiguration.GraphQLContextConfiguration object

unusualConfiguration

public static GraphQLUnusualConfiguration.GraphQLContextConfiguration unusualConfiguration(ExecutionInput.Builder executionInputBuilder)

This allows you to control "unusual" per execution aspects of the GraphQL system

This is named unusual because in general we don't expect you to have to make ths configuration by default, but you can opt into certain features or disable them if you want to.

Returns:

a GraphQLUnusualConfiguration.GraphQLContextConfiguration object

unusualConfiguration

public static GraphQLUnusualConfiguration.GraphQLContextConfiguration unusualConfiguration(GraphQLContext graphQLContext)

This allows you to control "unusual" per execution aspects of the GraphQL system

This is named unusual because in general we don't expect you to have to make ths configuration by default, but you can opt into certain features or disable them if you want to.

Returns:

a GraphQLUnusualConfiguration.GraphQLContextConfiguration object

unusualConfiguration

public static GraphQLUnusualConfiguration.GraphQLContextConfiguration unusualConfiguration(GraphQLContext.Builder graphQLContextBuilder)

This allows you to control "unusual" per execution aspects of the GraphQL system

This is named unusual because in general we don't expect you to have to make ths configuration by default, but you can opt into certain features or disable them if you want to.

Returns:

a GraphQLUnusualConfiguration.GraphQLContextConfiguration object

getGraphQLSchema

public GraphQLSchema getGraphQLSchema()

Returns:

the schema backing this GraphQL instance

getQueryStrategy

public ExecutionStrategy getQueryStrategy()

Returns:

the execution strategy used for queries in this GraphQL instance

getMutationStrategy

public ExecutionStrategy getMutationStrategy()

Returns:

the execution strategy used for mutation in this GraphQL instance

getSubscriptionStrategy

public ExecutionStrategy getSubscriptionStrategy()

Returns:

the execution strategy used for subscriptions in this GraphQL instance

getIdProvider

public ExecutionIdProvider getIdProvider()

Returns:

the provider of execution ids for this GraphQL instance

getInstrumentation

public Instrumentation getInstrumentation()

Returns:

the Instrumentation for this GraphQL instance, if any

isDoNotAutomaticallyDispatchDataLoader

public boolean isDoNotAutomaticallyDispatchDataLoader()

getPreparsedDocumentProvider

public PreparsedDocumentProvider getPreparsedDocumentProvider()

Returns:

the PreparsedDocumentProvider for this GraphQL instance

getValueUnboxer

public ValueUnboxer getValueUnboxer()

Returns:

the ValueUnboxer for this GraphQL instance

newGraphQL

public static GraphQL.Builder newGraphQL(GraphQLSchema graphQLSchema)

Helps you build a GraphQL object ready to execute queries

Parameters:

graphQLSchema - the schema to use

Returns:

a builder of GraphQL objects

transform

public GraphQL transform(Consumer<GraphQL.Builder> builderConsumer)

This helps you transform the current GraphQL object into another one by starting a builder with all the current values and allows you to transform it how you want.

Parameters:

builderConsumer - the consumer code that will be given a builder to transform

Returns:

a new GraphQL object based on calling build on that builder

execute

public ExecutionResult execute(String query)

Executes the specified graphql query/mutation/subscription

Parameters:

query - the query/mutation/subscription

Returns:

an ExecutionResult which can include errors

execute

public ExecutionResult execute(ExecutionInput.Builder executionInputBuilder)

Executes the graphql query using the provided input object builder

Parameters:

executionInputBuilder - ExecutionInput.Builder

Returns:

an ExecutionResult which can include errors

execute

public ExecutionResult execute(UnaryOperator<ExecutionInput.Builder> builderFunction)

Executes the graphql query using calling the builder function and giving it a new builder.

This allows a lambda style like :

 
    ExecutionResult result = graphql.execute(input -> input.query("{hello}").root(startingObj).context(contextObj));
 
 

Parameters:

builderFunction - a function that is given a ExecutionInput.Builder

Returns:

an ExecutionResult which can include errors

execute

public ExecutionResult execute(ExecutionInput executionInput)

Executes the graphql query using the provided input object

Parameters:

executionInput - ExecutionInput

Returns:

an ExecutionResult which can include errors

executeAsync

public CompletableFuture<ExecutionResult> executeAsync(ExecutionInput.Builder executionInputBuilder)

Executes the graphql query using the provided input object builder

This will return a promise (aka CompletableFuture) to provide a ExecutionResult which is the result of executing the provided query.

Parameters:

executionInputBuilder - ExecutionInput.Builder

Returns:

a promise to an ExecutionResult which can include errors

executeAsync

public CompletableFuture<ExecutionResult> executeAsync(UnaryOperator<ExecutionInput.Builder> builderFunction)

Executes the graphql query using the provided input object builder

This will return a promise (aka CompletableFuture) to provide a ExecutionResult which is the result of executing the provided query.

This allows a lambda style like :

 
    ExecutionResult result = graphql.execute(input -> input.query("{hello}").root(startingObj).context(contextObj));
 
 

Parameters:

builderFunction - a function that is given a ExecutionInput.Builder

Returns:

a promise to an ExecutionResult which can include errors

executeAsync

public CompletableFuture<ExecutionResult> executeAsync(ExecutionInput executionInput)

Executes the graphql query using the provided input object

This will return a promise (aka CompletableFuture) to provide a ExecutionResult which is the result of executing the provided query.

Parameters:

executionInput - ExecutionInput

Returns:

a promise to an ExecutionResult which can include errors