Improving applied directive & directive builders #3825

dondonz · 2025-02-16T05:10:38Z

Opening this PR for discussion.

For directive containers, @gnawf reported that the withAppliedDirectives builder surprisingly also cleared all of the existing directives, given that there is already a replaceAppliedDirectives builder. This led to a bug, and it was quickly fixed by using the singular withAppliedDirective builder, which doesn't delete any prior applied directives.

I agree that it is surprising, I would expect with implies that applied directives are only added without deleting existing applied directives. It seems like the previous code, before the transition to Applied Directives, also had this behaviour. I'm open here, maybe this is intended behaviour and I don't know the story behind it.

I think it would be better to have two sorts of builders, one that only adds applied directives, and another sort that can clear and replace all the existing applied directives, rather than the current state where two differently named methods are doing the same thing (replacement).

To make this change clearer I would like to introduce a new method addAppliedDirectives to supercede the withAppliedDirectives methods.

I guess this issue wasn't reported earlier because it is a less common use case. If a person wants to retain the legacy behaviour, they can switch to using replaceAppliedDirectives instead.

Although this is small, this is a breaking change so I would like to discuss this before making changes.

…ives

…r coverage

dondonz · 2025-02-16T05:12:06Z

src/main/java/graphql/schema/GraphqlDirectivesContainerTypeBuilder.java


 import static graphql.Assert.assertNotNull;

-@SuppressWarnings("unchecked")


IDEA told me it's no longer needed, I do what the computer says

dondonz · 2025-02-16T05:13:05Z

src/main/java/graphql/schema/GraphqlDirectivesContainerTypeBuilder.java

+
+    public B addAppliedDirective(GraphQLAppliedDirective.Builder builder) {
+        return addAppliedDirective(builder.build());
+    }


Because it makes more sense for all the additive builders to start with "add", I have also created the "add" version for the singular method, but I think the prior implementation was correct

dondonz · 2025-02-16T05:13:21Z

src/main/java/graphql/schema/GraphqlDirectivesContainerTypeBuilder.java

+            addAppliedDirective(directive);
+        }
+        return (B) this;
+    }


This no longer clears existing directives

I think this is a copy and paste bug

we have

