We are happy to announce v18.0 of graphql-java

https://github.com/graphql-java/graphql-java/pulls?q=is%3Apr+milestone%3A18.0+is%3Aclosed

Applied Directives

Graphql directives have two modes. They can be defined in a schema

directive @example on FIELD_DEFINITION | ARGUMENT_DEFINITION

and they can be applied to schema elements and query elements

type Query {
   field(arg : String! ) @example

So we have a directive definition and cases where that directive is applied to an element.

However when the graphql.schema.GraphQLDirective and graphql.schema.GraphQLArgument classes was created, we modelled this badly. These classes should really represent a directive definition in schema only but we reused them to also be the representation of a directive and value arguments applied to another schema or query element.

This modelling is wrong. You can tell because we have javadoc comments like this in graphql.schema.GraphQLArgument saying a certain property is only applicable in certain call contexts.

    /**
     * This is only used for applied directives, that is when this argument is on a {@link GraphQLDirective} applied to a schema or query element
     *
     * @return an input value with state for an applied directive
     *
     * @deprecated use {@link GraphQLAppliedDirectiveArgument} instead
     */
    @Deprecated
    public @NotNull InputValueWithState getArgumentValue() {
        return value;
    }

So we have decided to fix this bad class modelling in version 18. We have introduced new classes

• graphql.schema.GraphQLAppliedDirective
• graphql.schema.GraphQLAppliedDirectiveArgument

which represent an applied directive on a schema element and

• graphql.execution.directives.QueryAppliedDirective
• graphql.execution.directives.QueryAppliedDirectiveArgument

which represent an applied directive on a query element

For backwards compatibility reasons, the old graphql.schema.GraphQLDirective objects are still created for applied elements however the methods have all been deprecated and like for like getAppliedXXX methods have been introduced.

You should migrate your code way from getting applied directives from the old methods and use the new more correctly modelled classes. This backwards compatibility will be removed in a future version.

Because of this backwards compatibility, there are a few gotchas to look out for. For example visitors will be called twice for the same applied element, eg one for the old style GraphQLDirective object and one for the new GraphQLAppliedDirective object. You should choose the new classes only as part of code migration. This should only affect code that does schema and query traversal (which is an advanced use case) and hence most consumers of graphql-java will not be affected.

There is one breaking change here. graphql.introspection.IntrospectionWithDirectivesSupport and its predicate argument graphql.introspection.IntrospectionWithDirectivesSupport.DirectivePredicateEnvironment have been changed to provide a directive name and not the appliedGraphQLDirective directly. Again we think very few people will be affected by this breaking change.

#2186

Dramatic performance improvement on Validation rules

The team at Twitter contributed a changed to the RulesVisitor that is used to validate a query against the set of validation rules. For large queries this could be a performance drag.

This changes it to roughly linear complexity and shows a 5000% speedup when validating our large queries.

#2563

Skipping validation rules

In extreme cases, a server may choose to skip certain validation rules. We don't recommend it, because results may become unpredictable and we won't support fixing issues caused by deactivated rules.

However it is now possible and may help trade validation for performance.

 Predicate<Class<?>> predicate = new Predicate<Class<?>>() {
            @Override
            boolean test(Class<?> aClass) {
                if (aClass == NoUnusedFragments.class) {
                    return false
                }
                return true
            }
        }
        
ExecutionInput.newExecutionInput(query)
                .graphQLContext(["graphql.ParseAndValidate.Predicate": predicate])
                .build()

#2598

DataLoader has been upgrade

The java data loader version has been upgrade to 3.1.2 which as some bug fixes and small improvements.

#2724

PreparsedDocumentProvider changes

The graphql.execution.preparsed.PreparsedDocumentProvider has been updated to use a CompletableFuture<PreparsedDocumentEntry> getDocumentAsync method. This allows you to go to a remote cache in an asynchronous non blocking manner to get cached documents. This should have always been modelled in this manner.

However its an optional default interface method thats called the old deprecated synchronous method direct.

https://github.com/graphql-java/graphql-java/pull/2612/files

AstPrinter performance

The AST printer has been improved to stop unnecessary string allocation. For very large queries this slowed printing down dramatically.

#2729

Local context and field selection in TypeResolutionEnvironment

The type resolvers now can get access to the local context object via the passed in graphql.TypeResolutionEnvironment interface.

Similarly, the field sub selection graphql.schema.DataFetchingFieldSelectionSet is also now available.

#2699
#2597

Auto generated list of What's Changed

• This adds the AST definitions onto applied directives and applied arguments by @bbakerman in #2556
• Adding a parser listener AND the ability to set parser options per request by @bbakerman in #2555
• Add InstrumentationValidationParameters to QueryComplexityInfo by @stevenleeDB in #2558
• A protected method for logging by @bbakerman in #2569
• Improve non-nullable argument exception in ValuesResolver by @dondonz in #2572
• Support for custom validation error by @dugenkui03 in #2528
• Fix triple nested enum validation error by @dondonz in #2570
• Sort schema directives in SchemaPrinter. by @folone in #2575
• Only publish with Maven POM, disable Gradle module metadata file by @dondonz in #2586
• Override ImmutableMapWithNullValues.toString() (#2568) by @fvasco in #2594
• Fixed a bug in NormalisedInputValue by @bbakerman in #2599
• Compatator is used for in order schema printing by @russellyou in #2606
• The ability to sort a schema during printing by @bbakerman in #2561
• Support for tracking the parse order by @bbakerman in #2539
• fix broken build by @russellyou in #2607
• Added support for a context object to the AstTransformer by @chriswr95 in #2596
• Add type reference support to interface builders by @dondonz in #2602
• Fix integration test using the default Locale in Locale#getDisplayName() by @jord1e in #2611
• Avoid printing inline fragment if there is no conditional type by @gnawf in #2621
• fix typos in javadoc by @dfa1 in #2619
• Simplify some isEqualTo implementations by @dfa1 in #2620
• It's hard to search for failed in test output when we say this a lot.… by @bbakerman in #2629
• change preparsedDocumentProvider return value to CompletableFuture by @heoYH in #2612
• Propagate errors to individual Subscription events by @jord1e in #2610
• Directive validation is now done on schema build post validation by @bbakerman in #2576
• Using custom data structure for callstack tracking by @dfa1 in #2630
• Naming fix up to IntMap by @bbakerman in #2631
• Only print out important tests by @bbakerman in #2632
• A default implementation of DataFetcherExceptionHandler.onException by @bbakerman in #2614
• Correct broken links to documentation site by @jamietanna in #2640
• Allow leading pipe in directive SDL, and add leading union pipe tests by @jord1e in #2650
• Bugfix: Check wiring factory when fetching scalar implementations in ArgValueOfAllowedTypeChecker by @sachindshinde in #2648
• Bugfix: spec-compliant behaviour for non-nullable types with default values. by @folone in #2573
• This adds the field selection set to the type resolver by @bbakerman in #2597
• Fix AstPrinter trimming blank string values by @gnawf in #2672
• use new defaultValue method by @andimarek in #2687
• This uses -parameters as javac options by @bbakerman in #2671
• make FetchedValue part of the public API by @andimarek in #2690
• Fix gh-2702 and add Introspection.__DirectiveLocation regression tests by @jord1e in #2703
• This allows you to derive new classes from the error builder class by @bbakerman in #2651
• Allow certain query validation rules to be skipped by @bbakerman in #2598
• Fix wrong newline on Windows in SchemaPrinter (\r\n -> \n) by @jord1e in #2705
• Replace wrong constructor call to BigInteger in tests by @jord1e in #2711
• Fix generics on JDK 9+ by @jord1e in #2710
• Add missing @Deprecated to ExecutionStepInfo#getFieldContainer() by @jord1e in #2712
• validation perf improvements by @jbellenger in #2563
• Deprecate NextGen engine by @bbakerman in #2708
• Update dependencies, and update Gradle wrapper to 7.3.3 by @jord1e in #2713
• Added in local context to TypeResolutionEnvironment by @bbakerman in #2699
• Validation of input and output types only in the right context by @bbakerman in #2664
• Schema Usage support by @bbakerman in #2548
• Allows nullable error attributes in GraphqlErrorBuilder by @bbakerman in #2670
• Add clearErrors method to Builder in DataFetcherResult by @rabbitvirus in #2716
• ErrorBuilder<?> does not work with Kotlin by @bbakerman in #2718
• Support custom schema validation error classification by @dugenkui03 in #2723
• Upgrade dataloader to 3.1.2 by @bbakerman in #2724
• AstPrinter performance improvements by @bbakerman in #2729
• Added a missing onDispatch to the beginExecution by @bbakerman in #2730
• Adds a predicate mechanism to compile a document into all variables or just some by @bbakerman in #2731
• Oops - put test code in src/main by @bbakerman in #2733
• READY- Applied Directives by @bbakerman in #2562
• Change SchemaProblem from @internal to @publicapi by @dugenkui03 in #2735
• Improve ExecutableNormalizedField.isConditional for interface fields and fix a bug regarding covariant fields by @gnawf in #2638
• Avoid a binary incompatible change while retaining common code by @bbakerman in #2748
• This is some performance optimisations for NormalisedOperations by @bbakerman in #2732
• Rework isConditional to work without parent type name and adopt DataFetchingSelectionSet to ENF changes by @bbakerman in #2738
• Make ExecutionStepInfo values be lazy by @bbakerman in #2749
• Update README.zh_cn.md by @dugenkui03 in #2758

New Contributors

• @stevenleeDB made their first contribution in #2558
• @folone made their first contribution in #2575
• @fvasco made their first contribution in #2594
• @russellyou made their first contribution in #2606
• @chriswr95 made their first contribution in #2596
• @jord1e made their first contribution in #2611
• @heoYH made their first contribution in #2612
• @jamietanna made their first contribution in #2640
• @sachindshinde made their first contribution in #2648
• @jbellenger made their first contribution in #2563
• @rabbitvirus made their first contribution in #2716

Full Changelog: v17.3...v18.0