Merge pull request #130 from graphql-java/v21-release

v21 release

Author: dondonz

blog/2023-07-11-v21-released.md

@@ -0,0 +1,11 @@
+---
+title: "Version 21 released"
+authors: donna
+slug: v21-released
+---
+
+We are pleased to announce the release of graphql-java v21.0! Thanks to everyone in the community who contributed to the release, whether that was code, helping to report issues, or participating in discussions.
+
+And a very Happy 8th Birthday to graphql-java, who celebrated their birthday last week!
+
+This is a **breaking change** release, including upgrading to Java 11 and changes to `parseValue` coercion. See the full release notes on [GitHub](https://github.com/graphql-java/graphql-java/releases/tag/v21.0).

documentation/getting-started.mdx

@@ -25,7 +25,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.graphql-java:graphql-java:20.4'
+    implementation 'com.graphql-java:graphql-java:21.0'
 }
 ```
 </TabItem>
@@ -38,7 +38,7 @@ repositories {
 }
 
 dependencies {
-    implementation("com.graphql-java:graphql-java:20.4")
+    implementation("com.graphql-java:graphql-java:21.0")
 }
 ```
 </TabItem>
@@ -51,7 +51,7 @@ Dependency:
 <dependency>
     <groupId>com.graphql-java</groupId>
     <artifactId>graphql-java</artifactId>