public B replaceAppliedDirectives(List<GraphQLAppliedDirective> directives) { assertNotNull(directives, () -> "directive can't be null"); this.appliedDirectives.clear(); this.appliedDirectives.addAll(directives); return (B) this; } public B withAppliedDirectives(GraphQLAppliedDirective... directives) { assertNotNull(directives, () -> "directives can't be null"); this.appliedDirectives.clear(); /// COPY PASTE BUG HERE for (GraphQLAppliedDirective directive : directives) { withAppliedDirective(directive); } return (B) this; }

I think it was never meant to clear it because as you say we have non clearing singular version

public B withAppliedDirective(GraphQLAppliedDirective directive) { assertNotNull(directive, () -> "directive can't be null"); this.appliedDirectives.add(directive); return (B) this; }

I agree that addXXX might be more clearer but honestly I would change the bheavior of the original withXXX rather than add a new method. This is a breaking change after all

Hmmmmmmmm or maybe not

public B withDirectives(GraphQLDirective... directives) { assertNotNull(directives, () -> "directives can't be null"); this.directives.clear(); for (GraphQLDirective directive : directives) { withDirective(directive); } return (B) this; }

from another class does the same thing

copy and paste copy and paste bug??

I can see other "withXXX plural" and they dont do the clear behavior

public Builder withSchemaDirectives(GraphQLDirective... directives) { for (GraphQLDirective directive : directives) { withSchemaDirective(directive); } return this; }

That's right we have a combo of a copy paste of possibly a bug and then a typo that led to unusual behaviour

My preference is to change withXXX rather than introducing new addXXX methods, because most people are used to builders having "with", but wasn't sure how cautious to be

y preference is to change withXXX rather than introducing new addXXX methods,
I concur. Lets do that

github-actions · 2025-02-16T05:14:33Z

Test Results

310 files 310 suites 46s ⏱️
3 565 tests 3 559 ✅ 6 💤 0 ❌
3 654 runs 3 648 ✅ 6 💤 0 ❌

Results for commit 12eaa86.

♻️ This comment has been updated with latest results.

dondonz · 2025-02-16T05:14:39Z

src/main/java/graphql/schema/GraphqlDirectivesContainerTypeBuilder.java

+     * @deprecated - use {@link #replaceAppliedDirectives(List)} to clear and replace directives,
+     * or {@link #addAppliedDirectives(GraphQLAppliedDirective...)} to add directives without clearing the existing ones
+     */
+    @Deprecated(since = "2025-02-16", forRemoval = true)


forRemoval is set to true because this behaviour is identical in replaceAppliedDirectives

dondonz · 2025-02-16T05:14:57Z

src/main/java/graphql/schema/GraphqlDirectivesContainerTypeBuilder.java

+    @Deprecated(since = "2025-02-16", forRemoval = true)
    public B withAppliedDirectives(GraphQLAppliedDirective... directives) {
        assertNotNull(directives, () -> "directives can't be null");
        this.appliedDirectives.clear();


This is the unusual line - directives are cleared

src/main/java/graphql/schema/GraphqlDirectivesContainerTypeBuilder.java

dondonz · 2025-02-16T05:17:19Z

src/main/java/graphql/schema/GraphqlDirectivesContainerTypeBuilder.java

+     */
+    @Deprecated(since = "2025-02-16", forRemoval = true)
    public B withAppliedDirective(GraphQLAppliedDirective.Builder builder) {
        return withAppliedDirectives(builder.build());


This may have been an unintentional typo during the major migration to Applied Directives.

The previous singular withAppliedDirective method that takes a GraphQLAppliedDirective does not clear any prior directives, but this withAppliedDirective with a builder parameter will take clear existing directives because it calls the plural withAppliedDirectives method

The new 'addAppliedDirective' method corresponding to this one (with a builder parameter) does not clear directives

dondonz · 2025-02-16T05:19:24Z

src/test/groovy/graphql/execution/ValuesResolverTest.groovy

        def inputType = newInputObject()
                .name("Person")
-                .withAppliedDirective(Directives.OneOfDirective.toAppliedDirective())
+                .addAppliedDirective(Directives.OneOfDirective.toAppliedDirective())


I updated tests to use the new "add" versions of builders, and I added a few legacy tests for coverage. We can delete the legacy tests when we removed the deprecated methods

Scroll down to AppliedDirectivesAreValid test file to see the test that demonstrates the change in behaviour

dondonz · 2025-02-16T05:45:35Z

src/test/groovy/graphql/schema/validation/AppliedDirectivesAreValidTest.groovy

-        hasError(schemaProblem, "The directive 'directiveA' on the 'GraphQLFieldDefinition' called 'fieldD' is a non repeatable directive but has been applied 2 times");
-        hasError(schemaProblem, "The directive 'directiveA' on the 'GraphQLFieldDefinition' called 'fieldA' is a non repeatable directive but has been applied 2 times");
-        hasError(schemaProblem, "The directive 'directiveA' on the 'GraphQLEnumValueDefinition' called 'enumA' is a non repeatable directive but has been applied 2 times");
-        hasError(schemaProblem, "The directive 'directiveA' on the 'GraphQLInputObjectField' called 'inputFieldA' is a non repeatable directive but has been applied 2 times");


IDEA told me to delete the semi colons, I do what the computer says

dondonz · 2025-02-16T05:46:35Z

src/test/groovy/graphql/schema/validation/AppliedDirectivesAreValidTest.groovy

+        hasError(schemaProblem, "The directive 'directiveA' on the 'GraphQLInputObjectField' called 'inputFieldA' is a non repeatable directive but has been applied 2 times")
+    }
+
+    def "add applied directive builders do not clear any existing applied directives"(){


Here are a pair of tests to demonstrate the change of "clearing" behaviour more clearly

There isn't already a directive container test file, adding here instead for now

bbakerman

We spoke last week about this removing the add method and changing the with methods

Marking this as "request changes" to indicate that

dondonz · 2025-03-16T08:21:45Z

src/main/java/graphql/schema/GraphqlDirectivesContainerTypeBuilder.java

+     */
    public B withAppliedDirectives(GraphQLAppliedDirective... directives) {
        assertNotNull(directives, () -> "directives can't be null");
-        this.appliedDirectives.clear();


Removing the unintended "clear" behaviour

dondonz · 2025-03-16T08:36:14Z

src/main/java/graphql/schema/GraphqlDirectivesContainerTypeBuilder.java

+     * @return this builder
+     */
    public B withAppliedDirective(GraphQLAppliedDirective.Builder builder) {
-        return withAppliedDirectives(builder.build());


Seems to have been a typo

dondonz · 2025-03-16T08:36:24Z

src/test/groovy/graphql/execution/ValuesResolverTest.groovy


 import graphql.Directives
 import graphql.ErrorType
-import graphql.ExecutionInput


dondonz · 2025-03-16T08:44:39Z

src/main/java/graphql/schema/GraphqlDirectivesContainerTypeBuilder.java

    @Deprecated(since = "2022-02-24")
    public B withDirectives(GraphQLDirective... directives) {
        assertNotNull(directives, () -> "directives can't be null");
-        this.directives.clear();


This method is deprecated, but let's also remove the unintended clear line from here

dondonz · 2025-03-16T08:47:58Z

I've changed the existing with builders instead of adding a new set of add builders

dondonz · 2025-03-16T08:48:22Z

src/test/groovy/graphql/schema/validation/AppliedDirectivesAreValidTest.groovy

+        hasError(schemaProblem, "The directive 'directiveA' on the 'GraphQLInputObjectField' called 'inputFieldA' is a non repeatable directive but has been applied 2 times")
+    }
+
+    def "applied directive builders do not clear any existing applied directives"() {


A new test to lock in the new behaviour

dondonz added 2 commits February 16, 2025 11:40

Add new add directives method which doesn't clear the existing direct…

9f7eb53

…ives

Update tests to use new methods whilst retaining some legacy tests fo…

b02e379

…r coverage

dondonz added the breaking change requires a new major version to be relased label Feb 16, 2025

dondonz added this to the 23.x breaking changes milestone Feb 16, 2025

dondonz commented Feb 16, 2025

View reviewed changes

src/main/java/graphql/schema/GraphqlDirectivesContainerTypeBuilder.java Show resolved Hide resolved

dondonz commented Feb 16, 2025

View reviewed changes

Add tests to demonstrate the change in behaviour

0c0aeca

dondonz commented Feb 16, 2025

View reviewed changes

dondonz changed the title ~~WIP Improving applied directive builders~~ Improving applied directive builders Feb 16, 2025

bbakerman requested changes Feb 27, 2025

View reviewed changes

dondonz added 2 commits March 16, 2025 19:04

Merge branch 'master' into directive-helpers

677933f

Remove extra add directives, put behaviour in original builders

39d451c

dondonz commented Mar 16, 2025

View reviewed changes

dondonz added 2 commits March 16, 2025 19:28

Change tests back

276cdea

More tidying up

1be0a4a

dondonz commented Mar 16, 2025

View reviewed changes

dondonz added 2 commits March 16, 2025 19:40

Lock in behaviour with tests

df2738b

Remove clear from non-applied directive builder

91c9b74

dondonz commented Mar 16, 2025

View reviewed changes

Tidy up

12eaa86

bbakerman approved these changes Mar 20, 2025

View reviewed changes

bbakerman merged commit 86724a4 into master Mar 20, 2025
2 checks passed

dondonz changed the title ~~Improving applied directive builders~~ Improving applied directive & directive builders Apr 4, 2025


		import static graphql.Assert.assertNotNull;

		@SuppressWarnings("unchecked")

Improving applied directive & directive builders #3825

Improving applied directive & directive builders #3825

Uh oh!

Conversation

dondonz commented Feb 16, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Feb 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Results

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dondonz Feb 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dondonz Feb 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bbakerman left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dondonz commented Mar 16, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions bot commented Feb 16, 2025 •

edited

Loading

dondonz Feb 16, 2025 •

edited

Loading

dondonz Feb 16, 2025 •

edited

Loading