-    <version>20.4</version>
+    <version>21.0</version>
 </dependency>
 ```
 

documentation/instrumentation.md

@@ -98,7 +98,7 @@ GraphQL.newGraphQL(schema)
 ``graphql.execution.instrumentation.tracing.TracingInstrumentation`` is an ``Instrumentation`` implementation that creates tracing information
 about the query that is being executed.
 
-It follows the Apollo proposed tracing format defined at `https://github.com/apollographql/apollo-tracing <https://github.com/apollographql/apollo-tracing>`_
+It follows the Apollo proposed tracing format defined at [https://github.com/apollographql/apollo-tracing](https://github.com/apollographql/apollo-tracing).
 
 A detailed tracing map will be created and placed in the ``extensions`` section of the result.
 

readme.md

@@ -47,6 +47,8 @@ Then update `lastVersion` inside `docusaurus.config.js`
 lastVersion: "v20",
 ```
 
-Finally, change the Maven and Gradle sections in [documentation/getting-started.mdx](/documentation/getting-started.mdx) and versioned documentation inside `versioned_docs`.
+Delete the oldest version by deleting the oldest version's directory inside `versioned_docs` and the corresponding file in `versioned_sidebars`. Then delete the oldest version from `versions.json`.
+
+Finally, change the Maven and Gradle sections in [documentation/getting-started.mdx](/documentation/getting-started.mdx).
 
 For more, see the [Docusaurus versioning documentation](https://docusaurus.io/docs/versioning).

versioned_docs/version-v20/getting-started.mdx

@@ -10,7 +10,7 @@ import TabItem from '@theme/TabItem';
 
 # Getting started
 
-`graphql-java` requires at least Java 8.
+`graphql-java` v20.x requires at least Java 8.
 
 ## How to use the latest release with Gradle
 

versioned_docs/version-v19/batching.md versioned_docs/version-v21/batching.mdversioned_docs/version-v19/batching.md renamed to versioned_docs/version-v21/batching.md

@@ -28,7 +28,7 @@ type Product {
   description : String
   cost : Float
   tax : Float
-  launchDate(dateFormat : String = "dd, MMM, yyyy") : String
+  launchDate(dateFormat : String = "dd, MMM, yyyy') : String
 }
 ```
 
@@ -113,24 +113,9 @@ called ``fieldX`` or a map key called ``fieldX`` if the backing object is a ``Ma
 However you may have small differences between your graphql schema naming and runtime object naming.  For example imagine that ``Product.description`` is actually
 represented as ``getDesc()`` in the runtime backing Java object.
 
-If you are using SDL to specify your schema then you can use the ``@fetch`` directive to indicate this remapping.
-
-```graphql
-directive @fetch(from : String!) on FIELD_DEFINITION
-
-type Product {
-    id : ID
-    name : String
-    description : String @fetch(from:"desc")
-    cost : Float
-    tax : Float
-}
-```
-
+You can specify it directly by wiring in a field data fetcher.
 This will tell the ``graphql.schema.PropertyDataFetcher`` to use the property name ``desc`` when fetching data for the graphql field named ``description``.
 
-If you are hand coding your schema then you can just specify it directly by wiring in a field data fetcher.
-
 ```java
 GraphQLFieldDefinition descriptionField = GraphQLFieldDefinition.newFieldDefinition()
         .name("description")

versioned_docs/version-v19/concerns.md versioned_docs/version-v21/concerns.mdversioned_docs/version-v19/concerns.md renamed to versioned_docs/version-v21/concerns.md

@@ -3,9 +3,9 @@ title: "Data mapping"
 date: 2018-09-09T12:52:46+10:00
 description: How graphql-java maps object data to graphql types
 ---
-# Mapping data
+# Mapping output data
 
-## How graphql maps object data to types
+## How graphql maps object data to output types
 
 At its heart graphql is all about declaring a type schema and mapping that over backing runtime data.
 
@@ -166,3 +166,154 @@ For every object in the list it will look for an ``id`` field, find it by name i
 response.  It does that for every field in the query on that type.
 
 By creating a "unified view" at the higher level data fetcher, you have mapped between your runtime view of the data and the graphql schema view of the data.
+
+# Mapping input data
+
+## How graphql maps object data to input types
+
+Input type values are provided to as input to a graphql operation.  The three kinds of types that can be input are **Enums**, **Scalars** and **Input Object Types** and the **List** and **Non-Null** variants of these
+type kinds.
+
+The following outlines how graphql-java represents these type kinds in JVM runtime terms.
+
+### Enums
+
+graphql-java maps input `Enum` values by name.  When you create the `graphql.schema.GraphQLEnumType` instance you can in theory map a name `java.lang.String`
+to any JVM object.  But this is not common at all.  Mostly the name of the enum value is the actual value of it.
+
+```graphql
+enum RGB {
+    RED, BLUE, GREEN
+}
+
+scalar Pantone
+
+type Query {
+    toPantone( color : RGB) : Pantone
+}
+```
+
+The `RGB` enum type above has the runtime JVM `java.lang.String` values of `"RED"`,`"BLUE"` and `"GREEN"` on input and output.
+
+The graphql-java system allow you to also input `java.lang.Enum` but this is not common at all for input.  The reason it's not common is that this would 
+require you to turn your network input into Java enums and this is not a common action of serialisation frameworks.
+
+If the input value to the enum comes from the graphql operation document, then the input value will initially be a `graphql.language.EnumValue` which
+is the AST representation of a graphql `Enum` value.  This will be converted by graphql-java to a value by name.  
+
+So a query document like the following will end up mapping the AST enum input value `RED` to the JVM value `"RED"`.
+
+```graphql
+query MyColors {
+    toPantone(color : RED)
+}
+```
+
+### Scalars
+
+The input values to a scalar are controlled by the scalar implementation.  If their `graphql.schema.Coercing#parseValue(java.lang.Object, graphql.GraphQLContext, java.util.Locale)` accepts
+a certain value then it's up to them to decide what JVM object is returned by the scalar code.
+
+The graphql-java scalars will return the following values as JVM object input values.
+
+* **String** aka ``GraphQLString`` - will produce a `java.lang.String`
+* **Boolean** aka ``GraphQLBoolean`` - will produce a `java.lang.Boolean`
+* **Int** aka ``GraphQLInt`` - will produce a `java.lang.Integer`
+* **Float** aka ``GraphQLFloat`` - will produce a `java.lang.Double`
+* **ID** aka ``GraphQLID`` - will produce a `java.lang.String`
+
+### Input Object Types
+
+Input object types are complex input types with named input fields. The runtime JVM representation will be a `java.util.Map`.  Specifically 
+a map that ordered its keys in a predictable way.
+
+So imagine this input type named `Person`
+
+```graphql
+input Person {
+    name : String!
+    age : Int!
+}
+
+type Query {
+    contact(person : Person) : String
+}
+```
+
+This will be represented at runtime as a `java.util.Map` containing a key `name` with a `java.lang.String` value and 
+a key `age` with a `java.lang.Integer` value.
+
+### Nonnull input types
+
+There is no special runtime object used for non-null input types other than the called code can safely assume that the object
+is not a null value.
+
+```graphql
+type Query {
+    field(arg1 : String!, arg2 : String) : String
+}
+```
+
+So in the example above the `arg1` field argument will always be a non-null `java.lang.String` value while `arg2` may be `null` at runtime.
+
+### Lists of input types
+
+If the input type is a graphql list input type then the runtime JVM representation will be a `java.util.List` of the wrapped input type.
+
+So as an example, given
+
+```graphql
+type Query {
+    field(arg : [String!]!) : String
+}
+```
+
+The `arg` field argument would be a non-null `java.util.List` containing zero or more non-null `java.lang.String` values.
+
+In graphql you can say that a list is non-null and its entries are also non-null
+however there is no way to say that the list has one or more entries.  
+
+The `arg` field argument above could be an empty list.  It will not be `null` but it could be empty.
+
+Complex runtime input values can be declared and the runtime representation will reflect that.
+
+```graphql
+input Person {
+    name : String!
+    age : Int!
+    friends : [Person!]
+}
+
+type Query {
+    contacts(people : [Person!]!) : String
+}
+
+```
+
+The `person` field argument would be a `java.util.List` containing one or more `java.util.Map`s, where each map contained named entries 
+and the `friends` map entry could itself be a `java.util.List` containing one or more `java.util.Map`s, so imagine 
+the following representation at runtime :
+
+```java
+        List.of(
+                Map.of("name", "Brad",
+                        "age", 42,
+                        "friends", List.of(
+                                Map.of("name", "Bill",
+                                        "age", 17,
+                                        "friends", List.of()
+                                )
+                        )
+                ),
+                Map.of("name", "Andreas",
+                        "age", 34,
+                        "friends", List.of(
+                                Map.of("name", "Ted",
+                                        "age", 15,
+                                        "friends", List.of()
+                                )
+                        )
+                )
+        );
+
+```