diff --git a/.github/workflows/benchmarks.yml b/.github/workflows/benchmarks.yml
index dd9faf13b90..7bf8a0fc56a 100644
--- a/.github/workflows/benchmarks.yml
+++ b/.github/workflows/benchmarks.yml
@@ -5,25 +5,27 @@ on:
# branches: [ '*' ]
schedule:
- cron: '0 3 * * *'
+ workflow_dispatch:
+
env:
- GRADLE_ENTERPRISE_ACCESS_KEY: ${{ secrets.GRADLE_ENTERPRISE_ACCESS_KEY }}
+ DEVELOCITY_ACCESS_KEY: ${{ secrets.DEVELOCITY_ACCESS_KEY }}
jobs:
benchmarks:
runs-on: macos-14
if: github.repository == 'apollographql/apollo-kotlin'
steps:
- - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 #v4.1.1
- - uses: actions/setup-java@387ac29b308b003ca37ba93a6cab5eb57c8f5f93 #v4.0.0
+ - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 #v4.1.7
+ - uses: actions/setup-java@99b8673ff64fbf99d8d325f52d9a5bdedb8483e9 #v4.2.1
with:
distribution: 'temurin'
java-version: 17
- - uses: gradle/gradle-build-action@42452daeb5b454a76f686a8e4de8234afd7b1f44 #v2.12.0
+ - uses: gradle/actions/setup-gradle@dbbdc275be76ac10734476cc723d82dfe7ec6eda #v3.4.2
with:
gradle-home-cache-cleanup: true
- run: |
# Build the benchmark apks
- ./gradlew -p benchmark :app:assembleRelease :microbenchmark:assembleIncubatingReleaseAndroidTest :microbenchmark:assembleStableReleaseAndroidTest
+ ./gradlew -p benchmark :app:assembleRelease :microbenchmark:assembleReleaseAndroidTest
# Step can be removed if/when gcloud is added to the macos image - See https://github.com/actions/virtual-environments/issues/4639
- name: Setup gcloud
uses: google-github-actions/setup-gcloud@98ddc00a17442e89a24bbf282954a3b65ce6d200 #v2.1.0
diff --git a/.github/workflows/bump-kotlin-shadow.yml b/.github/workflows/bump-kotlin-shadow.yml
new file mode 100644
index 00000000000..0dfa6d1c87b
--- /dev/null
+++ b/.github/workflows/bump-kotlin-shadow.yml
@@ -0,0 +1,20 @@
+name: Bump kotlin shadow
+
+on:
+ schedule:
+ - cron: '0 2 * * *'
+ workflow_dispatch:
+
+jobs:
+ push-kotlin-nightlies-branch:
+ runs-on: macos-14
+ steps:
+ - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 #v4.1.7
+ - name: Bump Kotlin in libraries.toml
+ run: ./scripts/bump-kotlin-in-libraries-toml.main.kts
+ - name: Push changes to kotlin-nightlies branch
+ run: |
+ git checkout -b kotlin-nightlies
+ git add .
+ git commit -m "Bump Kotlin version"
+ git push --force origin kotlin-nightlies
diff --git a/.github/workflows/defer-with-router-tests.yml b/.github/workflows/defer-with-router-tests.yml
index 1074bc779ae..ae816371c8f 100644
--- a/.github/workflows/defer-with-router-tests.yml
+++ b/.github/workflows/defer-with-router-tests.yml
@@ -4,7 +4,7 @@ on:
schedule:
- cron: '0 3 * * *'
env:
- GRADLE_ENTERPRISE_ACCESS_KEY: ${{ secrets.GRADLE_ENTERPRISE_ACCESS_KEY }}
+ DEVELOCITY_ACCESS_KEY: ${{ secrets.DEVELOCITY_ACCESS_KEY }}
jobs:
defer-with-router-tests:
@@ -12,7 +12,7 @@ jobs:
if: github.repository == 'apollographql/apollo-kotlin'
steps:
- name: Checkout project
- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 #v4.1.1
+ uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 #v4.1.7
- name: Install and run subgraph
working-directory: tests/defer/router/subgraphs/computers
@@ -29,13 +29,13 @@ jobs:
./router --supergraph tests/defer/router/simple-supergraph.graphqls &
- name: Setup Java
- uses: actions/setup-java@387ac29b308b003ca37ba93a6cab5eb57c8f5f93 #v4.0.0
+ uses: actions/setup-java@99b8673ff64fbf99d8d325f52d9a5bdedb8483e9 #v4.2.1
with:
distribution: 'temurin'
java-version: 17
- name: Setup Gradle
- uses: gradle/gradle-build-action@42452daeb5b454a76f686a8e4de8234afd7b1f44 #v2.12.0
+ uses: gradle/actions/setup-gradle@dbbdc275be76ac10734476cc723d82dfe7ec6eda #v3.4.2
- name: Run Apollo Kotlin @defer tests
env:
diff --git a/.github/workflows/docs-publish.yml b/.github/workflows/docs-publish.yml
index f0df1982fd4..0a81d4a7794 100644
--- a/.github/workflows/docs-publish.yml
+++ b/.github/workflows/docs-publish.yml
@@ -13,7 +13,7 @@ on:
jobs:
publish:
- uses: apollographql/docs/.github/workflows/publish.yml@main
+ uses: apollographql/docs/.github/workflows/publish.yml@main # pga-ignore
if: github.repository == 'apollographql/apollo-kotlin'
secrets:
NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
diff --git a/.github/workflows/platform-api-tests.yml b/.github/workflows/platform-api-tests.yml
index a4403df6587..f1048b70872 100644
--- a/.github/workflows/platform-api-tests.yml
+++ b/.github/workflows/platform-api-tests.yml
@@ -8,7 +8,7 @@ on:
workflow_dispatch:
env:
- GRADLE_ENTERPRISE_ACCESS_KEY: ${{ secrets.GRADLE_ENTERPRISE_ACCESS_KEY }}
+ DEVELOCITY_ACCESS_KEY: ${{ secrets.DEVELOCITY_ACCESS_KEY }}
jobs:
platform-api-tests:
@@ -16,16 +16,16 @@ jobs:
if: github.repository == 'apollographql/apollo-kotlin'
steps:
- name: Checkout project
- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 #v4.1.1
+ uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 #v4.1.7
- name: Setup Java
- uses: actions/setup-java@387ac29b308b003ca37ba93a6cab5eb57c8f5f93 #v4.0.0
+ uses: actions/setup-java@99b8673ff64fbf99d8d325f52d9a5bdedb8483e9 #v4.2.1
with:
distribution: 'temurin'
java-version: 17
- name: Setup Gradle
- uses: gradle/gradle-build-action@42452daeb5b454a76f686a8e4de8234afd7b1f44 #v2.12.0
+ uses: gradle/actions/setup-gradle@dbbdc275be76ac10734476cc723d82dfe7ec6eda #v3.4.2
- name: Run tests against the Apollo Platform API
env:
diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml
index c8b31b03b44..c811d49bd50 100644
--- a/.github/workflows/pr.yml
+++ b/.github/workflows/pr.yml
@@ -5,12 +5,14 @@ on:
paths-ignore:
- 'docs/**'
- '*.md'
+ workflow_dispatch:
+
env:
- GRADLE_ENTERPRISE_ACCESS_KEY: ${{ secrets.GRADLE_ENTERPRISE_ACCESS_KEY }}
+ DEVELOCITY_ACCESS_KEY: ${{ secrets.DEVELOCITY_ACCESS_KEY }}
# Cancel any current or previous job from the same PR
concurrency:
- group: ${{ github.head_ref }}
+ group: ${{ format('{0}-', github.head_ref) }}
cancel-in-progress: true
jobs:
@@ -18,12 +20,12 @@ jobs:
if: "!startsWith(github.head_ref, 'release-')"
runs-on: macos-14
steps:
- - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 #v4.1.1
- - uses: actions/setup-java@387ac29b308b003ca37ba93a6cab5eb57c8f5f93 #v4.0.0
+ - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 #v4.1.7
+ - uses: actions/setup-java@99b8673ff64fbf99d8d325f52d9a5bdedb8483e9 #v4.2.1
with:
distribution: 'temurin'
java-version: 17
- - uses: gradle/gradle-build-action@42452daeb5b454a76f686a8e4de8234afd7b1f44 #v2.12.0
+ - uses: gradle/actions/setup-gradle@dbbdc275be76ac10734476cc723d82dfe7ec6eda #v3.4.2
with:
gradle-home-cache-cleanup: true
- name: Build with Gradle
@@ -32,7 +34,7 @@ jobs:
- name: Collect Diagnostics
if: always()
run: ./scripts/collect-diagnostics.main.kts
- - uses: actions/upload-artifact@26f96dfa697d77e81fd5907df203aa23a56210a8 #v4.3.0
+ - uses: actions/upload-artifact@65462800fd760344b1a7b4382951275a0abb4808 #v4.3.3
if: always()
with:
name: tests-gradle.zip
@@ -42,12 +44,12 @@ jobs:
if: "!startsWith(github.head_ref, 'release-')"
runs-on: macos-14
steps:
- - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 #v4.1.1
- - uses: actions/setup-java@387ac29b308b003ca37ba93a6cab5eb57c8f5f93 #v4.0.0
+ - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 #v4.1.7
+ - uses: actions/setup-java@99b8673ff64fbf99d8d325f52d9a5bdedb8483e9 #v4.2.1
with:
distribution: 'temurin'
java-version: 17
- - uses: gradle/gradle-build-action@42452daeb5b454a76f686a8e4de8234afd7b1f44 #v2.12.0
+ - uses: gradle/actions/setup-gradle@dbbdc275be76ac10734476cc723d82dfe7ec6eda #v3.4.2
with:
gradle-home-cache-cleanup: true
- name: Build with Gradle
@@ -56,7 +58,7 @@ jobs:
- name: Collect Diagnostics
if: always()
run: ./scripts/collect-diagnostics.main.kts
- - uses: actions/upload-artifact@26f96dfa697d77e81fd5907df203aa23a56210a8 #v4.3.0
+ - uses: actions/upload-artifact@65462800fd760344b1a7b4382951275a0abb4808 #v4.3.3
if: always()
with:
name: tests-no-gradle.zip
@@ -66,12 +68,12 @@ jobs:
if: "!startsWith(github.head_ref, 'release-')"
runs-on: macos-14
steps:
- - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 #v4.1.1
- - uses: actions/setup-java@387ac29b308b003ca37ba93a6cab5eb57c8f5f93 #v4.0.0
+ - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 #v4.1.7
+ - uses: actions/setup-java@99b8673ff64fbf99d8d325f52d9a5bdedb8483e9 #v4.2.1
with:
distribution: 'temurin'
java-version: 17
- - uses: gradle/gradle-build-action@42452daeb5b454a76f686a8e4de8234afd7b1f44 #v2.12.0
+ - uses: gradle/actions/setup-gradle@dbbdc275be76ac10734476cc723d82dfe7ec6eda #v3.4.2
with:
gradle-home-cache-cleanup: true
- name: Build with Gradle
@@ -80,7 +82,7 @@ jobs:
- name: Collect Diagnostics
if: always()
run: ./scripts/collect-diagnostics.main.kts
- - uses: actions/upload-artifact@26f96dfa697d77e81fd5907df203aa23a56210a8 #v4.3.0
+ - uses: actions/upload-artifact@65462800fd760344b1a7b4382951275a0abb4808 #v4.3.3
if: always()
with:
name: tests-integration.zip
@@ -102,11 +104,11 @@ jobs:
# Check out current repository
- name: Fetch Sources
- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 #v4.1.1
+ uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 #v4.1.7
# Setup Java 11 environment for the next steps
- name: Setup Java
- uses: actions/setup-java@387ac29b308b003ca37ba93a6cab5eb57c8f5f93 #v4.0.0
+ uses: actions/setup-java@99b8673ff64fbf99d8d325f52d9a5bdedb8483e9 #v4.2.1
with:
distribution: 'temurin'
java-version: 17
@@ -136,14 +138,14 @@ jobs:
# Collect Tests Result of failed tests
- name: Collect Tests Result
if: ${{ failure() }}
- uses: actions/upload-artifact@26f96dfa697d77e81fd5907df203aa23a56210a8 #v4.3.0
+ uses: actions/upload-artifact@65462800fd760344b1a7b4382951275a0abb4808 #v4.3.3
with:
name: tests-result
path: ${{ github.workspace }}/intellij-plugin/build/reports/tests
# Cache Plugin Verifier IDEs
- name: Setup Plugin Verifier IDEs Cache
- uses: actions/cache@13aacd865c20de90d75de3b17ebe84f7a17d57d2 #v4.0.0
+ uses: actions/cache@0c45773b623bea8c8e75f6c82b208c3cf94ea4f9 #v4.0.2
with:
path: ${{ steps.properties.outputs.pluginVerifierHomeDir }}/ides
key: plugin-verifier-${{ hashFiles('intellij-plugin/build/listProductsReleases.txt') }}
@@ -155,7 +157,7 @@ jobs:
# Collect Plugin Verifier Result
- name: Collect Plugin Verifier Result
if: ${{ always() }}
- uses: actions/upload-artifact@26f96dfa697d77e81fd5907df203aa23a56210a8 #v4.3.0
+ uses: actions/upload-artifact@65462800fd760344b1a7b4382951275a0abb4808 #v4.3.3
with:
name: pluginVerifier-result
path: ${{ github.workspace }}/intellij-plugin/build/reports/pluginVerifier
@@ -173,7 +175,7 @@ jobs:
# Store already-built plugin as an artifact for downloading
- name: Upload artifact
- uses: actions/upload-artifact@26f96dfa697d77e81fd5907df203aa23a56210a8 #v4.3.0
+ uses: actions/upload-artifact@65462800fd760344b1a7b4382951275a0abb4808 #v4.3.3
with:
name: ${{ steps.artifact.outputs.filename }}
path: ./intellij-plugin/build/distributions/content/*/*
diff --git a/.github/workflows/publish-ij-plugin-snapshot.yml b/.github/workflows/publish-ij-plugin-snapshot.yml
index 7e9486d1172..7678fb1a24d 100644
--- a/.github/workflows/publish-ij-plugin-snapshot.yml
+++ b/.github/workflows/publish-ij-plugin-snapshot.yml
@@ -5,16 +5,16 @@ on:
- cron: '0 0 * * 0'
workflow_dispatch:
env:
- GRADLE_ENTERPRISE_ACCESS_KEY: ${{ secrets.GRADLE_ENTERPRISE_ACCESS_KEY }}
+ DEVELOCITY_ACCESS_KEY: ${{ secrets.DEVELOCITY_ACCESS_KEY }}
jobs:
publish-intellij-plugin:
name: Publish IntelliJ plugin
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 #v4.1.1
+ - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 #v4.1.7
- - uses: actions/setup-java@387ac29b308b003ca37ba93a6cab5eb57c8f5f93 #v4.0.0
+ - uses: actions/setup-java@99b8673ff64fbf99d8d325f52d9a5bdedb8483e9 #v4.2.1
with:
distribution: 'temurin'
java-version: 17
diff --git a/.github/workflows/push.yml b/.github/workflows/push.yml
index 161b8755404..107a1eb9a18 100644
--- a/.github/workflows/push.yml
+++ b/.github/workflows/push.yml
@@ -7,19 +7,19 @@ on:
- 'docs/**'
- '*.md'
env:
- GRADLE_ENTERPRISE_ACCESS_KEY: ${{ secrets.GRADLE_ENTERPRISE_ACCESS_KEY }}
+ DEVELOCITY_ACCESS_KEY: ${{ secrets.DEVELOCITY_ACCESS_KEY }}
jobs:
deploy:
runs-on: macos-14
if: github.repository == 'apollographql/apollo-kotlin'
steps:
- - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 #v4.1.1
- - uses: actions/setup-java@387ac29b308b003ca37ba93a6cab5eb57c8f5f93 #v4.0.0
+ - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 #v4.1.7
+ - uses: actions/setup-java@99b8673ff64fbf99d8d325f52d9a5bdedb8483e9 #v4.2.1
with:
distribution: 'temurin'
java-version: 17
- - uses: gradle/gradle-build-action@42452daeb5b454a76f686a8e4de8234afd7b1f44 #v2.12.0
+ - uses: gradle/actions/setup-gradle@dbbdc275be76ac10734476cc723d82dfe7ec6eda #v3.4.2
with:
gradle-home-cache-cleanup: true
- name: Build with Gradle
@@ -35,13 +35,13 @@ jobs:
- name: Collect Diagnostics
if: always()
run: ./scripts/collect-diagnostics.main.kts
- - uses: actions/upload-artifact@26f96dfa697d77e81fd5907df203aa23a56210a8 #v4.3.0
+ - uses: actions/upload-artifact@65462800fd760344b1a7b4382951275a0abb4808 #v4.3.3
if: always()
with:
name: push.zip
path: diagnostics.zip
- name: Deploy Kdoc to github pages
- uses: JamesIves/github-pages-deploy-action@65b5dfd4f5bcd3a7403bbc2959c144256167464e #v4.5.0
+ uses: JamesIves/github-pages-deploy-action@5c6e9e9f3672ce8fd37b9856193d2a537941e66c #v4.6.1
with:
branch: gh-pages # The branch the action should deploy to.
folder: libraries/apollo-kdoc/build/dokka/html # The folder the action should deploy.
diff --git a/.github/workflows/tag.yml b/.github/workflows/tag.yml
index 5714097963b..9674ae5a978 100644
--- a/.github/workflows/tag.yml
+++ b/.github/workflows/tag.yml
@@ -5,7 +5,7 @@ on:
tags:
- '*'
env:
- GRADLE_ENTERPRISE_ACCESS_KEY: ${{ secrets.GRADLE_ENTERPRISE_ACCESS_KEY }}
+ DEVELOCITY_ACCESS_KEY: ${{ secrets.DEVELOCITY_ACCESS_KEY }}
jobs:
publish-libraries:
@@ -13,12 +13,12 @@ jobs:
runs-on: macos-14
if: github.repository == 'apollographql/apollo-kotlin'
steps:
- - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 #v4.1.1
- - uses: actions/setup-java@387ac29b308b003ca37ba93a6cab5eb57c8f5f93 #v4.0.0
+ - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 #v4.1.7
+ - uses: actions/setup-java@99b8673ff64fbf99d8d325f52d9a5bdedb8483e9 #v4.2.1
with:
distribution: 'temurin'
java-version: 17
- - uses: gradle/gradle-build-action@42452daeb5b454a76f686a8e4de8234afd7b1f44 #v2.12.0
+ - uses: gradle/actions/setup-gradle@dbbdc275be76ac10734476cc723d82dfe7ec6eda #v3.4.2
with:
gradle-home-cache-cleanup: true
#--no-configuration-cache for https://youtrack.jetbrains.com/issue/KT-65879
@@ -36,8 +36,8 @@ jobs:
name: Publish IntelliJ plugin
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 #v4.1.1
- - uses: actions/setup-java@387ac29b308b003ca37ba93a6cab5eb57c8f5f93 #v4.0.0
+ - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 #v4.1.7
+ - uses: actions/setup-java@99b8673ff64fbf99d8d325f52d9a5bdedb8483e9 #v4.2.1
with:
distribution: 'temurin'
java-version: 17
diff --git a/.idea/codeStyles/Project.xml b/.idea/codeStyles/Project.xml
index a5f2722fe66..d69494f0a95 100644
--- a/.idea/codeStyles/Project.xml
+++ b/.idea/codeStyles/Project.xml
@@ -25,6 +25,10 @@
+
+
+
+
@@ -58,7 +62,7 @@
-
+
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7a6c559fca7..27ae15562d4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,129 @@
Change Log
==========
+# Version 4.0.0-beta.7
+
+_2024-06-05_
+
+## K2
+
+#5931: This version is built with K2. You will need Kotlin 1.9+ on the JVM to build it and Kotlin 2.0 for other platforms.
+
+## ApolloCompilerPluginProvider
+
+#5865: `ApolloCompilerPluginProvider` is introduced to allow passing arguments to compiler plugins. See the [compiler plugins documentation](https://go.apollo.dev/ak-compiler-plugins) for more details.
+
+## ๐ทโ All changes
+* [testing] Use com.apollographql.mockserver.MockServer (#5939)
+* [testing] Simplify our implementation of runTest (#5935)
+* [testing] Prepare apollo-testing-support to new MockServer (#5934)
+* [runtime] Remove multidex library (#5930)
+* [all] Bump languageVersion/apiVersion to Kotlin 2.0 (#5931)
+* [codegen] fix mapping of the builtin Float type (#5928)
+* [IJ Plugin] Add inspection to warn about the presence of a GraphQL config file (#5908)
+* [codegen] Add a null-check to java enum safeValueOf (#5904)
+* [gradle-plugin] Remove eager configuration (#5923)
+* [gradle-plugin] sort input files (#5919)
+* [IJ Plugin] Suppress GraphQLDuplicateDirective for certain directives (#5910)
+* [adapters] Add KtorHttpUrlAdapter (#5915)
+* [IJ Plugin] Add a "new UI" compatible icon (#5906)
+* [IJ Plugin] Operation and fragment definition rename (#5912)
+* [IJ Plugin] Add @link directives to extra.graphqls during v3->v4 migration (#5909)
+* [IJ Plugin] Remove GraphQL IJ plugin issue workaround (#5907)
+* [cache] Pagination: use "field key" instead of "field name" (#5898)
+* [IJ Plugin] Improve the presentation of GraphQL elements when navigating to them (#5900)
+* [IJ Plugin] Include subfolders when contributing GraphQL config (#5871)
+* [runtime] Remove existing interceptors from ApolloClient.Builder before adding new ones (#5858)
+* [codegen] Add ApolloCompilerPluginProvider (#5865)
+* [runtime] Clear current ApolloStore related interceptors when calling `.store()` on builder (#5857)
+* [cache] Call through to loadRecords from the MemoryCache to the SQL one (#5848)
+* [runtime] deprecate operationIdGenerator (#5850)
+
+# Version 3.8.4
+
+_2024-04-29_
+
+Version 3.8.4 is a maintenance release with one bug fix and 2 performance improvements. New developments happen in the 4.x versions.
+
+* [java-runtime] Fix `ApolloClient.Builder.okHttpClient()` returns null instead of this (#5860)
+* [normalized-cache] Use a single transaction when using MemoryCache chaining (#5861)
+* [normalized-cache] Call through to loadRecords from the MemoryCache to the SQL one (#5863)
+
+# Version 4.0.0-beta.6
+
+_2024-04-23_
+
+## SQL cache performance improvements
+
+If you're using a chained memory + SQL cache, #5840 makes sure cache writes are wrapped in a transaction, making them much faster.
+
+## Apollo Compiler Plugins
+
+`Plugin` is renamed to `ApolloCompilerPlugin`. There is a new `documentTransform` API as well as other fixes. More details in the [compiler plugins documentation](https://www.apollographql.com/docs/kotlin/v4/advanced/compiler-plugins).
+
+## Experimental WebSockets
+
+A new `.websocket` package is available that makes it easier to retry WebSockets and handle errors. More details and migration guide in the [experimental websockets documentation](https://www.apollographql.com/docs/kotlin/v4/advanced/experimental-websockets).
+
+## ApolloIdlingResource is deprecated
+
+We recommend using reactive patterns to test your UI instead. See [this article about ways to do so](https://medium.com/androiddevelopers/alternatives-to-idling-resources-in-compose-tests-8ae71f9fc473).
+
+## Removed androidx.startup dependency
+
+androidx.startup was introduced in beta.5 but is problematic for unit tests and other cases. beta.6 removes that dependency. More details in the [network connectivity documentation](https://www.apollographql.com/docs/kotlin/v4/advanced/network-connectivity).
+
+## WasmJS support for apollo-adapter
+
+You can see Wasm in action at https://wasm.confetti-app.dev/
+
+## Threading changes
+
+In a effort to minimize the number of thread switches, the whole request is now run in the same dispatcher. See [Threading.md](https://github.com/apollographql/apollo-kotlin/blob/39d76630277476004bbaed0e3a897feb5a959084/design-docs/Threading.md) for more details.
+
+## Contributors ๐
+
+Many thanks to @joreilly, @ychescale9 and @japhib for their contributions to this release ๐!
+
+## ๐ทโ All changes
+* [normalized-cache]: use a single SQL transaction when using MemoryCache chaining (#5840)
+* [compiler] expose apollo-ast as an api dependency (#5838)
+* [compiler] Rename `Plugin` to `ApolloCompilerPlugin` and add error message for bad configurations (#5821)
+* [IJ Plugin] Fix pulling file from device not working on AS Koala (#5822)
+* [compiler] Add `@ApolloEnumConstructor` and make enum as sealed class Unknown constructor opt-in (#5813)
+* [runtime] Move ApolloParseException to ApolloNetworkException (#5816)
+* [normalized-cache] Let isFromCache be about the ApolloResponse (#5805)
+* [compiler] Add DocumentTransform API (#5809)
+* [idling-resource] Deprecate ApolloIdlingResource (#5817, #5764)
+* [runtime] Share the default OkHttpBuilder (#5811)
+* [runtime] [BREAKING] change `isOnline` to a suspend fun
+* [adapters] Support Kotlin/Wasm for apollo-adapters (#5803)
+* [all] Bump Kotlin to 2.0.0-RC1 (#5802)
+* [Codegen] Add CompiledArgumentDefinition (#5797, #5837)
+* [runtime] Merge experimental WebSocketNetworkTransport in apollo-runtime (#5790)
+* [normalized-cache] Cache pagination: add FieldNameGenerator and EmbeddedFieldsProvider (#5772)
+* [runtime] Support configuring `ApolloClient` with lazily initialized `Call.Factory`. (#5784)
+* [runtime] fix ApolloClient.Builder.okHttpClient() returns null instead of this (#5778)
+* [normalized-cache] Fix variable coercion in lists. Absent variables are coerced to null (#5773)
+* [IJ Plugin] Fix an NPE (#5770)
+* [runtime] Simplify ApolloCall (#5765)
+* [runtime] remove `androidx.startup` dependency (#5761, #5720)
+* [compiler] Bump kotlin_labs definitions to v0.3 (#5762)
+* [Pagination] Support nodes in Connection types (#5754)
+* [compiler] Directive validation is now enforced by default (#5758)
+* [cache] Make ApolloStore.publish() suspend (#5755)
+* [runtime] Change the dispatcher earlier in the chain (#4319)
+* [IJ Plugin] Add an advanced setting to include generated code references in GraphQL "Go To Declaration" (#5743)
+* [IJ Plugin] Fix presentation of Kotlin elements when navigating to them from GraphQL (#5739)
+* [IJ Plugin] Consider all Gradle projects recursively (#5734)
+* [runtime] Deprecate ApolloClient.Builder.addInterceptors() (#5733)
+* [all] use jdk-release (#5731)
+* [http-cache] Ignore IOException when calling ApolloHttpCache.remove (#5729)
+* [IJ plugin] Bump platformVersion and pluginSinceBuild from 232 to 233 (#5726)
+* [runtime] add ApolloClient.failFastIfOffline (#5725)
+* [all] Introduce "filesystem" sourceSet and use okio 3.9.0 (#5719)
+* [runtime] Do not use Ktor in Js HttpEngine, use fetch directly instead (#5702)
+
# Version 3.8.3
_2024-03-20_
diff --git a/README.md b/README.md
index c420e2b0bf6..67504272766 100644
--- a/README.md
+++ b/README.md
@@ -15,17 +15,17 @@
| :----- |
| What do you like best about Apollo Kotlin? What needs to be improved? Please tell us by taking a [one-minute survey](https://docs.google.com/forms/d/e/1FAIpQLSczNDXfJne3ZUOXjk9Ursm9JYvhTh1_nFTDfdq3XBAFWCzplQ/viewform?usp=pp_url&entry.1170701325=Apollo+Kotlin&entry.204965213=Readme). Your responses will help us understand Apollo Kotlin usage and allow us to serve you better. |
-Apollo Kotlin (formerly known as Apollo Android) is a GraphQL client that generates Kotlin and Java models from GraphQL queries.
+Apollo Kotlin (formerly Apollo Android) is a GraphQL client that generates Kotlin and Java models from GraphQL operations.
-Apollo Kotlin executes queries and mutations against a GraphQL server and returns results as query-specific Kotlin types. This means you don't have to deal with parsing JSON, or passing around `Map`s and making clients cast values to the right type manually. You also don't have to write model types yourself, because these are generated from the GraphQL definitions your UI uses.
+Apollo Kotlin executes operations against a GraphQL server and returns results as operation-specific Kotlin types. This means you don't have to deal with parsing JSON, or passing around `Map`s and making clients cast values to the right type manually. You also don't have to write model types yourself, because these are generated from the GraphQL definitions your app uses.
-Because generated types are query-specific, you can only access data that you actually specify as part of a query. If you don't ask for a particular field in a query, you can't access the corresponding property on the returned data structure.
+Because generated types are operation-specific, you can only access data that you actually specify as part of an operation. If you don't ask for a particular field in an operation, you can't access the corresponding property on the returned data structure.
-This library is designed primarily with Android in mind, but you can use it in any Java/Kotlin app, including multiplatform.
+This library is designed primarily with Android in mind, but you can use it in any Kotlin (including multiplatform) and Java app.
## Features
-* Java and Kotlin Multiplatform code generation
+* Kotlin Multiplatform and Java code generation
* Queries, Mutations and Subscriptions
* Reflection-free parsing
* Normalized cache
@@ -34,10 +34,10 @@ This library is designed primarily with Android in mind, but you can use it in a
* Auto Persisted Queries
* Query batching
* File uploads
-* Espresso IdlingResource
* Fake models for tests
* AppSync and graphql-ws websockets
* GraphQL AST parser
+* Plugin for Android Studio and IntelliJ
## Multiplatform
@@ -45,14 +45,14 @@ Apollo Kotlin is a [Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatf
Here's the current matrix of supported features per platform:
-| | `jvm` | `Appleยน` | `js` | `linuxX64`
-| --- | :---: | :---: |:----:| :---: |
-| `apollo-api` (models)|โ |โ | โ |โ |
-| `apollo-runtime` (network, query batching, apq, ...) |โ |โ | โ |๐ซ|
-| `apollo-normalized-cache` |โ |โ | โ |๐ซ|
-| `apollo-adapters` |โ |โ | โ |๐ซ|
-| `apollo-normalized-cache-sqlite` |โ |โ | ๐ซ |๐ซ|
-| `apollo-http-cache` |โ |๐ซ| ๐ซ |๐ซ|
+| | `jvm` | `Appleยน` | `js` | `wasmJs` | `linuxX64` |
+|------------------------------------------------------|:-----:|:--------:|:----:|:--------:|:----------:|
+| `apollo-api` (models) | โ | โ | โ | โ | โ |
+| `apollo-runtime` (network, query batching, apq, ...) | โ | โ | โ | โ | ๐ซ |
+| `apollo-normalized-cache` | โ | โ | โ | โ | ๐ซ |
+| `apollo-adapters` | โ | โ | โ | โ | ๐ซ |
+| `apollo-normalized-cache-sqlite` | โ | โ | ๐ซ | ๐ซ | ๐ซ |
+| `apollo-http-cache` | โ | ๐ซ | ๐ซ | ๐ซ | ๐ซ |
ยน: Apple currently includes:
@@ -80,7 +80,7 @@ Check [the project website](https://www.apollographql.com/docs/android/) for in
## Getting started
-If you are new to GraphQL, check out [the tutorial](https://www.apollographql.com/docs/android/tutorial/00-introduction/) that will guide you through building an Android app using Apollo, Kotlin and coroutines.
+If you are new to GraphQL, check out [the tutorial](https://www.apollographql.com/docs/android/tutorial/00-introduction/) that will guide you through building an Android app using Apollo.
If you'd like to add Apollo Kotlin to an existing project, follow these steps:
@@ -88,7 +88,7 @@ Add the plugin to your `build.gradle.kts`:
```kotlin
plugins {
- id("com.apollographql.apollo3") version "4.0.0-beta.5"
+ id("com.apollographql.apollo3") version "4.0.0-beta.7"
}
```
@@ -96,7 +96,7 @@ Add the runtime dependency:
```kotlin
dependencies {
- implementation("com.apollographql.apollo3:apollo-runtime:4.0.0-beta.5")
+ implementation("com.apollographql.apollo3:apollo-runtime:4.0.0-beta.7")
}
```
@@ -121,7 +121,7 @@ By default, Apollo Kotlin requires a schema in your module's `src/main/graphql`
cp ${schema} ${module}/src/main/graphql/
```
-Write a query in a `${module}/src/main/graphql/GetRepository.graphql` file:
+Write a query in a `${module}/src/main/graphql/HeroQuery.graphql` file:
```graphql
query HeroQuery($id: String!) {
@@ -164,9 +164,8 @@ Some platforms have specific runtime requirements:
At build time, it requires:
* Gradle 8.0+
-* Kotlin 1.8+ for JVM projects
-* Kotlin 1.9+ for native projects
-* Kotlin 2.0+ for JS projects
+* Kotlin 1.9+ for JVM projects
+* Kotlin 2.0+ for native, JS, and Wasm projects
## Proguard / R8 configuration
@@ -174,7 +173,7 @@ As the code generated by Apollo Kotlin doesn't use any reflection, it can safely
## Android Studio / IntelliJ plugin
-An experimental [plugin for Android Studio and IntelliJ](https://plugins.jetbrains.com/plugin/20645-apollo-graphql) is available to help you work with Apollo Kotlin, providing automatic code generation, integration with the [GraphQL IntelliJ Plugin](https://plugins.jetbrains.com/plugin/8097-js-graphql), navigation to GraphQL definitions, migration helpers, and more.
+A [plugin for Android Studio and IntelliJ](https://plugins.jetbrains.com/plugin/20645-apollo-graphql) is available to help you work with Apollo Kotlin, providing automatic code generation, integration with the [GraphQL IntelliJ Plugin](https://plugins.jetbrains.com/plugin/8097-js-graphql), navigation to GraphQL definitions, migration helpers, and more.
Installation instructions and more information can be found [here](https://github.com/apollographql/apollo-kotlin/tree/main/intellij-plugin).
@@ -188,7 +187,7 @@ Releases are hosted on [Maven Central](https://repo1.maven.org/maven2/com/apollo
```kotlin
plugins {
- id("com.apollographql.apollo3") version "4.0.0-beta.5"
+ id("com.apollographql.apollo3") version "4.0.0-beta.7"
}
repositories {
@@ -196,13 +195,13 @@ repositories {
}
dependencies {
- implementation("com.apollographql.apollo3:apollo-runtime:4.0.0-beta.5")
+ implementation("com.apollographql.apollo3:apollo-runtime:4.0.0-beta.7")
- // optional: if you want to use the normalized cache
- implementation("com.apollographql.apollo3:apollo-normalized-cache-sqlite:4.0.0-beta.5")
- // optional: if you just want the generated models and parsers and write your own HTTP code/cache code, you can remove apollo-runtime
+ // Optional: if you want to use the normalized cache
+ implementation("com.apollographql.apollo3:apollo-normalized-cache-sqlite:4.0.0-beta.7")
+ // Optional: if you just want the generated models and parsers and write your own HTTP code/cache code, you can remove apollo-runtime
// and use apollo-api instead
- implementation("com.apollographql.apollo3:apollo-api:4.0.0-beta.5")
+ implementation("com.apollographql.apollo3:apollo-api:4.0.0-beta.7")
}
```
@@ -233,7 +232,7 @@ pluginManagement {
}
```
-And then use the `4.0.0-beta.6-SNAPSHOT` version for the plugin and libraries.
+And then use the `4.0.0-beta.8-SNAPSHOT` version for the plugin and libraries.
These snapshots are updated on each push to `main`.
diff --git a/ROADMAP.md b/ROADMAP.md
index 295b4abb298..e9d64518c1a 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -1,6 +1,6 @@
# ๐ฎ Apollo Kotlin Roadmap
-**Last updated: 2024-04-19**
+**Last updated: 2024-05-16**
For up to date release notes, refer to the project [Changelog](https://github.com/apollographql/apollo-kotlin/blob/main/CHANGELOG.md).
diff --git a/benchmark/app/build.gradle.kts b/benchmark/app/build.gradle.kts
index 79841d12156..9a90b319aed 100644
--- a/benchmark/app/build.gradle.kts
+++ b/benchmark/app/build.gradle.kts
@@ -5,6 +5,7 @@ plugins {
id("com.android.application")
id("org.jetbrains.kotlin.android")
id("com.apollographql.apollo3")
+ alias(libs.plugins.kotlin.compose)
}
android {
@@ -43,10 +44,6 @@ android {
buildFeatures {
compose = true
}
-
- composeOptions {
- kotlinCompilerExtensionVersion = libs.versions.compose.compiler.get()
- }
}
dependencies {
diff --git a/benchmark/microbenchmark/build.gradle.kts b/benchmark/microbenchmark/build.gradle.kts
index 2e07e60b4af..9c22229e35e 100644
--- a/benchmark/microbenchmark/build.gradle.kts
+++ b/benchmark/microbenchmark/build.gradle.kts
@@ -21,40 +21,25 @@ configure {
sourceCompatibility = JavaVersion.VERSION_11
targetCompatibility = JavaVersion.VERSION_11
}
-
- flavorDimensions += "stability"
- productFlavors {
- create("incubating") {
- dimension = "stability"
- testApplicationId = "com.apollographql.apollo3.benchmark.incubating"
- }
- create("stable") {
- dimension = "stability"
- testApplicationId = "com.apollographql.apollo3.benchmark.stable"
- }
- }
}
dependencies {
- implementation("com.apollographql.apollo3:apollo-runtime")
-
- listOf(
- "com.apollographql.apollo3:apollo-normalized-cache-api",
- "com.apollographql.apollo3:apollo-normalized-cache-sqlite",
- "com.apollographql.apollo3:apollo-normalized-cache"
- ).forEach {
- add("androidTestStableImplementation", it)
- add("androidTestIncubatingImplementation", "$it-incubating")
- }
+ implementation(libs.apollo.runtime)
implementation(libs.moshi)
ksp(libs.moshix.ksp)
androidTestImplementation(libs.benchmark.junit4)
androidTestImplementation(libs.androidx.test.core)
- androidTestImplementation("com.apollographql.apollo3:apollo-mockserver")
- androidTestImplementation("com.apollographql.apollo3:apollo-testing-support")
+ androidTestImplementation(libs.apollo.mockserver)
+ androidTestImplementation(libs.apollo.testingsupport)
+
+ // Stable cache
+ androidTestImplementation(libs.apollo.normalizedcache.sqlite)
+
+ // Incubating cache
+ androidTestImplementation(libs.apollo.normalizedcache.sqlite.incubating.snapshot)
}
java {
diff --git a/benchmark/microbenchmark/src/androidTestIncubating/kotlin/com/apollographql/apollo3/benchmark/ApolloStoreIncubatingTests.kt b/benchmark/microbenchmark/src/androidTest/java/com/apollographql/apollo3/benchmark/ApolloStoreIncubatingTests.kt
similarity index 88%
rename from benchmark/microbenchmark/src/androidTestIncubating/kotlin/com/apollographql/apollo3/benchmark/ApolloStoreIncubatingTests.kt
rename to benchmark/microbenchmark/src/androidTest/java/com/apollographql/apollo3/benchmark/ApolloStoreIncubatingTests.kt
index ef5301c931a..16f7d1bffd6 100644
--- a/benchmark/microbenchmark/src/androidTestIncubating/kotlin/com/apollographql/apollo3/benchmark/ApolloStoreIncubatingTests.kt
+++ b/benchmark/microbenchmark/src/androidTest/java/com/apollographql/apollo3/benchmark/ApolloStoreIncubatingTests.kt
@@ -8,10 +8,10 @@ import com.apollographql.apollo3.benchmark.Utils.dbName
import com.apollographql.apollo3.benchmark.Utils.operationBasedQuery
import com.apollographql.apollo3.benchmark.Utils.resource
import com.apollographql.apollo3.benchmark.test.R
-import com.apollographql.apollo3.cache.normalized.ApolloStore
-import com.apollographql.apollo3.cache.normalized.api.MemoryCacheFactory
-import com.apollographql.apollo3.cache.normalized.api.NormalizedCacheFactory
-import com.apollographql.apollo3.cache.normalized.sql.SqlNormalizedCacheFactory
+import com.apollographql.cache.normalized.ApolloStore
+import com.apollographql.cache.normalized.api.MemoryCacheFactory
+import com.apollographql.cache.normalized.api.NormalizedCacheFactory
+import com.apollographql.cache.normalized.sql.SqlNormalizedCacheFactory
import org.junit.Assert
import org.junit.Rule
import org.junit.Test
diff --git a/benchmark/microbenchmark/src/androidTestStable/kotlin/com/apollographql/apollo3/benchmark/ApolloStoreTests.kt b/benchmark/microbenchmark/src/androidTest/java/com/apollographql/apollo3/benchmark/ApolloStoreTests.kt
similarity index 97%
rename from benchmark/microbenchmark/src/androidTestStable/kotlin/com/apollographql/apollo3/benchmark/ApolloStoreTests.kt
rename to benchmark/microbenchmark/src/androidTest/java/com/apollographql/apollo3/benchmark/ApolloStoreTests.kt
index 20b1f79f4c2..5743fb08ffd 100644
--- a/benchmark/microbenchmark/src/androidTestStable/kotlin/com/apollographql/apollo3/benchmark/ApolloStoreTests.kt
+++ b/benchmark/microbenchmark/src/androidTest/java/com/apollographql/apollo3/benchmark/ApolloStoreTests.kt
@@ -50,7 +50,7 @@ class ApolloStoreTests {
threadPool.submit {
// Let each thread execute a few writes/reads
repeat(WORK_LOAD) {
- apolloStore.writeOperation(query, data)
+ apolloStore.writeOperationSync(query, data)
val data2 = apolloStore.readOperation(query)
Assert.assertEquals(data, data2)
}
diff --git a/benchmark/microbenchmark/src/androidTestIncubating/kotlin/com/apollographql/apollo3/benchmark/CacheIncubatingIntegrationTests.kt b/benchmark/microbenchmark/src/androidTest/java/com/apollographql/apollo3/benchmark/CacheIncubatingIntegrationTests.kt
similarity index 82%
rename from benchmark/microbenchmark/src/androidTestIncubating/kotlin/com/apollographql/apollo3/benchmark/CacheIncubatingIntegrationTests.kt
rename to benchmark/microbenchmark/src/androidTest/java/com/apollographql/apollo3/benchmark/CacheIncubatingIntegrationTests.kt
index f3f5bb40391..4b259c5d878 100644
--- a/benchmark/microbenchmark/src/androidTestIncubating/kotlin/com/apollographql/apollo3/benchmark/CacheIncubatingIntegrationTests.kt
+++ b/benchmark/microbenchmark/src/androidTest/java/com/apollographql/apollo3/benchmark/CacheIncubatingIntegrationTests.kt
@@ -9,17 +9,17 @@ import com.apollographql.apollo3.benchmark.Utils.dbName
import com.apollographql.apollo3.benchmark.Utils.operationBasedQuery
import com.apollographql.apollo3.benchmark.Utils.resource
import com.apollographql.apollo3.benchmark.test.R
-import com.apollographql.apollo3.cache.normalized.ApolloStore
-import com.apollographql.apollo3.cache.normalized.FetchPolicy
-import com.apollographql.apollo3.cache.normalized.api.MemoryCacheFactory
-import com.apollographql.apollo3.cache.normalized.api.NormalizedCacheFactory
-import com.apollographql.apollo3.cache.normalized.fetchPolicy
-import com.apollographql.apollo3.cache.normalized.sql.SqlNormalizedCacheFactory
-import com.apollographql.apollo3.cache.normalized.store
-import com.apollographql.apollo3.mockserver.MockRequestBase
-import com.apollographql.apollo3.mockserver.MockResponse
-import com.apollographql.apollo3.mockserver.MockServer
-import com.apollographql.apollo3.mockserver.MockServerHandler
+import com.apollographql.cache.normalized.ApolloStore
+import com.apollographql.cache.normalized.FetchPolicy
+import com.apollographql.cache.normalized.api.MemoryCacheFactory
+import com.apollographql.cache.normalized.api.NormalizedCacheFactory
+import com.apollographql.cache.normalized.fetchPolicy
+import com.apollographql.cache.normalized.sql.SqlNormalizedCacheFactory
+import com.apollographql.cache.normalized.store
+import com.apollographql.mockserver.MockRequestBase
+import com.apollographql.mockserver.MockResponse
+import com.apollographql.mockserver.MockServer
+import com.apollographql.mockserver.MockServerHandler
import com.apollographql.apollo3.testing.MapTestNetworkTransport
import com.apollographql.apollo3.testing.registerTestResponse
import kotlinx.coroutines.joinAll
diff --git a/benchmark/microbenchmark/src/androidTestIncubating/kotlin/com/apollographql/apollo3/benchmark/CacheIncubatingTests.kt b/benchmark/microbenchmark/src/androidTest/java/com/apollographql/apollo3/benchmark/CacheIncubatingTests.kt
similarity index 80%
rename from benchmark/microbenchmark/src/androidTestIncubating/kotlin/com/apollographql/apollo3/benchmark/CacheIncubatingTests.kt
rename to benchmark/microbenchmark/src/androidTest/java/com/apollographql/apollo3/benchmark/CacheIncubatingTests.kt
index c0c606b3599..c4ea6d1c08d 100644
--- a/benchmark/microbenchmark/src/androidTestIncubating/kotlin/com/apollographql/apollo3/benchmark/CacheIncubatingTests.kt
+++ b/benchmark/microbenchmark/src/androidTest/java/com/apollographql/apollo3/benchmark/CacheIncubatingTests.kt
@@ -2,10 +2,7 @@ package com.apollographql.apollo3.benchmark
import androidx.benchmark.junit4.BenchmarkRule
import androidx.benchmark.junit4.measureRepeated
-import androidx.test.platform.app.InstrumentationRegistry
import com.apollographql.apollo3.api.CustomScalarAdapters
-import com.apollographql.apollo3.api.Executable
-import com.apollographql.apollo3.api.Operation
import com.apollographql.apollo3.api.Query
import com.apollographql.apollo3.api.json.jsonReader
import com.apollographql.apollo3.api.parseJsonResponse
@@ -16,26 +13,20 @@ import com.apollographql.apollo3.benchmark.Utils.registerCacheSize
import com.apollographql.apollo3.benchmark.Utils.resource
import com.apollographql.apollo3.benchmark.Utils.responseBasedQuery
import com.apollographql.apollo3.benchmark.test.R
-import com.apollographql.apollo3.cache.normalized.api.CacheHeaders
-import com.apollographql.apollo3.cache.normalized.api.CacheKeyGenerator
-import com.apollographql.apollo3.cache.normalized.api.CacheResolver
-import com.apollographql.apollo3.cache.normalized.api.DefaultRecordMerger
-import com.apollographql.apollo3.cache.normalized.api.FieldPolicyCacheResolver
-import com.apollographql.apollo3.cache.normalized.api.MemoryCacheFactory
-import com.apollographql.apollo3.cache.normalized.api.ReadOnlyNormalizedCache
-import com.apollographql.apollo3.cache.normalized.api.Record
-import com.apollographql.apollo3.cache.normalized.api.TypePolicyCacheKeyGenerator
-import com.apollographql.apollo3.cache.normalized.api.normalize
-import com.apollographql.apollo3.cache.normalized.api.readDataFromCache
-import com.apollographql.apollo3.cache.normalized.sql.SqlNormalizedCacheFactory
+import com.apollographql.cache.normalized.api.CacheHeaders
+import com.apollographql.cache.normalized.api.DefaultRecordMerger
+import com.apollographql.cache.normalized.api.FieldPolicyCacheResolver
+import com.apollographql.cache.normalized.api.MemoryCacheFactory
+import com.apollographql.cache.normalized.api.TypePolicyCacheKeyGenerator
+import com.apollographql.cache.normalized.api.normalize
+import com.apollographql.cache.normalized.api.readDataFromCache
+import com.apollographql.cache.normalized.sql.SqlNormalizedCacheFactory
import kotlinx.coroutines.runBlocking
import org.junit.Assert
import org.junit.Rule
import org.junit.Test
-import java.lang.reflect.Method
import java.util.concurrent.Executors
-@Suppress("UNCHECKED_CAST")
class CacheIncubatingTests {
@get:Rule
val benchmarkRule = BenchmarkRule()
@@ -158,4 +149,4 @@ class CacheIncubatingTests {
private const val CONCURRENCY = 15
private const val WORK_LOAD = 15
}
-}
\ No newline at end of file
+}
diff --git a/benchmark/microbenchmark/src/androidTestStable/kotlin/com/apollographql/apollo3/benchmark/CacheIntegrationTests.kt b/benchmark/microbenchmark/src/androidTest/java/com/apollographql/apollo3/benchmark/CacheIntegrationTests.kt
similarity index 94%
rename from benchmark/microbenchmark/src/androidTestStable/kotlin/com/apollographql/apollo3/benchmark/CacheIntegrationTests.kt
rename to benchmark/microbenchmark/src/androidTest/java/com/apollographql/apollo3/benchmark/CacheIntegrationTests.kt
index a088efaed44..4a14ae376fd 100644
--- a/benchmark/microbenchmark/src/androidTestStable/kotlin/com/apollographql/apollo3/benchmark/CacheIntegrationTests.kt
+++ b/benchmark/microbenchmark/src/androidTest/java/com/apollographql/apollo3/benchmark/CacheIntegrationTests.kt
@@ -16,10 +16,10 @@ import com.apollographql.apollo3.cache.normalized.api.NormalizedCacheFactory
import com.apollographql.apollo3.cache.normalized.fetchPolicy
import com.apollographql.apollo3.cache.normalized.sql.SqlNormalizedCacheFactory
import com.apollographql.apollo3.cache.normalized.store
-import com.apollographql.apollo3.mockserver.MockRequestBase
-import com.apollographql.apollo3.mockserver.MockResponse
-import com.apollographql.apollo3.mockserver.MockServer
-import com.apollographql.apollo3.mockserver.MockServerHandler
+import com.apollographql.mockserver.MockRequestBase
+import com.apollographql.mockserver.MockResponse
+import com.apollographql.mockserver.MockServer
+import com.apollographql.mockserver.MockServerHandler
import com.apollographql.apollo3.testing.MapTestNetworkTransport
import com.apollographql.apollo3.testing.registerTestResponse
import kotlinx.coroutines.joinAll
diff --git a/benchmark/microbenchmark/src/androidTestStable/kotlin/com/apollographql/apollo3/benchmark/CacheTests.kt b/benchmark/microbenchmark/src/androidTest/java/com/apollographql/apollo3/benchmark/CacheTests.kt
similarity index 100%
rename from benchmark/microbenchmark/src/androidTestStable/kotlin/com/apollographql/apollo3/benchmark/CacheTests.kt
rename to benchmark/microbenchmark/src/androidTest/java/com/apollographql/apollo3/benchmark/CacheTests.kt
diff --git a/benchmark/microbenchmark/src/androidTestStable/kotlin/com/apollographql/apollo3/benchmark/JsonTests.kt b/benchmark/microbenchmark/src/androidTest/java/com/apollographql/apollo3/benchmark/JsonTests.kt
similarity index 100%
rename from benchmark/microbenchmark/src/androidTestStable/kotlin/com/apollographql/apollo3/benchmark/JsonTests.kt
rename to benchmark/microbenchmark/src/androidTest/java/com/apollographql/apollo3/benchmark/JsonTests.kt
diff --git a/benchmark/settings.gradle.kts b/benchmark/settings.gradle.kts
index 948ad2898a5..3d1b8b0d7d2 100644
--- a/benchmark/settings.gradle.kts
+++ b/benchmark/settings.gradle.kts
@@ -2,8 +2,8 @@ pluginManagement {
includeBuild("build-logic")
}
plugins {
- id("com.gradle.develocity") version "3.17.2" // sync with libraries.toml
- id("com.gradle.common-custom-user-data-gradle-plugin") version "2.0.1"
+ id("com.gradle.develocity") version "3.17.5" // sync with libraries.toml
+ id("com.gradle.common-custom-user-data-gradle-plugin") version "2.0.2"
id("org.gradle.toolchains.foojay-resolver-convention") version "0.8.0"
}
@@ -23,9 +23,9 @@ apply(from = "../gradle/ge.gradle")
listOf(pluginManagement.repositories, dependencyResolutionManagement.repositories).forEach {
it.apply {
maven {
- url = uri("../build/localMaven")
+ url = uri("https://s01.oss.sonatype.org/content/repositories/snapshots/")
}
}
}
-includeBuild("../")
\ No newline at end of file
+includeBuild("../")
diff --git a/build-logic/build.gradle.kts b/build-logic/build.gradle.kts
index 97e86200629..8ad9afaa2af 100644
--- a/build-logic/build.gradle.kts
+++ b/build-logic/build.gradle.kts
@@ -22,6 +22,7 @@ dependencies {
implementation(libs.kotlinx.benchmark)
implementation(libs.dokkatoo)
+ implementation(libs.apollo.execution.gradle.plugin)
// We add all the plugins to the classpath here so that they are loaded with proper conflict resolution
// See https://github.com/gradle/gradle/issues/4741
diff --git a/build-logic/settings.gradle.kts b/build-logic/settings.gradle.kts
index c7ce3ed431e..b443e588d2d 100644
--- a/build-logic/settings.gradle.kts
+++ b/build-logic/settings.gradle.kts
@@ -1,6 +1,6 @@
plugins {
- id("com.gradle.develocity") version "3.17.2" // sync with libraries.toml
- id("com.gradle.common-custom-user-data-gradle-plugin") version "2.0.1"
+ id("com.gradle.develocity") version "3.17.5" // sync with libraries.toml
+ id("com.gradle.common-custom-user-data-gradle-plugin") version "2.0.2"
id("org.gradle.toolchains.foojay-resolver-convention") version "0.8.0"
}
diff --git a/build-logic/src/main/kotlin/Android.kt b/build-logic/src/main/kotlin/Android.kt
index d48af7eee16..46f60a73b13 100644
--- a/build-logic/src/main/kotlin/Android.kt
+++ b/build-logic/src/main/kotlin/Android.kt
@@ -41,6 +41,4 @@ fun Project.configureAndroid(
}
}
}
-
- dependencies.add("implementation", getCatalogLib("androidx.multidex"))
}
diff --git a/build-logic/src/main/kotlin/CompilerOptions.kt b/build-logic/src/main/kotlin/CompilerOptions.kt
index 084c347423d..9a49436adf2 100644
--- a/build-logic/src/main/kotlin/CompilerOptions.kt
+++ b/build-logic/src/main/kotlin/CompilerOptions.kt
@@ -16,14 +16,22 @@ import org.jetbrains.kotlin.gradle.dsl.KotlinJvmProjectExtension
import org.jetbrains.kotlin.gradle.dsl.KotlinMultiplatformExtension
import org.jetbrains.kotlin.gradle.dsl.KotlinNativeCompilerOptions
import org.jetbrains.kotlin.gradle.dsl.KotlinProjectExtension
-import org.jetbrains.kotlin.gradle.dsl.KotlinVersion
import org.jetbrains.kotlin.gradle.plugin.KotlinPlatformType
import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
/**
* @param target the JVM version we want to be compatible with (bytecode + bootstrap classpath)
*/
-fun KotlinCommonCompilerOptions.configure(target: Int) {
+fun KotlinCommonCompilerOptions.configure(target: Int, kotlinCompilerOptions: KotlinCompilerOptions, isAndroid: Boolean) {
+ val actualTarget = when {
+ isAndroid -> {
+ // https://blog.blundellapps.co.uk/setting-jdk-level-in-android-gradle-builds/
+ // D8 can dex Java17 bytecode
+ 17
+ }
+ else -> target
+ }
+
freeCompilerArgs.add("-Xexpect-actual-classes")
/**
@@ -34,14 +42,17 @@ fun KotlinCommonCompilerOptions.configure(target: Int) {
freeCompilerArgs.add("-opt-in=com.apollographql.apollo3.annotations.ApolloExperimental")
freeCompilerArgs.add("-opt-in=com.apollographql.apollo3.annotations.ApolloInternal")
- apiVersion.set(KotlinVersion.KOTLIN_1_9)
- languageVersion.set(KotlinVersion.KOTLIN_1_9)
+ apiVersion.set(kotlinCompilerOptions.version)
+ languageVersion.set(kotlinCompilerOptions.version)
when (this) {
is KotlinJvmCompilerOptions -> {
freeCompilerArgs.add("-Xjvm-default=all")
- freeCompilerArgs.add("-Xjdk-release=${target.toJvmTarget().target}")
- jvmTarget.set(target.toJvmTarget())
+ if (!isAndroid) {
+ // See https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-main:build-system/gradle-core/src/main/java/com/android/build/gradle/tasks/JavaCompileUtils.kt;l=410?q=Using%20%27--release%27%20option%20for%20JavaCompile%20is%20not%20supported%20because%20it%20prevents%20the%20Android%20Gradle%20plugin
+ freeCompilerArgs.add("-Xjdk-release=${actualTarget.toJvmTarget().target}")
+ }
+ jvmTarget.set(actualTarget.toJvmTarget())
}
is KotlinNativeCompilerOptions -> {
@@ -94,21 +105,12 @@ val Project.androidExtensionOrNull: BaseExtension?
return (extensions.findByName("android") as? BaseExtension)
}
-fun Project.configureJavaAndKotlinCompilers(jvmTarget: Int?) {
+fun Project.configureJavaAndKotlinCompilers(jvmTarget: Int?, kotlinCompilerOptions: KotlinCompilerOptions) {
@Suppress("NAME_SHADOWING")
val jvmTarget = jvmTarget?: 8
kotlinExtensionOrNull?.forEachCompilerOptions { isAndroid ->
- val target = when {
- isAndroid -> {
- // https://blog.blundellapps.co.uk/setting-jdk-level-in-android-gradle-builds/
- // D8 can dex Java17 bytecode
- 17
- }
- else -> jvmTarget
- }
-
- configure(target)
+ configure(jvmTarget, kotlinCompilerOptions, isAndroid)
}
project.tasks.withType(JavaCompile::class.java).configureEach {
// For JVM only modules, this dictates the "org.gradle.jvm.version" Gradle attribute
diff --git a/build-logic/src/main/kotlin/Mpp.kt b/build-logic/src/main/kotlin/Mpp.kt
index 5a6cb070878..cabe19d194b 100644
--- a/build-logic/src/main/kotlin/Mpp.kt
+++ b/build-logic/src/main/kotlin/Mpp.kt
@@ -120,29 +120,29 @@ fun Project.configureMpp(
* Current Graph is something like so:
*
* ```mermaid
- * graph TB
- * commonMain --> concurrentMain
- * commonMain --> linuxMain
- * commonMain --> jsMain
- * concurrentMain --> jvmMain
- * concurrentMain --> appleMain
- * appleMain --> macosX64
- * appleMain --> macosArm64
- * appleMain --> iosArm64
- * appleMain --> iosX64
- * appleMain --> iosSimulatorArm64
- * appleMain --> watchosArm32
- * appleMain --> watchosArm64
- * appleMain --> watchosSimulatorArm64
- * appleMain --> tvosArm64
- * appleMain --> tvosX64
- * appleMain --> tvosSimulatorArm64
- *
- * classDef kotlinPurple fill:#A97BFF,stroke:#333,stroke-width:2px,color:#333
- * classDef javaOrange fill:#b07289,stroke:#333,stroke-width:2px,color:#333
- * classDef gray fill:#AAA,stroke:#333,stroke-width:2px,color:#333
- * class jvmJavaCodeGen,macOsArm64Test,jvmTest,jsTest kotlinPurple
- * class commonTest javaOrange
+ * graph
+ * common --> fileSystem
+ * fileSystem --> concurrent
+ * fileSystem --> jsCommon
+ * concurrent --> native
+ * concurrent --> jvmCommon
+ * jsCommon --> js
+ * jsCommon --> wasmJs
+ * jvmCommon --> jvm
+ * jvmCommon --> android
+ * native --> linux
+ * native --> apple
+ * apple --> macosX64
+ * apple --> macosArm64
+ * apple --> iosArm64
+ * apple --> iosX64
+ * apple --> iosSimulatorArm64
+ * apple --> watchosArm32
+ * apple --> watchosArm64
+ * apple --> watchosSimulatorArm64
+ * apple --> tvosArm64
+ * apple --> tvosX64
+ * apple --> tvosSimulatorArm64
* ```
*/
@OptIn(ExperimentalKotlinGradlePluginApi::class)
diff --git a/build-logic/src/main/kotlin/Testing.kt b/build-logic/src/main/kotlin/Testing.kt
index bdae5755861..cc60ac2d4c2 100644
--- a/build-logic/src/main/kotlin/Testing.kt
+++ b/build-logic/src/main/kotlin/Testing.kt
@@ -1,4 +1,4 @@
-import com.gradle.enterprise.gradleplugin.testretry.retry
+import com.gradle.develocity.agent.gradle.test.DevelocityTestConfiguration
import org.gradle.api.Project
import org.gradle.api.tasks.PathSensitivity
import org.gradle.api.tasks.testing.AbstractTestTask
@@ -14,10 +14,10 @@ fun Project.configureTesting() {
forwardEnv("testFilter")
forwardEnv("codegenModels")
}
-
+
pluginManager.withPlugin("org.jetbrains.kotlin.jvm") {
tasks.withType(Test::class.java) {
- retry {
+ extensions.getByType(DevelocityTestConfiguration::class.java).testRetry {
if (isCIBuild()) {
maxRetries.set(3)
failOnPassedAfterRetry.set(true)
@@ -54,6 +54,7 @@ private fun Project.addTestDependencies() {
}
}
}
+
is KotlinJvmProjectExtension -> {
dependencies.add("testImplementation", getCatalogLib("kotlin.test"))
}
diff --git a/build-logic/src/main/kotlin/api.kt b/build-logic/src/main/kotlin/api.kt
index ab02a117159..0ef1a972959 100644
--- a/build-logic/src/main/kotlin/api.kt
+++ b/build-logic/src/main/kotlin/api.kt
@@ -1,15 +1,19 @@
-
import org.gradle.api.Project
import org.gradle.api.Task
import org.gradle.api.tasks.TaskProvider
import org.gradle.jvm.tasks.Jar
import org.jetbrains.kotlin.gradle.dsl.KotlinMultiplatformExtension
+import org.jetbrains.kotlin.gradle.dsl.KotlinVersion
import org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsRootExtension
import org.jetbrains.kotlin.gradle.targets.js.nodejs.NodeJsRootPlugin
import org.jetbrains.kotlin.gradle.targets.js.npm.tasks.KotlinNpmInstallTask
class AndroidOptions(
- val withCompose: Boolean
+ val withCompose: Boolean,
+)
+
+class KotlinCompilerOptions(
+ val version: KotlinVersion = KotlinVersion.KOTLIN_2_0,
)
fun Project.apolloLibrary(
@@ -21,7 +25,8 @@ fun Project.apolloLibrary(
withJvm: Boolean = true,
withWasm: Boolean = true,
androidOptions: AndroidOptions? = null,
- publish: Boolean = true
+ publish: Boolean = true,
+ kotlinCompilerOptions: KotlinCompilerOptions = KotlinCompilerOptions(),
) {
group = property("GROUP")!!
version = property("VERSION_NAME")!!
@@ -30,7 +35,7 @@ fun Project.apolloLibrary(
configureAndroid(namespace, androidOptions)
}
commonSetup()
- configureJavaAndKotlinCompilers(jvmTarget)
+ configureJavaAndKotlinCompilers(jvmTarget, kotlinCompilerOptions)
addOptIn(
"com.apollographql.apollo3.annotations.ApolloExperimental",
@@ -74,9 +79,10 @@ fun Project.apolloTest(
withJvm: Boolean = true,
appleTargets: Set = setOf(hostTarget),
browserTest: Boolean = false,
+ kotlinCompilerOptions: KotlinCompilerOptions = KotlinCompilerOptions(),
) {
commonSetup()
- configureJavaAndKotlinCompilers(null)
+ configureJavaAndKotlinCompilers(null, kotlinCompilerOptions)
addOptIn(
"com.apollographql.apollo3.annotations.ApolloExperimental",
"com.apollographql.apollo3.annotations.ApolloInternal",
diff --git a/build.gradle.kts b/build.gradle.kts
index 625f9d2f9bb..27128de78fe 100644
--- a/build.gradle.kts
+++ b/build.gradle.kts
@@ -1,4 +1,5 @@
import JapiCmp.configureJapiCmp
+import kotlinx.validation.ExperimentalBCVApi
import org.jetbrains.kotlin.gradle.targets.native.tasks.KotlinNativeHostTest
plugins {
@@ -85,9 +86,6 @@ tasks.register("ciTestsNoGradle") {
* Update the database schemas in CI
*/
dependsOn(":apollo-normalized-cache-sqlite:generateCommonMainJsonDatabaseSchema")
- dependsOn(":apollo-normalized-cache-sqlite-incubating:generateCommonMainJsonDatabaseSchema")
- dependsOn(":apollo-normalized-cache-sqlite-incubating:generateCommonMainBlobDatabaseSchema")
- dependsOn(":apollo-normalized-cache-sqlite-incubating:generateCommonMainBlob2DatabaseSchema")
doLast {
if (isCIBuild()) {
@@ -122,6 +120,9 @@ rootProject.configureNode()
rootProject.configureJapiCmp()
configure {
+ @OptIn(ExperimentalBCVApi::class)
+ klib.enabled = true
+
ignoredPackages.addAll(
listOf(
/**
@@ -168,4 +169,4 @@ tasks.register("rmbuild") {
}
}
-apolloRoot(ciBuild)
\ No newline at end of file
+apolloRoot(ciBuild)
diff --git a/design-docs/Glossary.md b/design-docs/Glossary.md
index fcc41654bf2..860d3a2a9b9 100644
--- a/design-docs/Glossary.md
+++ b/design-docs/Glossary.md
@@ -1,9 +1,6 @@
-# Codegen Glossary
-
-## Glossary
-
-A small Glossary of the terms used during codegen. The [GraphQL Spec](https://spec.graphql.org/draft/) does a nice job of defining the common terms like `Field`, `SelectionSet`, etc... so I'm not adding these terms here. But it misses some concepts that we bumped into during codegen and that I'm trying to clarify here.
+# Glossary
+The [GraphQL Spec](https://spec.graphql.org/draft/) does a nice job of defining common terms like `Field`, `SelectionSet`, etc. but here are a few other concepts that the library deals with, and their definition.
### Response shape
@@ -105,3 +102,26 @@ Example:
### Polymorphic field
A field that can take several shapes
+
+### Record
+
+A shallow map of a response object. Nested objects in the map values are replaced by a cache reference to another Record.
+
+### Cache key
+
+A unique identifier for a Record.
+By default it is the path formed by all the field keys from the root of the query to the field referencing the Record.
+To avoid duplication the Cache key can also be computed from the Record contents, usually using its key fields.
+
+### Field key
+
+A key that uniquely identifies a field within a Record. By default composed of the field name and the arguments passed to it.
+
+### Key fields
+
+Fields that are used to compute a Cache key for an object.
+
+### Pagination arguments
+
+Field arguments that control pagination, e.g. `first`, `after`, etc. They should be omitted when computing a field key so different pages can be merged into the same field.
+
diff --git a/design-docs/Normalized cache overview.md b/design-docs/Normalized cache overview.md
index 7ba4fb34712..6bd1b52e692 100644
--- a/design-docs/Normalized cache overview.md
+++ b/design-docs/Normalized cache overview.md
@@ -93,7 +93,7 @@ An example:
-
Key
+
Cache key
Record
@@ -217,7 +217,7 @@ An instance is created when building the `ApolloClient` and held by the `ApolloC
## Record merging
-When a `Record` is stored in the cache, it is _merged_ with the existing one at the same key (if any):
+When a `Record` is stored in the cache, it is _merged_ with the existing one at the same cache key (if any):
- existing fields are replaced with the new value
- new fields are added
diff --git a/design-docs/Normalized cache pagination.md b/design-docs/Normalized cache pagination.md
index 6fa93fadffc..3311d071ebd 100644
--- a/design-docs/Normalized cache pagination.md
+++ b/design-docs/Normalized cache pagination.md
@@ -210,7 +210,7 @@ If your schema uses a different pagination style, you can still use the paginati
#### Pagination arguments
-The `@fieldPolicy` directive has a `paginationArgs` argument that can be used to specify the arguments that should be omitted from the cache key.
+The `@fieldPolicy` directive has a `paginationArgs` argument that can be used to specify the arguments that should be omitted from the field key.
Going back to the example above with `usersPage`:
@@ -220,6 +220,9 @@ extend type Query
@fieldPolicy(forField: "usersPage" paginationArgs: "page")
```
+> [!NOTE]
+> This can also be done programmatically by configuring the `ApolloStore` with a `FieldKeyGenerator` implementation.
+
With that in place, after fetching the first page, the cache will look like this:
| Cache Key | Record |
@@ -228,7 +231,7 @@ With that in place, after fetching the first page, the cache will look like this
| user:1 | id: 1, name: John Smith |
| user:2 | id: 2, name: Jane Doe |
-Notice how the cache key no longer includes the `page` argument, which means watching `UsersPage(page = 1)` (or any page) is enough to observe the whole list.
+The field key no longer includes the `page` argument, which means watching `UsersPage(page = 1)` or any page will observe the same list.
Here's what happens when fetching the second page:
@@ -240,13 +243,13 @@ Here's what happens when fetching the second page:
| user:3 | id: 3, name: Peter Parker |
| user:4 | id: 4, name: Bruce Wayne |
-We can see that the field containing the first page was overwritten by the second page.
+The field containing the first page was overwritten by the second page.
-This is because the cache key is now the same for all pages.
+This is because the field key is now the same for all pages and the default merging strategy is to overwrite existing fields with the new value.
#### Record merging
-To fix this we need to supply the store with a piece of code that can merge new pages with the existing list.
+To fix this we need to supply the store with a piece of code that can merge the lists in a sensible way.
This is done by passing a `RecordMerger` to the `ApolloStore` constructor:
```kotlin
@@ -266,11 +269,11 @@ val apolloStore = ApolloStore(
normalizedCacheFactory = cacheFactory,
cacheKeyGenerator = TypePolicyCacheKeyGenerator,
apolloResolver = FieldPolicyApolloResolver,
- recordMerger = FieldRecordMerger(MyFieldMerger)
+ recordMerger = FieldRecordMerger(MyFieldMerger), // Configure the store with the custom merger
)
```
-With this, the cache will look like this after fetching the second page:
+With this, the cache will be as expected after fetching the second page:
| Cache Key | Record |
|------------|-------------------------------------------------------------------------------|
@@ -280,13 +283,13 @@ With this, the cache will look like this after fetching the second page:
| user:3 | id: 3, name: Peter Parker |
| user:4 | id: 4, name: Bruce Wayne |
-The `RecordMerger` shown above is simplistic: it can only append new pages to the end of the existing list.
-
-A more sophisticated implementation could look at the contents of the incoming page and decide where to append / insert the items into the existing list.
+The `RecordMerger` shown above is simplistic: it will always append new items to the end of the existing list.
+In a real app, we need to look at the contents of the incoming page and decide if and where to append / insert the items.
-To do that it is often necessary to have access to the arguments used to fetch a record inside the `RecordMerger`, to decide where to insert the new items.
+To do that it is usually necessary to have access to the arguments that were used to fetch the existing/incoming lists (e.g. the page number), to decide what to do with the new items.
+For instance if the existing list is for page 1 and the incoming one is for page 2, we should append.
-Fields in records can actually have arbitrary metadata associated with them, in addition to their values. We'll use this to implement more sophisticated merging.
+Fields in records can have arbitrary metadata attached to them, in addition to their value. We'll use this to implement a more capable merging strategy.
#### Metadata
@@ -307,10 +310,10 @@ This is done by passing a `MetadataGenerator` to the `ApolloStore` constructor:
```kotlin
class ConnectionMetadataGenerator : MetadataGenerator {
@Suppress("UNCHECKED_CAST")
- override fun metadataForObject(obj: Any?, context: MetadataGeneratorContext): Map {
+ override fun metadataForObject(obj: ApolloJsonElement, context: MetadataGeneratorContext): Map {
if (context.field.type.rawType().name == "UserConnection") {
- obj as Map
- val edges = obj["edges"] as List>
+ obj as Map
+ val edges = obj["edges"] as List>
val startCursor = edges.firstOrNull()?.get("cursor") as String?
val endCursor = edges.lastOrNull()?.get("cursor") as String?
return mapOf(
@@ -325,35 +328,46 @@ class ConnectionMetadataGenerator : MetadataGenerator {
}
```
-However, this cannot work yet.
-Normalization will make the `edges` field value be a list of **references** to the `UserEdge` records, and not the actual edges - so the
-cast in `val edges = obj["edges"] as List>` will fail.
+However, this cannot work yet.
+
+Normalization will make the `usersConnection` field value be a **reference** to the `UserConnection` record, and not the actual connection.
+Because of this, we won't be able to access its metadata inside the `RecordMerger` implementation.
+Furthermore, the `edges` field value will be a list of **references** to the `UserEdge` records which will contain the item's list index in their cache key (e.g. `usersConnection.edges.0`, `usersConnection.edges.1`) which will break the merging logic.
#### Embedded fields
-To remediate this, we can use `embeddedFields` to configure the cache to skip normalization and store the actual list of edges instead of references:
+To remediate this, we can configure the cache to skip normalization for certain fields. When doing so, the value will be embedded directly into the record instead of being referenced.
+
+This is done with the `embeddedFields` argument of the `@typePolicy` directive:
```graphql
+# Embed the value of the `usersConnection` field in the record
+extend type Query @typePolicy(embeddedFields: "usersConnection")
+
+# Embed the values of the `edges` field in the record
extend type UserConnection @typePolicy(embeddedFields: "edges")
```
-Now that we have the metadata in place, we can access it inside the `RecordMerger` (simplified for brevity):
+> [!NOTE]
+> This can also be done programmatically by configuring the `ApolloStore` with an `EmbeddedFieldsProvider` implementation.
+
+Now that we have the metadata and embedded fields in place, we can implement the `RecordMerger` (simplified for brevity):
```kotlin
object ConnectionFieldMerger : FieldRecordMerger.FieldMerger {
@Suppress("UNCHECKED_CAST")
override fun mergeFields(existing: FieldRecordMerger.FieldInfo, incoming: FieldRecordMerger.FieldInfo): FieldRecordMerger.FieldInfo {
- // Get existing record metadata
+ // Get existing field metadata
val existingStartCursor = existing.metadata["startCursor"]
val existingEndCursor = existing.metadata["endCursor"]
- // Get incoming record metadata
+ // Get incoming field metadata
val incomingBeforeArgument = incoming.metadata["before"]
val incomingAfterArgument = incoming.metadata["after"]
- // Get values
- val existingList = (existing.value as Map)["edges"] as List<*>
- val incomingList = (incoming.value as Map)["edges"] as List<*>
+ // Get the lists
+ val existingList = (existing.value as Map)["edges"] as List<*>
+ val incomingList = (incoming.value as Map)["edges"] as List<*>
// Merge the lists
val mergedList: List<*> = if (incomingAfterArgument == existingEndCursor) {
diff --git a/design-docs/Threading.md b/design-docs/Threading.md
index 732b5dabea1..17c96f33a7a 100644
--- a/design-docs/Threading.md
+++ b/design-docs/Threading.md
@@ -16,7 +16,7 @@ Most of the above steps need to happen in a background thread as they are potent
## Mutable, shared state that requires synchronization
-Some state in the pipeline is shared require synchronisation:
+Some state in the pipeline is shared and requires synchronisation:
* Normalized cache
* Store listeners
@@ -37,3 +37,9 @@ that would mean that we pay the context switching price in all cases and also th
nothing so a coroutine is way more efficient there.
**On the JVM**, there are less restrictions. OkHttp has as synchronous API that [has proven to be quite efficient](https://github.com/grpc/grpc-java/issues/6696)/
+
+## Current state
+
+The dispatcher is changed very early in the chain. On the JVM, everything runs synchronously from that dispatcher.
+
+The only thing happening before the dispatcher change is notification of the ApolloIdlingResources that need to happen from the same call stack. ApolloIdlingResource is deprecated and that should be removed when ApolloIdlingResource goes away.
\ No newline at end of file
diff --git a/docs/source/_redirects b/docs/source/_redirects
index 4c1ede579a3..da381c32645 100644
--- a/docs/source/_redirects
+++ b/docs/source/_redirects
@@ -19,3 +19,4 @@
/advanced/test-builders/ /docs/kotlin/testing/test-builders/
/advanced/response-based-codegen/ /docs/kotlin/advanced/response-based/
/advanced/codegen-methods/ /docs/kotlin/advanced/response-based/
+/advanced/source-sets/ /docs/kotlin/advanced/plugin-configuration/#wiring-generated-sources
diff --git a/docs/source/advanced/apollo-ast.mdx b/docs/source/advanced/apollo-ast.mdx
index 96c8aa211ab..84668615e74 100644
--- a/docs/source/advanced/apollo-ast.mdx
+++ b/docs/source/advanced/apollo-ast.mdx
@@ -4,7 +4,7 @@ title: Apollo AST
To generate client code, Apollo Kotlin parses both your GraphQL schema _and_ each operation you write against it into an **Abstract Syntax Tree** ([AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree)). An AST represents a GraphQL document in a type-safe, machine-readable format.
-Apollo Kotlin's parser has its own module (`apollo-ast`), which you can use independently of `apollo-runtime` or `apollo-api`.
+The Apollo Kotlin parser has its own artifact (`apollo-ast`), which you can use independently of `apollo-runtime` or `apollo-api`.
Features of `apollo-ast` include:
@@ -21,7 +21,7 @@ Add the `apollo-ast` dependency to your project:
dependencies {
// ...
- implementation("com.apollographql.apollo3:apollo-ast:4.0.0-beta.5")
+ implementation("com.apollographql.apollo3:apollo-ast:4.0.0-beta.7")
}
```
@@ -29,7 +29,7 @@ dependencies {
Use the `parseAsGQLDocument` method to parse a document from a `File`, a `String`, or an Okio [`BufferedSource`](https://square.github.io/okio/3.x/okio/okio/okio/-buffered-source/index.html).
-```kotlin {12}
+```kotlin {13}
val graphQLText = """
query HeroForEpisode(${"$"}ep: Episode) {
hero(episode: ${"$"}ep) {
diff --git a/docs/source/advanced/authentication.mdx b/docs/source/advanced/authentication.mdx
index a0643e708aa..517c821aa16 100644
--- a/docs/source/advanced/authentication.mdx
+++ b/docs/source/advanced/authentication.mdx
@@ -2,13 +2,13 @@
title: Authenticate your operations
---
-> Authentication is not included in the GraphQL specification. This page aims at giving some guidance for the most common scenarios but doesn't pretend to be exhaustive.
+> Authentication is not included in the GraphQL specification. This page aims at giving some guidance for the most common scenarios but doesn't intend to be exhaustive.
## Authenticating your HTTP requests with OkHttp
[OkHttp Interceptors](https://square.github.io/okhttp/features/interceptors/) are an easy way to add an `"Authorization"` header to your HTTP requests.
-OkHttp Interceptors have been around for a long time and work well but only work on Android and the JVM.
+OkHttp Interceptors have been around for a long time and work well but can only be used with Apollo Kotlin on Android and the JVM.
## Authenticating your HTTP requests with Apollo HttpInterceptor
@@ -69,10 +69,10 @@ Alternatively, you can also send headers in the initial WebSocket handshake requ
```kotlin
val apolloClient = ApolloClient.Builder()
- .httpServerUrl("http://localhost:8080/graphql")
+ .httpServerUrl("https://example.com/graphql")
.subscriptionNetworkTransport(
WebSocketNetworkTransport.Builder()
- .serverUrl("http://localhost:8080/subscriptions")
+ .serverUrl("https://example.com/subscriptions")
.addHeader("Authorization", authorization) // highlight-line
.build()
)
@@ -83,7 +83,11 @@ val apolloClient = ApolloClient.Builder()
When using authenticated subscriptions over WebSockets, you might want to refresh your authentication token because it was invalidated or simply because it expired.
-> Note: if your user logged out, you might want to consider creating a new `ApolloClient` instead. This will make sure that all other state besides the WebSocket, like cache for an example, is new and not shared amongst different users.
+
+
+If your user logged out, you might want to consider creating a new `ApolloClient` instead. This will make sure that all other state besides the WebSocket, like cache for an example, is new and not shared amongst different users.
+
+
Sometimes the websocket will emit an error that you can use in `webSocketReopenWhen` to create a new WebSocket. Other times that information will come from elsewhere in your app and you will have to force disconnect the WebSocket.
diff --git a/docs/source/advanced/client-awareness.mdx b/docs/source/advanced/client-awareness.mdx
index 33296a67426..b8cf3c4e293 100644
--- a/docs/source/advanced/client-awareness.mdx
+++ b/docs/source/advanced/client-awareness.mdx
@@ -6,7 +6,7 @@ GraphOS Studio users can opt-in [Client Awareness](https://www.apollographql.com
Client Awareness uses `apollographql-client-name` and `apollographql-client-version` custom HTTP headers to report client usage.
-Enable it by adding an `ApolloClientAwarenessInterceptor` to your `OkHttpClient`:
+Enable it by adding an `ApolloClientAwarenessInterceptor` to your `ApolloClient`:
```kotlin
val apolloClient = ApolloClient.Builder()
@@ -15,4 +15,6 @@ val apolloClient = ApolloClient.Builder()
.build()
```
-**Note**: This example uses `BuildConfig` to set the applicationId as client name and app version as client version but you can override this. Especially, if your iOS and Android apps use the same package name, it's useful to customize it to allow differentiating the clients
+
+This example uses `BuildConfig` to set the app's `applicationId` as the client name and its `versionName` as the client version, but you can override this. Especially, if your iOS and Android apps use the same package name, it's useful to customize it to be able to differentiate the clients.
+
diff --git a/docs/source/advanced/compiler-plugins.mdx b/docs/source/advanced/compiler-plugins.mdx
index ce68930aafc..e5a7ee6d291 100644
--- a/docs/source/advanced/compiler-plugins.mdx
+++ b/docs/source/advanced/compiler-plugins.mdx
@@ -2,6 +2,12 @@
title: Apollo compiler plugins
---
+
+
+**Compiler plugins are currently [experimental](https://www.apollographql.com/docs/resources/release-stages/#experimental-features) in Apollo Kotlin.** If you have feedback on them, please let us know via [GitHub issues](https://github.com/apollographql/apollo-kotlin/issues/new?assignees=&labels=Type%3A+Bug&template=bug_report.md) or in the [Kotlin Slack community](https://slack.kotl.in/).
+
+
+
The Apollo compiler supports [a wide range of options](../advanced/plugin-configuration). For the cases where these options are not enough, you can use Apollo compiler plugins to modify the behaviour of the compiler.
Apollo compiler plugins allow to:
@@ -11,13 +17,13 @@ Apollo compiler plugins allow to:
* Transform the JavaPoet/KotlinPoet models.
* Transform the Apollo IR.
-# Implementing a compiler plugin
+## Implementing a compiler plugin
In this example we will implement a plugin that uses custom [persisted queries](../advanced/persisted-queries) ids registered on your backend.
The Apollo compiler use the [ServiceLoader API](https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html) to load plugins at runtime. Plugins need to be implemented in a separate module that is added to the classpath.
-To start, create a new Gradle module and add `apollo-compiler` as a dependency to the module `build.gradle[.kts]` file. In this example, we'll use `apollo-compiler-plugin` for the module name:
+To start, create a new Gradle module and add `apollo-compiler` as a dependency to the module `build.gradle[.kts]` file. In this example, we'll use `apollo-compiler-plugin` as module name:
```kotlin
// apollo-compiler-plugin/build.gradle.kts
@@ -27,7 +33,7 @@ plugins {
dependencies {
// Add apollo-compiler as a dependency
- implementation("com.apollographql.apollo3:apollo-compiler:4.0.0-beta.4")
+ implementation("com.apollographql.apollo3:apollo-compiler:4.0.0-beta.7")
}
```
@@ -37,11 +43,11 @@ Next create your plugin in a `src/main/kotlin/mypackage/MyPlugin` file:
package mypackage
import com.apollographql.apollo3.compiler.OperationOutputGenerator
-import com.apollographql.apollo3.compiler.Plugin
+import com.apollographql.apollo3.compiler.ApolloCompilerPlugin
import com.apollographql.apollo3.compiler.operationoutput.OperationDescriptor
import com.apollographql.apollo3.compiler.operationoutput.OperationId
-class MyPlugin: Plugin {
+class MyPlugin: ApolloCompilerPlugin {
override fun operationIds(descriptors: List): List {
// This assumes the returned ids are in the same order as the descriptors
return registerOperations(descriptors).withIndex().map { OperationId(it.value, descriptors[it.index].name) }
@@ -56,16 +62,28 @@ class MyPlugin: Plugin {
}
```
-Make your plugin discoverable by [ServiceLoader](https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html) using a resource in `src/main/resources/META-INF/services/com.apollographql.apollo3.compiler.Plugin`. This file contains the fully qualified name of your plugin:
+Next, create an `ApolloCompilerPluginProvider`. This is the entry point of compiler plugins. It is loaded using the [ServiceLoader](https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html) API.
+
+```kotlin
+class MyPluginProvider: ApolloCompilerPluginProvider {
+ override fun create(environment: ApolloCompilerPluginEnvironment): ApolloCompilerPlugin {
+ return MyPlugin()
+ }
+}
+```
+
+Make your plugin discoverable by [ServiceLoader](https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html) by adding a resource in `src/main/resources/META-INF/services/com.apollographql.apollo3.compiler.ApolloCompilerPluginProvider`. This file contains the fully qualified name of your plugin:
```
-mypackage.MyPlugin
+mypackage.MyPluginProvider
```
-> [!NOTE]
-> The name of the resource file is important. It must be `com.apollographql.apollo3.compiler.Plugin` and be in the `META-INF/services` folder. This is how `ServiceLoader` looks up `Plugins` at runtime.
+
-# Adding a plugin to the Apollo compiler classpath
+The name of the resource file is important. It must be `com.apollographql.apollo3.compiler.ApolloCompilerPluginProvider` and be in the `META-INF/services` folder. This is how `ServiceLoader` looks up plugins at runtime.
+
+
+## Adding a plugin to the Apollo compiler classpath
Use the `Service.plugin()` Gradle method to add the plugin to the Apollo compiler classpath:
@@ -88,8 +106,46 @@ apollo {
The plugin code will now be invoked the next time the compiler is invoked.
-# Other references
+## Passing arguments to your Apollo compiler plugin
+
+Because the compiler plugin runs in an isolated classpath, you can't use classes or data from your main build logic classpath.
+
+In order to pass build-time arguments to your Apollo compiler plugin, use the `argument()` function:
+
+```kotlin
+apollo {
+ service("service") {
+ packageName.set("com.example")
+
+ // Add your plugin to the Apollo compiler classpath
+ plugin(project(":apollo-compiler-plugin")) {
+ argument("token", token) // highlight-line
+ }
+ }
+}
+```
+
+The arguments are available in `ApolloCompilerPluginEnvironment.arguments`:
+
+```kotlin
+class MyPluginProvider: ApolloCompilerPluginProvider {
+ override fun create(environment: ApolloCompilerPluginEnvironment): ApolloCompilerPlugin {
+ return MyPlugin(environment.arguments.get("token") as String)
+ }
+}
+```
+
+Arguments must be serializable and be instances of classes accessible from the bootstrap classloader. In practice, built-in types and collections are supported.
+
+## Limitations
+
+Because codegen is run in a separate classloader when using compiler plugins, it's not possible to use `packageNameGenerator`, `operationIdGenerator` or `operationOutputGenerator` at the same time as compiler plugins. If you want to use them, you'll have to:
+
+* use `ApolloCompilerPlugin.layout()` instead of `packageNameGenerator`
+* use `ApolloCompilerPlugin.operationIds()` instead of `operationIdGenerator` and `operationOutputGenerator`
+
+## Other references
-For other plugin APIs like layout, IR, JavaPoet and KotlinPoet transforms, check out the [Plugin API docs](https://www.apollographql.com/docs/kotlin/kdoc/apollo-compiler/com.apollographql.apollo3.compiler/-plugin/index.html)
+For other plugin APIs like layout, IR, JavaPoet and KotlinPoet transforms, check out the [ApolloCompilerPlugin API docs](https://www.apollographql.com/docs/kotlin/kdoc/apollo-compiler/com.apollographql.apollo3.compiler/-apollo-compiler-plugin/index.html)
-For more examples, check out the [integration-tests](https://github.com/apollographql/apollo-kotlin/tree/main/tests/compiler-plugins).
\ No newline at end of file
+For more examples, check out the [integration-tests](https://github.com/apollographql/apollo-kotlin/tree/main/tests/compiler-plugins).
diff --git a/docs/source/advanced/experimental-websockets.mdx b/docs/source/advanced/experimental-websockets.mdx
new file mode 100644
index 00000000000..9a538650b4a
--- /dev/null
+++ b/docs/source/advanced/experimental-websockets.mdx
@@ -0,0 +1,129 @@
+---
+title: Experimental WebSockets
+---
+
+
+
+**The experimental WebSockets implementation are currently [experimental](https://www.apollographql.com/docs/resources/release-stages/#experimental-features) in Apollo Kotlin.** If you have feedback on them, please let us know via [GitHub issues](https://github.com/apollographql/apollo-kotlin/issues/new?assignees=&labels=Type%3A+Bug&template=bug_report.md) or in the [Kotlin Slack community](https://slack.kotl.in/).
+
+
+
+Historically, WebSockets have been one of the most complex and error-prone parts of Apollo Kotlin because:
+
+1. The WebSocket transport protocol has no official specification and different implementations have different behaviours.
+2. WebSockets are stateful and making them work using the old Kotlin native memory model was challenging.
+3. Because WebSockets are long-lived connections, they are more exposed to errors and knowing when (or if) to retry is hard.
+4. Not all subscriptions happen on WebSockets. Some use [HTTP multipart](https://www.apollographql.com/docs/router/executing-operations/subscription-multipart-protocol/) for an example.
+
+Starting with 4.0.0, Apollo Kotlin provides a new `com.apollographql.apollo3.network.websocket` package containing new `WebSocketNetworkTransport` and `WebSocketEngine` implementations (instead of `com.apollographql.apollo3.network.ws` for the current implementations).
+
+The `com.apollographql.apollo3.network.websocket` implementation provides the following:
+
+1. Defaults to the [graphql-ws](https://github.com/enisdenjo/graphql-ws/blob/master/PROTOCOL.md) protocol, which has become the de facto standard. Using the other protocols is still possible but having a main, specified, protocol ensures we can write a good and solid test suite.
+2. Does not inherit from the old memory model design, making the code considerably simpler. In particular, `WebSocketEngine` is now event based and no attempt at flow control is done. If you buffers grow too much, your subscription fails.
+3. Plays nicely with the ApolloClient `retryOnError` API.
+4. Handles different Subscription transports more consistently.
+
+## Status
+
+While they are `@ApolloExperimental`, we believe the new `.websocket` APIS to be more robust than the non-experimental `.ws` ones. They are safe to use in non-lib use cases.
+
+The "experimental" tag is to account for required API breaking changes based on community feedback. Ideally no change will be needed.
+
+After a feedback phase, the current `.ws` APIs will become deprecated and the `.websocket` one promoted to stable by removing the `@ApolloExperimental` annotations.
+
+## Migration guide
+
+In simple cases where you did not configure the underlying `WsProtocol` or retry logic, the migration should be about replacing `com.apollographql.apollo3.network.ws` with `com.apollographql.apollo3.network.websocket` everywhere:
+
+```kotlin
+// Replace
+import com.apollographql.apollo3.network.ws.WebSocketNetworkTransport
+import com.apollographql.apollo3.network.ws.WebSocketEngine
+// etc...
+
+// With
+import com.apollographql.apollo3.network.websocket.WebSocketNetworkTransport
+import com.apollographql.apollo3.network.websocket.WebSocketEngine
+// etc...
+```
+
+Because we can't remove the current APIs just yet, the `ApolloClient.Builder` shortcut APIs are still pointing to the `.ws` implementations. To use the newer `.websocket` implementation, pass a `websocket.WebSocketNetworkTransport` directly:
+
+```kotlin
+// Replace
+val apolloClient = ApolloClient.Builder()
+ .serverUrl(serverUrl)
+ .webSocketServerUrl(webSocketServerUrl)
+ .webSocketEngine(myWebSocketEngine)
+ .webSocketIdleTimeoutMillis(10_000)
+ .build()
+
+// With
+import com.apollographql.apollo3.network.websocket.*
+
+// [...]
+
+ApolloClient.Builder()
+ .serverUrl(serverUrl)
+ .subscriptionNetworkTransport(
+ WebSocketNetworkTransport.Builder()
+ .serverUrl(webSocketServerUrl)
+ // If you didn't set a WsProtocol before, make sure to include this
+ .wsProtocol(SubscriptionWsProtocol())
+ // If you were already using GraphQLWsProtocol, this is now the default
+ //.wsProtocol(GraphQLWsProtocol())
+ .webSocketEngine(myWebSocketEngine)
+ .idleTimeoutMillis(10_000)
+ .build()
+ )
+ .build()
+```
+
+To account for non-websocket transports, like [multipart subscriptions](https://www.apollographql.com/docs/router/executing-operations/subscription-multipart-protocol/), the retry is now handled on the `ApolloClient` instead of the `NetworkTransport`.
+
+```kotlin
+// Replace
+val apolloClient = ApolloClient.Builder()
+ .subscriptionNetworkTransport(
+ WebSocketNetworkTransport.Builder()
+ .serverUrl(url)
+ .reopenWhen { _, _ ->
+ delay(1000)
+ true
+ }
+ .build()
+ )
+
+// With
+val apolloClient = ApolloClient.Builder()
+ .subscriptionNetworkTransport(
+ WebSocketNetworkTransport.Builder()
+ .serverUrl(url)
+ .build()
+ )
+ // Only retry subscriptions
+ .retryOnError { it.operation is Subscription }
+```
+
+The above uses the default retry algorithm:
+
+* Wait until the network is available if you configured a [NetworkMonitor](network-connectivity).
+* Or use exponential backoff else.
+
+To customize the retry logic more, use `addRetryOnErrorInterceptor`:
+
+```kotlin
+val apolloClient = ApolloClient.Builder()
+ .subscriptionNetworkTransport(
+ WebSocketNetworkTransport.Builder()
+ .serverUrl(url)
+ .build()
+ )
+ .addRetryOnErrorInterceptor { exception, attempt ->
+ // retry logic here
+
+ // return true to retry or false to terminate the Flow
+ true
+ }
+```
diff --git a/docs/source/advanced/http-engine.mdx b/docs/source/advanced/http-engine.mdx
index 19174079be6..6ee027dac5e 100644
--- a/docs/source/advanced/http-engine.mdx
+++ b/docs/source/advanced/http-engine.mdx
@@ -4,15 +4,39 @@ title: Using a custom HTTP client
By default, Apollo Kotlin uses the following HTTP clients for different platforms/languages:
-| Platform | HTTP Client |
-|----------|-------------|
-| Android | [OkHttp](https://square.github.io/okhttp/) |
-| JavaScript | [Ktor](https://ktor.io/) |
-| iOS/MacOS | [NSURLSesssion](https://developer.apple.com/documentation/foundation/nsurlsession) |
+| Platform | HTTP Client |
+|-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Android/JVM | [OkHttp](https://square.github.io/okhttp/) |
+| JavaScript/Wasm | [fetch()](https://developer.mozilla.org/en-US/docs/Web/API/fetch) / [Node Fetch](https://www.npmjs.com/package/node-fetch) for HTTP, [Ktor](https://ktor.io/) for WebSockets |
+| iOS/MacOS | [NSURLSesssion](https://developer.apple.com/documentation/foundation/nsurlsession) |
-You can use a different HTTP client with Apollo Kotlin by creating a custom class that implements the `HttpEngine` interface.
-## The `HttpEngine` interface
+## Ktor engine
+
+Additionally, an optional implementation based on [Ktor](https://ktor.io/) for all targets is available in the `apollo-engine-ktor` module. To use it, add the following dependency to your project:
+
+```kotlin title="build.gradle[.kts]"
+dependencies {
+ // ...
+ implementation("com.apollographql.apollo3:apollo-engine-ktor:4.0.0-beta.7")
+}
+```
+
+And configure your `ApolloClient` to use the Ktor engine:
+
+```kotlin
+val client = ApolloClient.Builder()
+ .serverUrl("https://example.com/graphql")
+ // Create a new Ktor engine
+ .httpEngine(KtorHttpEngine())
+ // Or, if you want to reuse an existing Ktor client
+ .ktorClient(myKtorClient)
+ .build()
+```
+
+## Implement your own HTTP engine
+
+You can use a different HTTP client with Apollo Kotlin by creating a custom class that implements the `HttpEngine` interface.
The [HttpEngine interface](https://apollographql.github.io/apollo-kotlin/kdoc/apollo-runtime/com.apollographql.apollo3.network.http/-http-engine/index.html)
defines two functions: `execute` and `close`. Here's an example implementation that also includes a couple of helper
@@ -63,14 +87,14 @@ class MyHttpEngine(val wrappedClient: MyClient) : HttpEngine {
This example uses an asynchronous `wrappedClient` that runs the network request in a separate thread. Note that because `HttpEngine.execute` itself is called from a background thread, you can safely block in `execute()`.
-## Using your `HttpEngine`
+### Using your `HttpEngine`
After you create your `HttpEngine` implementation, you can register it with your [`ApolloClient`](https://apollographql.github.io/apollo-kotlin/kdoc/apollo-runtime/com.apollographql.apollo3/-apollo-client/index.html) instance using [`ApolloClient.Builder.httpEngine`](https://apollographql.github.io/apollo-kotlin/kdoc/apollo-runtime/com.apollographql.apollo3/-apollo-client/-builder/http-engine.html):
```kotlin
// Use your HttpEngine
val client = ApolloClient.Builder()
- .serverUrl(serverUrl = "https://com.example/graphql")
+ .serverUrl(serverUrl = "https://example.com/graphql")
.httpEngine(httpEngine = MyHttpEngine(wrappedClient))
.build()
```
diff --git a/docs/source/advanced/java.mdx b/docs/source/advanced/java.mdx
index 0cd6c1e2afd..60ec6e494a1 100644
--- a/docs/source/advanced/java.mdx
+++ b/docs/source/advanced/java.mdx
@@ -1,76 +1,5 @@
---
-title: Using with Java
+title: Using Java
---
-This article describes how to use Apollo Kotlin in Java projects.
-
-## Use the Java codegen
-
-Apollo Kotlin generates Kotlin code by default, but you can configure it to use the Java codegen instead:
-
-```kotlin title="build.gradle[.kts]"
-apollo {
- service("service") {
- generateKotlinModels.set(false)
- }
-}
-```
-
-## The Java runtime
-
-The default runtime for Apollo Kotlin, `apollo-runtime`, exposes a coroutines / Flow-based API that isn't well suited to be consumed from Java.
-That is why a specific runtime, `apollo-runtime-java` is available to use Apollo Kotlin from Java. To use it, add a dependency on this runtime instead of the default one:
-
-```kotlin title="build.gradle[.kts]"
-dependencies {
- // ...
-
- // Use apollo-runtime-java instead of apollo-runtime
- implementation("com.apollographql.apollo3:apollo-runtime-java:4.0.0-beta.5")
-}
-```
-
-The Java runtime has a callbacks based API. This snippet demonstrates initializing and using an `ApolloClient` in Java:
-
-```java
-import com.apollographql.apollo3.runtime.java.ApolloClient;
-// (...)
-
-ApolloClient client = ApolloClient.Builder builder = new ApolloClient.Builder()
- .serverUrl("http://localhost:4000/graphql")
- .build();
-
-// Use enqueue to execute a query asynchronously
-apolloClient.query(new GetRandomQuery()).enqueue(response -> {
- if (response.data != null) {
- // No errors
- System.out.println(response.data);
- } else {
- // Errors
- if (response.exception instanceof ApolloGraphQLException) {
- // GraphQL errors
- System.out.println(((ApolloGraphQLException) response.exception).getErrors().get(0));
- } else {
- // Network error
- response.exception.printStackTrace();
- }
- }
-});
-```
-
-Note that as of now, the Java runtime doesn't support the Http or Normalized caches.
-
-### Cancelling requests
-
-`euqueue` returns an `ApolloDisposable` that can be used to cancel the request:
-
-```java
-ApolloDisposable disposable = apolloClient.subscription(new MyQuery()).enqueue(response -> ...)
-// ...
-disposable.dispose();
-
-```
-
-### RxJava extensions
-
-If your project uses RxJava, you can use Apollo's [RxJava extensions](./rxjava/) with the Java runtime.
+To use Apollo Kotlin in Java projects, please refer to the dedicated Java Support repository [documentation](https://apollographql.github.io/apollo-kotlin-java-support/).
diff --git a/docs/source/advanced/js-interop.mdx b/docs/source/advanced/js-interop.mdx
index 3eb83840178..472682b45bb 100644
--- a/docs/source/advanced/js-interop.mdx
+++ b/docs/source/advanced/js-interop.mdx
@@ -20,7 +20,11 @@ To work around this, Apollo Kotlin provides two alternative solutions to work wi
the [@JsExport](https://kotlinlang.org/docs/js-to-kotlin-interop.html#jsexport-annotation) annotation so that the
dynamic JS object is callable from Kotlin directly.
-> โน๏ธ `JsExport` is an experimental feature in Kotlin and Apollo Kotlin and may change in future versions.
+
+
+**`JsExport` is currently [experimental](https://www.apollographql.com/docs/resources/release-stages/#experimental-features) in Apollo Kotlin.** If you have feedback on it, please let us know via [GitHub issues](https://github.com/apollographql/apollo-kotlin/issues/new?assignees=&labels=Type%3A+Bug&template=bug_report.md) or in the [Kotlin Slack community](https://slack.kotl.in/).
+
+
Because it bypasses the Kotlin type system, using `jsExport` comes with limitations.
See [Limitations](#Limitations) for more details.
@@ -50,8 +54,7 @@ expect suspend fun JsonHttpClient.executeApolloOperation(
): D?
```
-For non-JS implementations, implement `executeApolloOperation` using your favorite HTTP client (
-see [no-runtime](no-runtime)) and `parseJsonResponse`:
+For non-JS implementations, implement `executeApolloOperation` using your favorite HTTP client (see [Using the models without apollo-runtime](no-runtime)) and `parseJsonResponse`:
```kotlin
// non-js implementation
@@ -68,8 +71,7 @@ actual suspend fun JsonHttpClient.executeApolloOperation(
}
```
-On JS, you can use `fetch` and `unsafeCast()` to cast the returned javascript object into the @JsExport responseBased
-model:
+On JS, you can use `fetch` and `unsafeCast()` to cast the returned javascript object into the `@JsExport` responseBased model:
```kotlin
// js implementation
@@ -91,8 +93,7 @@ actual suspend fun JsonHttpClient.executeApolloOperation(
}
```
-For a more complete example see [this gist](https://gist.github.com/baconz/778e8a0b359267292d6e05ad81c19b90) which uses
-ktor for non-JS clients.
+For a more complete example see [this gist](https://gist.github.com/baconz/778e8a0b359267292d6e05ad81c19b90) which uses Ktor for non-JS clients.
### How it works
@@ -147,9 +148,8 @@ class Point {
```
To work around this, you need to tell the compiler not to mangle property names, which you can do by annotating the
-class
-with `JsExport`. When you set the `jsExport` option on your service, you tell Apollo to annotate each generated
-class with `JsExport` so that the property names are not mangled, and you can safely cast.
+class with `@JsExport`. When you set the `jsExport` option on your service, you tell Apollo to annotate each generated
+class with `@JsExport` so that the property names are not mangled, and you can safely cast.
### Accessors and Polymorphism
@@ -188,14 +188,14 @@ when (animal.__typename) {
### Limitations
-* `JsExport` is an experimental feature in Kotlin and Apollo Kotlin and may change in future versions.
-* `JsExport` only makes sense on response based codegen since it requires the Kotlin models to have the same shape as
+* `@JsExport` is an experimental feature in Kotlin and Apollo Kotlin and may change in future versions.
+* `@JsExport` only makes sense on response based codegen since it requires the Kotlin models to have the same shape as
the JSON.
* On JS, is is not possible to check if a `@JsExport` instance implements a given class. If you need polymorphism, you
must check `__typename` to determine what interface to use.
* Extension functions on generated code break when you use this technique since we are casting a raw JS object and not
actually instantiating a class.
-* `generateAsInternal = true` does not work with `JsExport`, since the compiler ends up giving the internal modifier
+* `generateAsInternal = true` does not work with `@JsExport`, since the compiler ends up giving the internal modifier
precedence, and thus mangling the property names.
* Custom adapters can only be used when their target types are supported by JS (see the full list
of [supported types](https://kotlinlang.org/docs/js-to-kotlin-interop.html#kotlin-types-in-javascript)).
@@ -205,14 +205,14 @@ when (animal.__typename) {
## `DynamicJsJsonReader`
If you would prefer to use `operationBased` models, and performance is not _as_ critical, you can
-use `DynamicJsJsonReader`. `DynamicJsJsonReader` works with a javascript object that is already parsed on the JS side.
+use `DynamicJsJsonReader`. `DynamicJsJsonReader` works with a JavaScript object that is already parsed on the JS side.
-In JS reading response byte by byte from a byte array like okio is doing incurs a lot of overhead because Kotlin
+In JS reading response byte by byte from a byte array like Okio does incurs a lot of overhead because Kotlin
uses `Long` indices in its Arrays, and Longs do not have a JS implementation.
By bypassing this reading, `DynamicJsJsonReader` allows faster reading of responses while still keeping the full Kotlin type information.
-In testing we've seen a ~25x performance boost on JS platforms using this parser vs ~100x with the `JsExport` approach.
+In testing we've seen a ~25x performance boost on JS platforms using this parser vs ~100x with the `@JsExport` approach.
To use `DynamicJsJsonReader`, your JS implementation above would become:
diff --git a/docs/source/advanced/kotlin-native.mdx b/docs/source/advanced/kotlin-native.mdx
deleted file mode 100644
index a4a665d208a..00000000000
--- a/docs/source/advanced/kotlin-native.mdx
+++ /dev/null
@@ -1,35 +0,0 @@
----
-title: Kotlin native
----
-
-Apollo Kotlin supports multiple native targets, including iOS and MacOS.
-
-Apollo Kotlin requires the [new Kotlin Native Memory Manager](https://blog.jetbrains.com/kotlin/2021/08/try-the-new-kotlin-native-memory-manager-development-preview/). It is enabled by default since Kotlin 1.7.20. If you're using a version of Kotlin lower than 1.7.20, you need to opt-in:
-
-```kotlin title="build.gradle.kts"
-kotlin.targets.withType(KotlinNativeTarget::class.java) {
- binaries.all {
- binaryOptions["memoryModel"] = "experimental"
- }
-}
-```
-
-More information is available on the [migration guide](https://github.com/JetBrains/kotlin/blob/master/kotlin-native/NEW_MM.md#enable-the-new-mm).
-
-## Multithreaded coroutines
-
-By default when using the `x.y.z-native-mt` branch of coroutines, Gradle replaces the `-native-mt` version with the non-mt version as outlined [here](https://kotlinlang.org/docs/mobile/concurrency-and-coroutines.html#multithreaded-coroutines). To prevent this, add the following to your root `build.gradle.kts`:
-
-```kotlin
-allprojects {
- configurations {
- all {
- resolutionStrategy {
- force("org.jetbrains.kotlinx:kotlinx-coroutines-core:x.y.z-native-mt")
- }
- }
- }
-}
-```
-
-This ensures that the same version is used everywhere, and that Gradle doesn't fail because `-native-mt` is a pre-release version [(`1.5.1-native-mt < 1.5.1`)](https://docs.gradle.org/current/userguide/dependency_resolution.html#sub:resolution-strategy).
diff --git a/docs/source/advanced/multi-modules.mdx b/docs/source/advanced/multi-modules.mdx
index c5ebbcbf6ba..ee5b3bfa7d7 100644
--- a/docs/source/advanced/multi-modules.mdx
+++ b/docs/source/advanced/multi-modules.mdx
@@ -5,7 +5,9 @@ title: Multi Modules codegen
For multi-modules projects, Apollo Kotlin enables you to define queries in a feature module and reuse fragments and types from another module dependency. This helps with better separation of concerns and build times.
+
This page is for sharing a schema between different modules and defining your `.graphql` operations in different modules. If all your `.graphql` files are in a single module, you can use `apollo-runtime` like any other Kotlin dependency without any of this.
+
@@ -21,16 +23,20 @@ apollo {
service("service") {
packageName.set("schema")
- // enable generation of metadata for use by downstream modules
+ // Enable generation of metadata for use by downstream modules
generateApolloMetadata.set(true)
// If you need to specify the location of your schema files
schemaFiles.from(/*...*/)
- // define options that must be shared between all modules using this schema
+ // Scalar mappings and generateDataBuilders must be defined in the schema module
mapScalar(/*...*/)
generateDataBuilders.set(true)
- // more options...
+
+ // Other options can be different between modules.
+ // If you want those options to be applied to all modules, use a convention plugin and shared build logic.
+ useSemanticNaming.set(true)
+ generateFragmentImplementations.set(true)
}
}
```
@@ -40,7 +46,7 @@ In your feature module, declare your schema module as a dependency:
```kotlin
// feature/build.gradle.kts
apollo {
- // service names must match
+ // Service names must match
service("service") {
packageName.set("feature")
@@ -68,8 +74,10 @@ apollo {
}
```
-
+
+
The `bidirectional` parameter is experimental because it may break Gradle project isolation. For a project-isolation compatible method, try isADependencyOf
-
-Once you opt in auto-detection of used types, it's important that **all** modules are doubly linked like above. If not the feature modules will fail to compile due to some missing schema classes.
\ No newline at end of file
+
+
+Once you opt in auto-detection of used types, it's important that **all** modules are doubly linked like above. If not the feature modules will fail to compile due to some missing schema classes.
diff --git a/docs/source/advanced/network-connectivity.mdx b/docs/source/advanced/network-connectivity.mdx
new file mode 100644
index 00000000000..93054dd863f
--- /dev/null
+++ b/docs/source/advanced/network-connectivity.mdx
@@ -0,0 +1,84 @@
+---
+title: Monitor the network state to reduce latency
+---
+
+
+
+**Network Monitor APIs are currently [experimental](https://www.apollographql.com/docs/resources/release-stages/#experimental-features) in Apollo Kotlin.** If you have feedback on them, please let us know via [GitHub issues](https://github.com/apollographql/apollo-kotlin/issues/new?assignees=&labels=Type%3A+Bug&template=bug_report.md) or in the [Kotlin Slack community](https://slack.kotl.in/).
+
+
+
+Android and Apple targets provide APIs to monitor the network state of your device:
+
+- [ConnectivityManager](https://developer.android.com/training/monitoring-device-state/) on Android targets.
+- [NWPathMonitor](https://developer.apple.com/documentation/network/nwpathmonitor) on Apple targets.
+
+You can configure your [ApolloClient](https://www.apollographql.com/docs/kotlin/kdoc/apollo-runtime/com.apollographql.apollo3/-apollo-client/index.html) to use these APIs to improve latency of your requests using the `NetworkMonitor` API:
+
+```kotlin
+// androidMain
+val networkMonitor = NetworkMonitor(context)
+
+// appleMain
+val networkMonitor = NetworkMonitor()
+
+// commonMain
+val apolloClient = ApolloClient.Builder()
+ .serverUrl("https://example.com/graphql")
+ .networkMonitor(networkMonitor)
+ .build()
+```
+
+### `failFastIfOffline`
+
+When a `NetworkMonitor` is configured, you can use `failFastIfOffline` to avoid trying out request if the device is offline:
+
+```kotlin
+// Opt-in `failFastIfOffline` on all queries
+val apolloClient = ApolloClient.Builder()
+ .serverUrl("https://example.com/graphql")
+ .failFastIfOffline(true)
+ .build()
+
+val response = apolloClient.query(myQuery).execute()
+println(response.exception?.message)
+// "The device is offline"
+
+// Opt-out `failFastIfOffline` on a single query
+val response = apolloClient.query(myQuery).failFastIfOffline(false).execute()
+```
+
+### `retryOnError`
+
+When a `NetworkMonitor` is configured, `retryOnError` uses `NetworkMonitor.waitForNetwork()` instead of the default exponential backoff algorithm in order to reconnect faster when connectivity is back.
+
+### Customizing the retry algorithm
+
+You can customize the retry algorithm further by defining you won interceptor. Make sure to:
+
+- add your interceptor last, so that it wraps the network call and doesn't get cache misses or any other errors that may be emitted by upstream interceptors.
+- call `retryOnError(false)` when forwarding the request downstream so that the retry is not made twice.
+
+```kotlin
+internal class MyRetryInterceptor(private val networkMonitor: NetworkMonitor?): ApolloInterceptor {
+ override fun intercept(request: ApolloRequest, chain: ApolloInterceptorChain): Flow> {
+ // Disable Apollo's built-in retry mechanism
+ val newRequest = request.newBuilder().retryOnError(false).build()
+ return chain.proceed(newRequest)
+ .onEach {
+ if (it.exception != null && it.exception.shouldRetry()) {
+ throw RetryException
+ }
+ }.retryWhen { cause, _->
+ if (cause is RetryException) {
+ // Add your logic here
+ true
+ } else {
+ // Programming error, re-throw it
+ false
+ }
+ }
+ }
+}
+```
+
diff --git a/docs/source/advanced/no-runtime.mdx b/docs/source/advanced/no-runtime.mdx
index 4eef85f21a7..0f4d1c5adb8 100644
--- a/docs/source/advanced/no-runtime.mdx
+++ b/docs/source/advanced/no-runtime.mdx
@@ -2,12 +2,12 @@
title: Using the models without apollo-runtime
---
-`apollo-runtime` and `ApolloClient` provides support for doing the network requests and interacting with the cache but you can use the generated models and parsers without the runtime and use your network layer of choice for the HTTP calls.
+`apollo-runtime` and `ApolloClient` provide support for doing the network requests and interacting with the cache but you can use the generated models and parsers without the runtime and use your network layer of choice for the HTTP calls.
For this, remove the `com.apollographql.apollo3:apollo-runtime` dependency and replace it with:
```kotlin title="build.gradle"
-implementation("com.apollographql.apollo3:apollo-api:4.0.0-beta.5")
+implementation("com.apollographql.apollo3:apollo-api:4.0.0-beta.7")
```
## Composing an HTTP request body
diff --git a/docs/source/advanced/nullability.mdx b/docs/source/advanced/nullability.mdx
index 214a4f18f20..988ede1f779 100644
--- a/docs/source/advanced/nullability.mdx
+++ b/docs/source/advanced/nullability.mdx
@@ -3,7 +3,11 @@ title: Handling nullability and errors
description: Make your queries even more typesafe
---
-> โ ๏ธ **Nullability annotations are currently [experimental](https://www.apollographql.com/docs/resources/product-launch-stages/#experimental-features) in Apollo Kotlin.** If you have feedback on them, please let us know via [GitHub issues](https://github.com/apollographql/apollo-kotlin/issues/new?assignees=&labels=Type%3A+Bug&template=bug_report.md&title=[Defer%20Support]), in the [Kotlin Slack community](https://slack.kotl.in/), or in the [GraphQL nullability working group](https://github.com/graphql/nullability-wg/).
+
+
+**Nullability annotations are currently [experimental](https://www.apollographql.com/docs/resources/product-launch-stages/#experimental-features) in Apollo Kotlin.** If you have feedback on them, please let us know via [GitHub issues](https://github.com/apollographql/apollo-kotlin/issues/new?assignees=&labels=Type%3A+Bug&template=bug_report.md), in the [Kotlin Slack community](https://slack.kotl.in/), or in the [GraphQL nullability working group](https://github.com/graphql/nullability-wg/).
+
+
## Nullability in GraphQL
@@ -50,11 +54,13 @@ The server returns the following response in case of error:
GraphQL best practices recommend using nullable types by default. From [graphql.org](https://graphql.org/learn/best-practices/#nullability):
-```
-In a GraphQL type system, every field is nullable by default.
+
+
+_In a GraphQL type system, every field is nullable by default.
This is because there are many things that can go awry in a networked
-service backed by databases and other services.
-```
+service backed by databases and other services._
+
+
This default makes sense in distributed environments where microservices might fail and some data fail to resolve. This behaviour is robust by default: if part of your query fails, you still get the rest of the data.
diff --git a/docs/source/advanced/persisted-queries.mdx b/docs/source/advanced/persisted-queries.mdx
index f329b3978f8..0815fbfceb4 100644
--- a/docs/source/advanced/persisted-queries.mdx
+++ b/docs/source/advanced/persisted-queries.mdx
@@ -24,7 +24,12 @@ You can use APQs with the following versions of Apollo Kotlin, Apollo Server, an
- [Apollo Server](/apollo-server/) (v1.0.0+)
- [Apollo Router](/router) (v0.1.0+)
-> **Note:** You can use _either_ Apollo Server _or_ Apollo Router for APQs. They don't need to be used together.
+
+
+
+You can use _either_ Apollo Server _or_ Apollo Router for APQs. They don't need to be used together.
+
+
Using persisted queries for safelisting has the following requirements:
- Apollo Kotlin (v3.8.2+)
@@ -81,7 +86,7 @@ Once you've configured your code generation to include operation IDs, you can up
```kotlin
val apolloClient = ApolloClient.Builder()
- .serverUrl("https://...")
+ .serverUrl("https://example.com/graphql")
.autoPersistedQueries()
.build()
```
diff --git a/docs/source/advanced/plugin-configuration.mdx b/docs/source/advanced/plugin-configuration.mdx
index 42a5f291dd9..72c73870e42 100644
--- a/docs/source/advanced/plugin-configuration.mdx
+++ b/docs/source/advanced/plugin-configuration.mdx
@@ -37,14 +37,14 @@ apollo {
}
```
-> By default, Apollo Kotlin combines all files in your project that match the pattern `schema.[graphqls|json|sdl]`.
+> By default, Apollo Kotlin combines all `*.[graphqls|json|sdl]` files in `src/main/graphql/` (Android/JVM projects) or `src/commonMain/graphql/` (multiplatform projects).
## Combining multiple schema files
Apollo Kotlin supports a collection of client directives, including `@nonnull`, `@optional`, and `@typePolicy`. These
directives enable you to extend your server's base schema with client-specific types and fields.
-If you expand your schema in a separate file, you can instruct Apollo Kotlin to construct its schema from a combination
+If you expand your schema in a separate file (usually named `extra.graphqls`), you can instruct Apollo Kotlin to construct its schema from a combination
of multiple files, like so:
```kotlin
@@ -55,19 +55,17 @@ apollo {
}
```
-> By default, Apollo Kotlin combines all files in your project that match the pattern `schema.[graphqls|json|sdl]`.
+> By default, Apollo Kotlin combines all `*.[graphqls|json|sdl]` files in `src/main/graphql/` (Android/JVM projects) or `src/commonMain/graphql/` (multiplatform projects).
-## Wiring generated source
+## Wiring generated sources
-By default, Apollo Kotlin adds generated source:
+By default, Apollo Kotlin adds the generated sources:
- to the `main` sourceSet for JVM projects
- to `commonMain` for multiplatform projects
- to all non-test variants for Android projects
-You can customize this behavior with the `outputDirConnection` property. For example, to wire a service to the test
-source set of a Kotlin
-JVM project:
+You can customize this behavior with the `outputDirConnection` property. For example, to wire a service to the test source set of a Kotlin JVM project:
```kotlin
apollo {
@@ -81,10 +79,9 @@ apollo {
## Android variants support
-It is sometimes useful to have different operations or schemas depending on
-the [variant](https://developer.android.com/studio/build/build-variants) of your Android project.
+It is sometimes useful to have different operations or schemas depending on the [variant](https://developer.android.com/build/build-variants) of your Android project.
-To do this, you can instruct the Gradle plugin to automatically configure a Service per variant, like so:
+To do this, you can instruct the Gradle plugin to automatically configure a Service per variant:
```kotlin
apollo {
@@ -95,13 +92,12 @@ apollo {
}
```
-- `sourceFolder` where to find the GraphQL relative to "src/$sourceSetName/graphql". Pass "." to look into "
- src/$sourceSetName/graphql".
-- `nameSuffix` a suffix to use for the service name. Leave blank to use the variant name as is.
+- `sourceFolder` is where to find the GraphQL relative to "src/$sourceSetName/graphql". Pass "." to look into "src/$sourceSetName/graphql".
+- `nameSuffix` is the suffix to use for the service name. Leave blank to use the variant name as is.
-Similarly to what the Android variant system does with source code, the GraphQL files are handled additively, and files
-in `src/main/graphql` are included in all services. This means your project could look like this (e.g. when certain
-operations must only exist in debug builds):
+Similarly to what the Android variant system does with source code, the GraphQL files are handled **additively**, and files in `src/main/graphql` are included in all services.
+
+For instance, if certain operations should only exist in debug builds, your project structure could look like this:
```
- main
@@ -113,7 +109,7 @@ operations must only exist in debug builds):
- operations.graphql // Operations specific to the 'debug' build type
```
-Or for instance like this (specific backend per flavor):
+Or if you have a specific backend per flavor, it could look like this:
```
- main
@@ -127,8 +123,7 @@ Or for instance like this (specific backend per flavor):
- operations.graphql // Operations specific to the 'full' flavor
```
-If you have many variants and don't need to configure an Apollo Service for each one of them, it may be simpler to
-declare the Services manually, for instance:
+If you have a lot of variants and don't need to configure an Apollo Service for each, it may be simpler to declare the Services manually rather than using `createAllAndroidVariantServices`. For instance:
```kotlin
apollo {
@@ -214,7 +209,7 @@ or a subset of the data class methods. To do this, set `generateMethods` to a li
- "equalsHashCode" generates `equals` and `hashCode` methods that will compare generated class properties.
- "toString" generates a method that will print a pretty string representing the data in the class.
- "copy" (Kotlin only) generates a method that will copy the class with named parameters and default values.
-- "dataClass" (Kotlin only and redundant with all other methods) generates the class as a [data class](https://kotlinlang.org/docs/data-classes.html)
+- "dataClass" (Kotlin only and redundant with all other methods) generates the class as a [data class](https://kotlinlang.org/docs/data-classes.html).
which will automatically generate `toString`, `copy`, `equals` and `hashCode`.
Here are some possible configurations:
@@ -222,13 +217,13 @@ Here are some possible configurations:
```kotlin
apollo {
service("service") {
- // Generates equals/hashCode
+ // Generates equals and hashCode
generateMethods.set(listOf("equalsHashCode"))
- // Also generates toString, equals, and hashcode
+ // Generates toString, equals, and hashcode (the default for Java)
generateMethods.set(listOf("equalsHashCode", "toString"))
// Only generates copy
generateMethods.set(listOf("copy"))
- // Generates data classes
+ // Generates data classes (the default for Kotlin)
generateMethods.set(listOf("dataClass"))
}
}
diff --git a/docs/source/advanced/query-batching.mdx b/docs/source/advanced/query-batching.mdx
index 1a04acb481c..2b371015232 100644
--- a/docs/source/advanced/query-batching.mdx
+++ b/docs/source/advanced/query-batching.mdx
@@ -12,7 +12,7 @@ You enable batching when you initialize your `ApolloClient` instance, like so:
```kotlin {3}
val apolloClient = ApolloClient.Builder()
- .serverUrl("https://...")
+ .serverUrl("https://example.com/graphql")
.httpBatching()
.build()
```
@@ -43,7 +43,7 @@ You can also require individual operations to _opt in_ to batching. To do so, yo
```kotlin {4}
val apolloClient = ApolloClient.Builder()
- .serverUrl("https://...")
+ .serverUrl("https://example.com/graphql")
.httpBatching()
.canBeBatched(false)
.build()
diff --git a/docs/source/advanced/source-sets.mdx b/docs/source/advanced/source-sets.mdx
index 5c2ad1c23d1..9c436f71a18 100644
--- a/docs/source/advanced/source-sets.mdx
+++ b/docs/source/advanced/source-sets.mdx
@@ -2,11 +2,13 @@
title: Connecting source sets
---
-By default, Apollo Kotlin adds the generated files to the `main` (for JVM/Android projects) or `commonMain` (for multiplatform projects) source sets.
+By default, Apollo Kotlin adds generated sources:
-If you only need them in a specific source set, you can use `outputDirConnection` to add them to a different source set.
+- to the `main` sourceSet for JVM projects
+- to `commonMain` for multiplatform projects
+- to all non-test variants for Android projects
-For an example, you can add them to the "test" source set:
+You can customize this behavior with the `outputDirConnection` property. For example, to wire a service to the test source set of a Kotlin JVM project:
```kotlin
apollo {
@@ -17,15 +19,3 @@ apollo {
}
}
```
-
-On Android, because the generated files are added to the `main` source set, they are available in all your [build variants](https://developer.android.com/studio/build/build-variants#build-types). If you need them available to only a specific build variant, you can do so with:
-
-```kotlin
-apollo {
- service("service") {
- outputDirConnection {
- connectToAndroidSourceSet("demoDebug")
- }
- }
-}
-```
diff --git a/docs/source/advanced/upload.mdx b/docs/source/advanced/upload.mdx
index f95a4b26b96..a06009ea2d5 100644
--- a/docs/source/advanced/upload.mdx
+++ b/docs/source/advanced/upload.mdx
@@ -4,7 +4,7 @@ title: Uploading files
Apollo Kotlin supports file uploads via the [GraphQL multipart request specification](https://github.com/jaydenseric/graphql-multipart-request-spec) with a few caveats:
-- Uploading files with GraphQL is most often suitable for proof-of-concept applications. In production, using purpose-built tools for file uploads may be preferable. Refer to this [blog post](https://www.apollographql.com/blog/backend/file-uploads/file-upload-best-practices/) for the advantages and disadvantages of multiple approaches.
+- Uploading files with GraphQL is most often suitable for proof-of-concept applications. In production, using purpose-built tools for file uploads may be preferable. Refer to this [blog post](https://www.apollographql.com/blog/backend/file-uploads/file-upload-best-practices/) for possible approaches and their advantages and disadvantages.
- The [Apollo Router](/router/) doesn't support `multipart/form-data` uploads.
## Uploading files with Apollo Kotlin
@@ -21,7 +21,11 @@ apollo {
In this example, the GraphQL schema defines a custom scalar type named `Upload`. You can use a different name as needed for your schema.
-> **Note:** You don't need to register a type adapter for `Upload`, because the `mapScalarToUpload` method registers it automatically.
+
+
+You don't need to register a type adapter for `Upload`, because the `mapScalarToUpload` method registers it automatically.
+
+
Now let's consider a mutation that takes an `Upload` as a parameter:
diff --git a/docs/source/caching/declarative-ids.mdx b/docs/source/caching/declarative-ids.mdx
index 8bd632631dd..1cad5d75f9c 100644
--- a/docs/source/caching/declarative-ids.mdx
+++ b/docs/source/caching/declarative-ids.mdx
@@ -16,16 +16,16 @@ extend type Book @typePolicy(keyFields: "id")
With declarative cache IDs, the codegen process adds ID fields automatically and generates type-safe code that can return a valid cache ID for any object.
-To do this, Apollo Kotlin extends your back-end schema. The GraphQL spec supports [object extensions](https://spec.graphql.org/draft/#sec-Object-Extensions) using the `extend type` keywords. We can use this together with the `@typePolicy` and `@fieldPolicy` directives, along with an extra `.graphqls` file named `extra.graphqls`.
+To do this, Apollo Kotlin extends your backend schema. The GraphQL spec supports [object extensions](https://spec.graphql.org/draft/#sec-Object-Extensions) using the `extend type` keywords. We can use this together with the `@typePolicy` and `@fieldPolicy` directives, along with an extra `.graphqls` file named `extra.graphqls`.
Note that you'll need to make sure that the `extra.graphqls` file is included in your [schema configuration](https://www.apollographql.com/docs/kotlin/advanced/plugin-configuration#combining-multiple-schema-files).
You can obtain a given object type's cache ID from one of two sources:
-| Source | Directive | Description |
-|--------|-----------|-------------|
-| From a response object's fields (e.g., `Book.id`) | [`@typePolicy`](#typepolicy) | This happens _after_ a network request and is essential to merging a query result with existing cached data. This is the most common case. |
-| From a GraphQL operation's arguments (e.g., `author(id: "au456")`) | [`@fieldPolicy`](#fieldpolicy) | This happens _before_ a network request and enables you to avoid a network round trip if all requested data is in the cache already. This is an optional optimization that can avoid some cache misses. |
+| Source | Directive | Description |
+|--------------------------------------------------------|-----------|-------------|
+| From a response object's fields (e.g., `Book.id`) | [`@typePolicy`](#typepolicy) | This happens _after_ a network request and is essential to merging a query result with existing cached data. This is the most common case. |
+| From a field's arguments (e.g., `author(id: "au456")`) | [`@fieldPolicy`](#fieldpolicy) | This happens _before_ a network request and enables you to avoid a network round trip if all requested data is in the cache already. This is an optional optimization that can avoid some cache misses. |
## `@typePolicy`
diff --git a/docs/source/caching/http-cache.mdx b/docs/source/caching/http-cache.mdx
index 8fdc79a88a1..fd7120e5c61 100644
--- a/docs/source/caching/http-cache.mdx
+++ b/docs/source/caching/http-cache.mdx
@@ -5,7 +5,11 @@ title: HTTP cache
> This page focuses on the HTTP cache. If you want to deduplicate the storage of your objects and/or notify your UI when your data changes, take a look at the [normalized cache](./normalized-cache) instead.
-> โน๏ธ The HTTP cache is only available on the JVM.
+
+
+The HTTP cache is only available on Android and the JVM.
+
+
## Setup
@@ -13,7 +17,7 @@ To enable HTTP cache support, add the dependency to your project's `build.gradle
```kotlin title="build.gradle[.kts]"
dependencies {
- implementation("com.apollographql.apollo3:apollo-http-cache:4.0.0-beta.5")
+ implementation("com.apollographql.apollo3:apollo-http-cache:4.0.0-beta.7")
}
```
@@ -45,19 +49,26 @@ apolloClient = ApolloClient.Builder()
The HTTP cache is a least recently used (LRU) cache with a configurable max size.
-Once your cache setup is complete, the cache will be used by default by all your queries (mutations are never cached). By default, queries will try to find a result in the cache first and go the network if it's not there. This is the `HttpFetchPolicy.CacheFirst`. You can customize that behaviour with `httpFetchPolicy(HttpFetchPolicy)`:
+Once your cache setup is complete, the cache will be used by default by all your queries. By default, queries will try to find a result in the cache first and go the network if it's not there. This is the `HttpFetchPolicy.CacheFirst` policy. You can customize that behaviour with `httpFetchPolicy(HttpFetchPolicy)`:
```kotlin
val response = apolloClient.query(query)
- // Don't use the cache
- .httpFetchPolicy(HttpFetchPolicy.NetworkOnly)
+ // Try the cache first - if it's a miss, try the network
+ .httpFetchPolicy(HttpFetchPolicy.CacheFirst)
+
+ // Only use the cache
+ .httpFetchPolicy(HttpFetchPolicy.CacheOnly)
- // Or only use the cache
- .httpFetchPolicy(HttpFetchPolicy.CacheOnly)
+ // Try the network first - if there's an error, try the cache
+ .httpFetchPolicy(HttpFetchPolicy.NetworkFirst)
- // Finally, execute your query
- .execute()
+ // Don't use the cache
+ .httpFetchPolicy(HttpFetchPolicy.NetworkOnly)
+
+ // Finally, execute your query
+ .execute()
```
+Note: mutations and subscriptions don't go through the cache.
If the query is present in cache, it will be used to return `response.data`. If not, a `HttpCacheMissException` will be thrown.
diff --git a/docs/source/caching/normalized-cache.mdx b/docs/source/caching/normalized-cache.mdx
index 6c806f64ad5..799477f4c45 100644
--- a/docs/source/caching/normalized-cache.mdx
+++ b/docs/source/caching/normalized-cache.mdx
@@ -57,7 +57,11 @@ A normalized cache does _not_ store this response directly. Instead, it breaks i
"QUERY_ROOT": {"favoriteBook": "ApolloCacheReference{favoriteBook}"}
```
-> โ ๏ธ These default generated cache IDs (`favoriteBook` and `favoriteBook.author`) are undesirable for data deduplication. See [Specifying cache IDs](#specifying-cache-ids).
+
+
+These default generated cache IDs (`favoriteBook` and `favoriteBook.author`) are undesirable for data deduplication. See [Specifying cache IDs](#specifying-cache-ids).
+
+
* Notice that the `author` field of the `Book` entry now contains the string `ApolloCacheReference{favoriteBook.author}`. This is a **reference** to the `Author` cache entry.
* Notice also the `QUERY_ROOT` entry, which is always present if you've cached results from at least one query. This entry contains a reference for each top-level field you've included in a query (e.g., `favoriteBook`).
@@ -70,7 +74,7 @@ Apollo Kotlin's `MemoryCache` is a normalized, in-memory cache for storing objec
```kotlin title="build.gradle[.kts]"
dependencies {
- implementation("com.apollographql.apollo3:apollo-normalized-cache:4.0.0-beta.5")
+ implementation("com.apollographql.apollo3:apollo-normalized-cache:4.0.0-beta.7")
}
```
@@ -81,7 +85,7 @@ Then include the cache in your `ApolloClient` initialization, like so:
val cacheFactory = MemoryCacheFactory(maxSizeBytes = 10 * 1024 * 1024)
// Build the ApolloClient
val apolloClient = ApolloClient.Builder()
- .serverUrl("https://...")
+ .serverUrl("https://example.com/graphql")
// normalizedCache() is an extension function on ApolloClient.Builder
.normalizedCache(cacheFactory)
.build()
@@ -106,7 +110,7 @@ To enable SQLite cache support, add the `apollo-normalized-cache-sqlite` depende
```kotlin title="build.gradle.kts"
dependencies {
- implementation("com.apollographql.apollo3:apollo-normalized-cache-sqlite:4.0.0-beta.5")
+ implementation("com.apollographql.apollo3:apollo-normalized-cache-sqlite:4.0.0-beta.7")
}
```
@@ -122,7 +126,7 @@ val sqlNormalizedCacheFactory = SqlNormalizedCacheFactory("apollo.db")
// Build the ApolloClient
val apolloClient = ApolloClient.Builder()
- .serverUrl("https://...")
+ .serverUrl("https://example.com/graphql")
.normalizedCache(sqlNormalizedCacheFactory)
.build()
```
@@ -149,7 +153,7 @@ After you add a normalized cache to your `ApolloClient` initialization, Apollo K
```kotlin
val apolloClient = ApolloClient.Builder()
- .serverUrl("https://...")
+ .serverUrl("https://example.com/graphql")
.fetchPolicy(FetchPolicy.NetworkOnly)
.build()
```
@@ -172,23 +176,21 @@ val response = apolloClient.query(query)
// Always use the network and never check the cache, even if network fails
.fetchPolicy(FetchPolicy.NetworkOnly)
-
- // Execute the query
- .execute()
-```
-The `CacheAndNetwork` policy can emit multiple values, so you call `toFlow()` instead of `execute()`:
-
-```kotlin
-apolloClient.query(query)
-
- // Check the cache and also use the network (1 or 2 values can be emitted)
+
+ // Check the cache and also use the network
.fetchPolicy(FetchPolicy.CacheAndNetwork)
// Execute the query and collect the responses
.toFlow().collect { response ->
- // ...
+ // ...
}
```
+Note that cache misses **will** emit a response with a non null `.exception`, meaning that some of these policies can emit multiple values:
+- `CacheFirst` can emit 1 or 2 values
+- `NetworkFirst` can emit 1 or 2 values
+- `CacheAndNetwork` will emit 2 values
+
+Note: `.execute()` filters out cache or network errors to return a single success response, however since `CacheAndNetwork` can emit 2 success responses, you should use `.toFlow()` when using that policy.
As with `normalizedCache(NormalizedCacheFactory)`, `fetchPolicy(FetchPolicy)` is an extension function on `ApolloClient.Builder()`, so you need `apollo-normalized-cache` in your classpath for this to work.
@@ -257,17 +259,9 @@ Fortunately, all of our objects have an `id` field that we can use for this purp
There are two methods for specifying an object's cache ID:
-* **[Declaratively](declarative-ids)** (recommended). You can specify schema extensions that tell the codegen where to find the ID and make sure at compile time that all the `id` fields are requested so that all objects can be identified. Declarative IDs also prefix each ID with the typename to ensure global uniqueness.
-* **[Programmatically](programmatic-ids).** You can implement custom APIs that retrieve the ID for an object. Because you can execute arbitrary code, this solution is more flexible, but it's also more error prone and requires that you manually request `id` fields.
+* **[Declaratively](declarative-ids)** (recommended). You can specify schema extensions that tell the codegen in which field(s) to find the ID and make sure at compile time that all these fields are requested in operations so that all objects can be identified. Declarative IDs also prefix each ID with the typename to ensure global uniqueness.
+* **[Programmatically](programmatic-ids).** You can implement custom APIs that provide the cache ID for an object. Because you can execute arbitrary code, this solution is more flexible, but it's also more error prone and requires that your operations request the key fields.
## Clearing the cache
-Call below to clear the cache of all entries, note that retrieving `apolloClient.apolloStore` will throw an exception if a cache has not been configured on the client.
-
-```kotlin
-try {
- apolloClient.apolloStore.clearAll()
-} catch (e: IllegalStateException) {
- println("Failed to clear Apollo normalized cache because none was found")
-}
-```
+Call `apolloClient.apolloStore.clearAll()` to clear the cache of all entries. Note that calling `apolloClient.apolloStore` throws an exception if a cache has not been configured.
diff --git a/docs/source/caching/programmatic-ids.mdx b/docs/source/caching/programmatic-ids.mdx
index 54d1db8b727..6cfe27cc200 100644
--- a/docs/source/caching/programmatic-ids.mdx
+++ b/docs/source/caching/programmatic-ids.mdx
@@ -11,7 +11,7 @@ You can generate a given object type's cache ID from one of two sources:
| From a response object's fields (e.g., `Book.id`) | [`CacheKeyGenerator`](#cachekeygenerator) | This happens _after_ a network request and is essential to merging a query result with existing cached data. This is the most common case. |
| From a GraphQL operation's arguments (e.g., `author(id: "au456")`) | [`CacheKeyResolver`](#cachekeyresolver) | This happens _before_ a network request and enables you to avoid a network round trip if all requested data is in the cache already. This is an optional optimization that can avoid some cache misses. |
-Apollo Kotlin provides a class for generating cache keys from each of these sources.
+Apollo Kotlin provides a class for generating cache IDs from each of these sources.
## `CacheKeyGenerator`
@@ -30,7 +30,7 @@ To use your custom `CacheKeyGenerator`, include it in your cache initialization
```kotlin {5}
val apolloClient = ApolloClient.Builder()
- .serverUrl("https://...")
+ .serverUrl("https://example.com/graphql")
.normalizedCache(
normalizedCacheFactory = cacheFactory,
cacheKeyGenerator = cacheKeyGenerator,
@@ -43,7 +43,7 @@ You can get the current object's typename from the `context` object and include
```kotlin
val cacheKeyGenerator = object : CacheKeyGenerator {
override fun cacheKeyForObject(obj: Map, context: CacheKeyGeneratorContext): CacheKey? {
- val typename = context.field.type.leafType().name
+ val typename = context.field.type.rawType().name
val id = obj["id"] as String
return CacheKey(typename, id)
@@ -54,7 +54,7 @@ val cacheKeyGenerator = object : CacheKeyGenerator {
You can also use the current object's typename to use _different_ cache ID generation logic for different object types.
Note that for cache ID generation to work, your GraphQL operations must return whatever fields your custom code relies on (such as `id` above). If a query does not return a required field, the cache ID will be inconsistent, resulting in data duplication.
-Also, using `context.field.type.leafType().name` yields the typename of the Union as opposed to the expected runtime value of Union received in the response. Instead querying for the `__typename` is safer.
+Also, for interfaces and unions, `context.field.type.rawType().name` yields the typename as it is declared in the schema, as opposed to the runtime value of the type received in the response. Instead querying for the `__typename` is safer.
To make sure `__typename` is included in all operations set the [addTypename](https://www.apollographql.com/docs/kotlin/kdoc/apollo-gradle-plugin-external/com.apollographql.apollo3.gradle.api/-service/add-typename.html) gradle config:
```
@@ -67,14 +67,14 @@ apollo {
## `CacheKeyResolver`
-The `CacheKeyResolver` class enables you to generate custom cache IDs from an field's arguments. This basic example generates _every_ object type's cache ID from the `id` argument _if it's present_:
+The `CacheKeyResolver` class enables you to generate custom cache IDs from a field's arguments. This basic example generates _every_ object type's cache ID from the `id` argument _if it's present_:
```kotlin
val cacheKeyResolver = object: CacheKeyResolver() {
override fun cacheKeyForField(field: CompiledField, variables: Executable.Variables): CacheKey? {
// [field] contains compile-time information about what type of object is being resolved.
- // Even though we call leafType() here, we're guaranteed that the type is a composite type and not a list
- val typename = field.type.leafType().name
+ // Even though we call rawType() here, we're guaranteed that the type is a composite type and not a list
+ val typename = field.type.rawType().name
// argumentValue returns the runtime value of the "id" argument
// from either the variables or as a literal value
@@ -95,7 +95,7 @@ To use your custom `CacheKeyResolver`, include it in your cache initialization c
```kotlin {6}
val apolloClient = ApolloClient.Builder()
- .serverUrl("https://...")
+ .serverUrl("https://example.com/graphql")
.normalizedCache(
normalizedCacheFactory = cacheFactory,
cacheKeyGenerator = cacheKeyGenerator,
@@ -127,14 +127,14 @@ To have the cache look up _all_ books in the `ids` list, we need to override `li
```kotlin
override fun listOfCacheKeysForField(field: CompiledField, variables: Executable.Variables): List? {
// Note that the field *can* be a list type here
- val typename = field.type.leafType().name
+ val typename = field.type.rawType().name
// argumentValue returns the runtime value of the "id" argument
// from either the variables or as a literal value
val ids = field.argumentValue("ids", variables).getOrNull()
if (ids is List<*>) {
- // This field has an id argument, so we can use it to compute a cache key
+ // This field has an id argument, so we can use it to compute a cache ID
return ids.map { CacheKey(typename, it as String) }
}
diff --git a/docs/source/caching/query-watchers.mdx b/docs/source/caching/query-watchers.mdx
index 3f503d37cd8..3ecfc8f35e6 100644
--- a/docs/source/caching/query-watchers.mdx
+++ b/docs/source/caching/query-watchers.mdx
@@ -5,7 +5,7 @@ description: Update your UI in response to cache changes
Because your [normalized cache](./normalized-cache/) can deduplicate your GraphQL data (using proper [cache IDs](./declarative-ids/)), you can use the cache as the source of truth for populating your UI.
-When executing an operation, you can use the `ApolloCall.watch` method to automatically notify that operation whenever its associated cached data changes:
+When executing an operation, you can use the `ApolloCall.watch` method to automatically be notified whenever its associated cached data changes:
```kotlin {2}
apolloClient.query(TodoDetailsQuery())
@@ -61,12 +61,12 @@ The app's main view executes the `AllTodos` query to display a list of todo `Ite
"items": [
{
"id": "0",
- "title": "Write code for Apollo Kotlin 3",
+ "title": "Write code for Apollo Kotlin",
"completed": true,
},
{
"id": "1",
- "title": "Write documentation for Apollo Kotlin 3",
+ "title": "Write documentation for Apollo Kotlin",
"completed": false,
}
]
@@ -83,7 +83,7 @@ In this case, the `TodoDetails` query might return something like this:
"data": {
"item": {
"id": "1",
- "title": "Write documentation for Apollo Kotlin 3",
+ "title": "Write documentation for Apollo Kotlin",
"completed": true,
"content": "Don't forget docs about the normalized cache!"
}
diff --git a/docs/source/caching/store.mdx b/docs/source/caching/store.mdx
index d7def8a0541..a6e8ec02af2 100644
--- a/docs/source/caching/store.mdx
+++ b/docs/source/caching/store.mdx
@@ -8,7 +8,7 @@ The store is accessible with the `ApolloClient.apolloStore` extension:
```kotlin
val apolloClient = ApolloClient.Builder()
- .serverUrl("https://...")
+ .serverUrl("https://example.com/graphql")
.normalizedCache(MemoryCacheFactory(maxSizeBytes = 10 * 1024 * 1024))
.build()
diff --git a/docs/source/caching/troubleshooting.mdx b/docs/source/caching/troubleshooting.mdx
index a7d35087db3..0be26f64a77 100644
--- a/docs/source/caching/troubleshooting.mdx
+++ b/docs/source/caching/troubleshooting.mdx
@@ -9,12 +9,12 @@ If you are still experiencing cache misses, you can dump the contents of the cac
```kotlin
val dump = apolloClient.apolloStore.dump()
-NormalizedCache.prettifyDump(dump)
+println(NormalizedCache.prettifyDump(dump))
```
A graphical [normalized cache viewer](../testing/android-studio-plugin#normalized-cache-viewer) is also available in the Android Studio plugin.
-Make sure that no data is duplicated in the dump. If it is the case, it probably means that some objects have a wrong `CacheKey`. Make sure to provide a `CacheKeyResolver` that can work with your graph. All objects should have a unique and stable ID. That means that the ID should be the same no matter what path the object is in the graph. That also mean you have to include the identifier field in your queries to be able to use in from the `CacheKeyResolver`.
+Make sure that no data is duplicated in the dump. If it is the case, it probably means that some objects have a wrong `CacheKey`. Make sure to provide a `CacheKeyResolver` that can work with your graph. All objects should have a unique and stable cache ID. That means that the cache ID should be the same no matter what path the object is in the graph. That also mean you have to include the key field(s) in your queries to be able to use them in the `CacheKeyResolver`.
Finally, make sure to design your queries so that you can reuse fields. A single missing field in the cache for a query will trigger a network fetch. Sometimes it might be useful to query an extra field early on so that it can be reused by other later queries.
diff --git a/docs/source/config.json b/docs/source/config.json
index a5ce726d79c..dc881441145 100644
--- a/docs/source/config.json
+++ b/docs/source/config.json
@@ -28,7 +28,6 @@
"File types": "/essentials/file-types",
"Client Awareness": "/advanced/client-awareness",
"Multi Modules": "/advanced/multi-modules",
- "Connecting source sets": "/advanced/source-sets",
"Gradle plugin configuration": "/advanced/plugin-configuration"
},
"Fetching": {
@@ -39,7 +38,7 @@
"Error handling": "/essentials/errors",
"Custom scalars": "/essentials/custom-scalars",
"Fragments": "/essentials/fragments",
- "@defer support (experimental)": "/fetching/defer",
+ "@defer support": "/fetching/defer",
"Persisted queries": "/advanced/persisted-queries"
},
"Caching": {
@@ -53,7 +52,7 @@
"Troubleshooting": "/caching/troubleshooting"
},
"Networking": {
- "HTTP interceptors": "/advanced/interceptors-http",
+ "Interceptors": "/advanced/interceptors-http",
"Custom HTTP clients": "/advanced/http-engine",
"Using the models without apollo-runtime": "/advanced/no-runtime",
"Authentication": "/advanced/authentication",
@@ -66,15 +65,15 @@
"Mocking HTTP responses": "/testing/mocking-http-responses",
"Mocking GraphQL responses": "/testing/mocking-graphql-responses",
"Data builders": "/testing/data-builders",
- "UI Tests": "/testing/ui-tests",
"Apollo Debug Server": "/testing/apollo-debug-server"
},
"Advanced": {
"Uploading files": "/advanced/upload",
- "Handling nullability (experimental)": "/advanced/nullability",
+ "Monitoring the network state": "/advanced/network-connectivity",
+ "Handling nullability": "/advanced/nullability",
+ "Experimental WebSockets": "/advanced/experimental-websockets",
"Using aliases": "/advanced/using-aliases",
- "Using with Java": "/advanced/java",
- "Kotlin native": "/advanced/kotlin-native",
+ "Using Java": "/advanced/java",
"Apollo AST": "/advanced/apollo-ast",
"Compiler plugins": "/advanced/compiler-plugins",
"JS Interoperability": "/advanced/js-interop",
diff --git a/docs/source/essentials/custom-scalars.mdx b/docs/source/essentials/custom-scalars.mdx
index 7a3351cb052..e6b2eca8523 100644
--- a/docs/source/essentials/custom-scalars.mdx
+++ b/docs/source/essentials/custom-scalars.mdx
@@ -110,7 +110,7 @@ Make sure you pass the full class name including the package, because imports ar
You can also register adapters on your `ApolloClient` instance by calling `ApolloClient.Builder.addCustomScalarAdapter` once for each adapter:
```kotlin
-val apolloClient = ApolloClient.Builder().serverUrl("https://")
+val apolloClient = ApolloClient.Builder().serverUrl("https://example.com/graphql")
.addCustomScalarAdapter(GeoPoint.type, geoPointAdapter)
.build()
```
@@ -144,13 +144,17 @@ In addition, the `com.apollographql.apollo3:apollo-adapters` artifact provides t
| `com.apollographql.apollo3.adapter.DateAdapter` | For `java.util.Date` ISO8601 dates |
| `com.apollographql.apollo3.adapter.BigDecimalAdapter` | For a Multiplatform `com.apollographql.apollo3.adapter.BigDecimal` class holding big decimal values |
-> **Note:** Because some adapters use `kotlinx.datetime` (which itself uses `java.time`), you need to enable [core library desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring) on Android API levels < 26
+
+
+Because some adapters use `kotlinx.datetime` (which itself uses `java.time`), you need to enable [core library desugaring](https://developer.android.com/studio/write/java8-support#library-desugaring) on Android API levels < 26
+
+
For example, to use `DateAdapter`, configure your Gradle scripts like so:
```kotlin title="build.gradle[.kts]"
dependencies {
- implementation("com.apollographql.apollo3:apollo-adapters:4.0.0-beta.5")
+ implementation("com.apollographql.apollo3:apollo-adapters:4.0.0-beta.7")
}
apollo {
diff --git a/docs/source/essentials/fragments.mdx b/docs/source/essentials/fragments.mdx
index 46c75288aef..2f7172465c0 100644
--- a/docs/source/essentials/fragments.mdx
+++ b/docs/source/essentials/fragments.mdx
@@ -2,7 +2,11 @@
title: Fragments in Apollo Kotlin
---
-> **Note:** This article describes the behavior of fragments when using the default `operationBased` codegen in Apollo Kotlin. For the `responseBased` codegen, see [this page](../advanced/codegen-methods).
+
+
+This article describes the behavior of fragments when using the default `operationBased` codegen in Apollo Kotlin. For the `responseBased` codegen, see [this page](../advanced/response-based).
+
+
Apollo Kotlin supports both forms of [GraphQL fragments](https://graphql.org/learn/queries/#fragments):
@@ -16,7 +20,7 @@ Take a look at the following GraphQL definitions:
```graphql title="Launch.graphql"
# Declaration of named fragment
-fragment launchFragment on Launch {
+fragment LaunchFragment on Launch {
id
site
mission {
@@ -27,7 +31,7 @@ fragment launchFragment on Launch {
query LaunchDetails($id:ID!) {
launch(id: $id) {
# Usage of named fragment
- ...launchFragment
+ ...LaunchFragment
}
}
```
@@ -58,7 +62,7 @@ You can reuse the fragment in any number of operations:
query LaunchList {
launches {
launches {
- ...launchFragment
+ ...LaunchFragment
}
}
}
@@ -70,7 +74,7 @@ You can even use a fragment in operations that are defined in a different `.grap
Take a look at this query definition that uses two inline fragments:
-```graphql {4-9} title="HeroQuery.graphql"
+```graphql {4-9} title="HeroForEpisode.graphql"
query HeroForEpisode($ep: Episode!) {
hero(episode: $ep) {
name
@@ -91,4 +95,4 @@ println("Droid primaryFunction: ${hero.onDroid?.primaryFunction}")
println("Human height: ${hero.onHuman?.height}")
```
-> These `on` fields (`onDroid` and `onHuman`) are `null` if the returned object is _not_ the corresponding type.
+> These `on` fields (`onDroid` and `onHuman`) are `null` if the returned object is _not_ of the corresponding type.
diff --git a/docs/source/essentials/mutations.mdx b/docs/source/essentials/mutations.mdx
index ef0e7bbd815..7450e304a3a 100644
--- a/docs/source/essentials/mutations.mdx
+++ b/docs/source/essentials/mutations.mdx
@@ -19,7 +19,7 @@ mutation UpvotePost($postId: Int!) {
And here's an example schema snippet that supports this mutation:
-```graphql title="schema.graphql"
+```graphql title="schema.graphqls"
type Mutation {
upvotePost(postId: Int!): Post
}
@@ -57,7 +57,7 @@ For more information on mutation return types, see [Designing mutations](https:/
Similar to queries, mutations are represented by instances of generated classes, conforming to the `Mutation` interface.
Constructor arguments are used to define mutation variables. You pass a mutation object
-to `ApolloClient#mutation(mutation)` to send the mutation to the server, execute it, and receive typed results:
+to `ApolloClient.mutation(mutation)` to send the mutation to the server, execute it, and receive typed results:
```kotlin
diff --git a/docs/source/essentials/queries.mdx b/docs/source/essentials/queries.mdx
index cd057b53994..b1eb61af61e 100644
--- a/docs/source/essentials/queries.mdx
+++ b/docs/source/essentials/queries.mdx
@@ -28,11 +28,11 @@ query HeroQuery($id: String!) {
}
```
-If we define this query in its own `.graphql` file, Apollo Kotlin will generate a corresponding `HeroQuery` class that we can then use to [execute the query](#executing).
+Apollo Kotlin will generate a corresponding `HeroQuery` class that we can then use to [execute the query](#executing).
To generate classes, Apollo Kotlin requires your server's schema, along with all of the `.graphql` files that contain your defined operations. It uses these to generate code you can use to execute queries and access typed results.
-> All `.graphql` files in your project (or the subset you specify as input to `apollo-codegen` if you customize the script for your code generation build phase) are combined and treated as _one_ GraphQL document. This means that fragments defined in one `.graphql` file are available across _all_ `.graphql` files. However, it _also_ means that operation and fragment names must be unique (and validation errors will occur if they aren't).
+> All `.graphql` files in your project are combined and treated as _one_ GraphQL document. This means that fragments defined in one `.graphql` file are available across _all_ `.graphql` files. However, it _also_ means that operation and fragment names must be unique (and validation errors will occur if they aren't).
## Executing
@@ -40,13 +40,13 @@ To generate classes, Apollo Kotlin requires your server's schema, along with all
To execute the query we [just defined](#defining), we pass a `HeroQuery` instance to the `query` method of `ApolloClient`, like so:
```kotlin {2}
-val apolloClient = ApolloClient.Builder().serverUrl("https://your.domain/graphql").build()
+val apolloClient = ApolloClient.Builder().serverUrl("https://example.com/graphql").build()
val response = apolloClient.query(HeroQuery(id = "12")).execute()
```
By default, Apollo Kotlin offloads I/O work to a background thread, which means it's safe to start GraphQL operations on the main thread. The result is also dispatched to the calling thread, and you can use the response directly to update your data.
-* On the JVM, the I/O work is using `Dispatchers.IO` by default. You can change this dispatcher with `ApolloClient.Builder.dispatcher`.
+* On the Android and JVM, the I/O work is using `Dispatchers.IO` by default. You can change this dispatcher with `ApolloClient.Builder.dispatcher`.
* On [Kotlin/native](https://kotlinlang.org/docs/native-overview.html) (iOS, macOS, ...), the request offloads the cache and network I/O to background threads that resume in the main dispatch queue. For this reason,
the `ApolloClient` APIs assume they are called from the main thread. It isn't possible to customize the dispatcher, but cache and network
I/O are always done in background threads.
diff --git a/docs/source/essentials/subscriptions.mdx b/docs/source/essentials/subscriptions.mdx
index 4472b7abc5f..0fd1763fcbf 100644
--- a/docs/source/essentials/subscriptions.mdx
+++ b/docs/source/essentials/subscriptions.mdx
@@ -36,13 +36,16 @@ To use subscriptions over WebSocket, use `WebSocketNetworkTransport`:
val apolloClient = ApolloClient.Builder()
.subscriptionNetworkTransport(
WebSocketNetworkTransport.Builder()
- .serverUrl("https://apollo-fullstack-tutorial.herokuapp.com/graphql")
+ .serverUrl("https://example.com/graphql")
.build()
)
.build()
```
+
-> **Note:** Apollo Kotlin supports both `https://` (or `http://`) and `wss://` (or `ws://`) protocols. Internally, `wss://` is renamed to `https://` and which one you use does not matter.
+Apollo Kotlin supports both `https://` (or `http://`) and `wss://` (or `ws://`) protocols. Internally, `wss://` is renamed to `https://` and which one you use does not matter.
+
+
### Customizing your WebSocket protocol
@@ -68,7 +71,7 @@ val apolloClient = ApolloClient.Builder()
.subscriptionNetworkTransport(
WebSocketNetworkTransport.Builder()
.protocol(GraphQLWsProtocol.Factory()) // highlight-line
- .serverUrl("https://apollo-fullstack-tutorial.herokuapp.com/graphql")
+ .serverUrl("https://example.com/graphql")
.build()
)
.build()
@@ -127,7 +130,7 @@ To use HTTP for subscriptions, use `HttpNetworkTransport` like so:
val apolloClient = ApolloClient.Builder()
.subscriptionNetworkTransport(
HttpNetworkTransport.Builder()
- .serverUrl("https://apollo-fullstack-tutorial.herokuapp.com/graphql")
+ .serverUrl("https://example.com/graphql")
.build()
)
.build()
@@ -137,7 +140,7 @@ This is the only configuration required. `HttpNetworkTransport` will use [chunke
## Listening to a subscription
-After you configure the `NetworkTransport`, use `ApolloClient.subscribe` to open the connection and listen for changes:
+After you configure the `NetworkTransport`, use `ApolloClient.subscription` to open the connection and listen for changes:
```kotlin
apolloClient.subscription(TripsBookedSubscription())
@@ -147,7 +150,7 @@ apolloClient.subscription(TripsBookedSubscription())
}
```
-Because subscriptions are long-lasting operations, they return a `Flow` instead of a single `Response`.
+Because subscriptions are long-lasting operations, you should call `toFlow()` to get a `Flow` instead of a single `Response`.
## Terminating a subscription
@@ -162,3 +165,9 @@ Like queries, subscriptions support partial responses with GraphQL errors, which
Network errors terminate the `Flow`, and you need to retry to get new updates. Depending on the situation, retrying might open a new WebSocket or restart the subscription.
See also [this section](../advanced/websocket-errors) about WebSocket errors handling.
+
+## Experimental WebSockets
+
+Starting with 4.0.0, Apollo Kotlin provides a new experimental WebSockets implementation that aim to replace the current implementation in the future.
+
+If you are interested in trying them out, please consult [the dedicated section](../advanced/experimental-websockets).
diff --git a/docs/source/fetching/defer.mdx b/docs/source/fetching/defer.mdx
index 74e975b00e3..8677e77bb41 100644
--- a/docs/source/fetching/defer.mdx
+++ b/docs/source/fetching/defer.mdx
@@ -1,16 +1,19 @@
---
title: 'Using the @defer directive in Apollo Kotlin'
description: 'Fetch slower schema fields asynchronously'
-minVersion: 3.6.0
---
-> โ ๏ธ **The `@defer` directive is currently [experimental](https://www.apollographql.com/docs/resources/product-launch-stages/#experimental-features) in Apollo Kotlin and enabled for use by default.** If you have feedback on it, please let us know via [GitHub issues](https://github.com/apollographql/apollo-kotlin/issues/new?assignees=&labels=Type%3A+Bug&template=bug_report.md&title=[Defer%20Support]) or in the [Kotlin Slack community](https://slack.kotl.in/).
+
-Beginning with version `3.6.0`, Apollo Kotlin provides experimental support of [the `@defer` directive](https://github.com/graphql/graphql-wg/blob/main/rfcs/DeferStream.md), which enables your queries to receive data for specific fields asynchronously. This is helpful whenever some fields in a query take much longer to resolve than the others.
+**The `@defer` directive is currently [experimental](https://www.apollographql.com/docs/resources/product-launch-stages/#experimental-features) in Apollo Kotlin.** If you have feedback on it, please let us know via [GitHub issues](https://github.com/apollographql/apollo-kotlin/issues/new?assignees=&labels=Type%3A+Bug&template=bug_report.md) or in the [Kotlin Slack community](https://slack.kotl.in/).
+
+
+
+Apollo Kotlin provides experimental support of [the `@defer` directive](https://github.com/graphql/graphql-wg/blob/main/rfcs/DeferStream.md), which enables your queries to receive data for specific fields asynchronously. This is helpful whenever some fields in a query take much longer to resolve than the others.
For example, let's say we're building a social media application that can quickly fetch a user's basic profile information, but retrieving that user's friends takes longer. If we include _all_ of those fields in a single query, we want to be able to display the profile information as soon as it's available, instead of waiting for the friend fields to resolve.
-To achieve this, we can apply the `@defer` directive to an in-line fragment that contains all slow-resolving fields related to friend data:
+To achieve this, we can apply the `@defer` directive to an inline fragment that contains all slow-resolving fields related to friend data:
```graphql
query PersonQuery($personId: ID!) {
@@ -39,7 +42,7 @@ When the fields of the fragment are available, a new `Person` will be emitted, t
```kotlin
apolloClient.query(PersonQuery(personId)).toFlow().collect {
println("Received: $it")
- if (it.dataAssertNoErrors.person.onUser == null) {
+ if (it.dataOrThrow().person.onUser == null) {
// Initial payload: basic info only
// ...
} else {
@@ -58,11 +61,11 @@ Received: Person(id=1, firstName=John, lastName=Doe, onUser=OnUser(friends=[Frie
### Limitations/known issues
* `@defer` cannot be used with `responseBased` codegen.
-* Some servers might send an empty payload to signal the end of the stream. In such a case you will receive an extra terminal emission. You can filter it out by using `distinct()`:
+* Some servers might send an empty payload to signal the end of the stream. In such a case you will receive an extra terminal emission. You can filter it out by using `distinctUntilChangedBy()`:
```kotlin
apolloClient.query(MyQuery()).toFlow()
- .distinct() // filter out duplicates
+ .distinctUntilChangedBy { it.data } // filter out duplicates
.collect { /* ... */ }
```
diff --git a/docs/source/index.md b/docs/source/index.md
index 26e900742b4..7a3b623bda2 100644
--- a/docs/source/index.md
+++ b/docs/source/index.md
@@ -1,21 +1,21 @@
---
title: Introduction to Apollo Kotlin
-description: A strongly-typed, caching GraphQL client for Java and Kotlin multiplatform
+description: A strongly-typed, caching GraphQL client for the JVM, Android, and Kotlin multiplatform.
---
> ๐ฃ **Apollo Kotlin 3 is generally available.** If you're using Apollo Android 2.x, see the [migration guide](./migration/3.0/). You can also [view the 2.x docs](https://www.apollographql.com/docs/kotlin/v2).
-[Apollo Kotlin](https://github.com/apollographql/apollo-kotlin) (formerly Apollo Android) is a GraphQL client that generates Kotlin and Java models from GraphQL queries.
+[Apollo Kotlin](https://github.com/apollographql/apollo-kotlin) (formerly Apollo Android) is a GraphQL client that generates Kotlin and Java models from GraphQL operations.
-Apollo Kotlin executes queries and mutations against a GraphQL server and returns results as query-specific Kotlin types. This means you don't have to deal with parsing JSON, or passing around `Map`s and making clients cast values to the right type manually. You also don't have to write model types yourself, because these are generated from the GraphQL definitions your UI uses.
+Apollo Kotlin executes operations against a GraphQL server and returns results as operation-specific Kotlin types. This means you don't have to deal with parsing JSON, or passing around `Map`s and making clients cast values to the right type manually. You also don't have to write model types yourself, because these are generated from the GraphQL definitions your app uses.
-Because generated types are query-specific, you can only access data that you actually specify as part of a query. If you don't ask for a particular field in a query, you can't access the corresponding property on the returned data structure.
+Because generated types are operation-specific, you can only access data that you actually specify as part of an operation. If you don't ask for a particular field in an operation, you can't access the corresponding property on the returned data structure.
-This library is designed primarily with Android in mind, but you can use it in any Java/Kotlin app, including multiplatform.
+This library is designed primarily with Android in mind, but you can use it in any Kotlin (including multiplatform) and Java app.
## Features
-* Java and Kotlin Multiplatform code generation
+* Kotlin Multiplatform and Java code generation
* Queries, Mutations and Subscriptions
* Reflection-free parsing
* Normalized cache
@@ -24,10 +24,10 @@ This library is designed primarily with Android in mind, but you can use it in a
* Auto Persisted Queries
* Query batching
* File uploads
-* Espresso IdlingResource
* Fake models for tests
* AppSync and graphql-ws websockets
* GraphQL AST parser
+* Plugin for Android Studio and IntelliJ
## Multiplatform
@@ -35,14 +35,14 @@ Apollo Kotlin is a [Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatf
Here's the current matrix of supported features per platform:
-| | `jvm` | `Appleยน` | `js` | `linuxX64`
-| --- | :---: | :---: |:----:| :---: |
-| `apollo-api` (models)|โ |โ | โ |โ |
-| `apollo-runtime` (network, query batching, apq, ...) |โ |โ | โ |๐ซ|
-| `apollo-normalized-cache` |โ |โ | โ |๐ซ|
-| `apollo-adapters` |โ |โ | โ |๐ซ|
-| `apollo-normalized-cache-sqlite` |โ |โ | ๐ซ |๐ซ|
-| `apollo-http-cache` |โ |๐ซ| ๐ซ |๐ซ|
+| | `jvm` | `Appleยน` | `js` | `wasmJs` | `linuxX64` |
+|------------------------------------------------------|:-----:|:--------:|:----:|:--------:|:----------:|
+| `apollo-api` (models) | โ | โ | โ | โ | โ |
+| `apollo-runtime` (network, query batching, apq, ...) | โ | โ | โ | โ | ๐ซ |
+| `apollo-normalized-cache` | โ | โ | โ | โ | ๐ซ |
+| `apollo-adapters` | โ | โ | โ | โ | ๐ซ |
+| `apollo-normalized-cache-sqlite` | โ | โ | ๐ซ | ๐ซ | ๐ซ |
+| `apollo-http-cache` | โ | ๐ซ | ๐ซ | ๐ซ | ๐ซ |
ยน: Apple currently includes:
@@ -60,7 +60,7 @@ Here's the current matrix of supported features per platform:
## Getting started
-If you are new to GraphQL, check out [the tutorial](./tutorial/00-introduction/) that will guide you through building an Android app using Apollo, Kotlin and coroutines.
+If you are new to GraphQL, check out [the tutorial](./tutorial/00-introduction/) that will guide you through building an Android app using Apollo.
If you'd like to add Apollo Kotlin to an existing project, follow these steps:
@@ -68,7 +68,7 @@ Add the plugin to your `build.gradle.kts`:
```kotlin
plugins {
- id("com.apollographql.apollo3") version "4.0.0-beta.5"
+ id("com.apollographql.apollo3") version "4.0.0-beta.7"
}
```
@@ -76,7 +76,7 @@ Add the runtime dependency:
```kotlin
dependencies {
- implementation("com.apollographql.apollo3:apollo-runtime:4.0.0-beta.5")
+ implementation("com.apollographql.apollo3:apollo-runtime:4.0.0-beta.7")
}
```
@@ -101,7 +101,7 @@ By default, Apollo Kotlin requires a schema in your module's `src/main/graphql`
cp ${schema} ${module}/src/main/graphql/
```
-Write a query in a `${module}/src/main/graphql/GetRepository.graphql` file:
+Write a query in a `${module}/src/main/graphql/HeroQuery.graphql` file:
```graphql
query HeroQuery($id: String!) {
@@ -144,9 +144,8 @@ Some platforms have specific runtime requirements:
At build time, it requires:
* Gradle 8.0+
-* Kotlin 1.8+ for JVM projects
-* Kotlin 1.9+ for native projects
-* Kotlin 2.0+ for JS projects
+* Kotlin 1.9+ for JVM projects
+* Kotlin 2.0+ for native, JS, and Wasm projects
## Proguard / R8 configuration
@@ -154,7 +153,7 @@ As the code generated by Apollo Kotlin doesn't use any reflection, it can safely
## Android Studio / IntelliJ plugin
-An experimental [plugin for Android Studio and IntelliJ](https://plugins.jetbrains.com/plugin/20645-apollo-graphql) is available to help you work with Apollo Kotlin, providing automatic code generation, integration with the [GraphQL IntelliJ Plugin](https://plugins.jetbrains.com/plugin/8097-js-graphql), navigation to GraphQL definitions, migration helpers, and more.
+A [plugin for Android Studio and IntelliJ](https://plugins.jetbrains.com/plugin/20645-apollo-graphql) is available to help you work with Apollo Kotlin, providing automatic code generation, integration with the [GraphQL IntelliJ Plugin](https://plugins.jetbrains.com/plugin/8097-js-graphql), navigation to GraphQL definitions, migration helpers, and more.
Installation instructions and more information can be found [here](testing/android-studio-plugin).
@@ -166,10 +165,9 @@ Check the [changelog](https://github.com/apollographql/apollo-kotlin/releases) f
Releases are hosted on [Maven Central](https://repo1.maven.org/maven2/com/apollographql/apollo3/). The plugin is additionally hosted on the [Gradle Plugin Portal](https://plugins.gradle.org/plugin/com.apollographql.apollo3)
-
```kotlin
plugins {
- id("com.apollographql.apollo3") version "4.0.0-beta.5"
+ id("com.apollographql.apollo3") version "4.0.0-beta.7"
}
repositories {
@@ -177,13 +175,13 @@ repositories {
}
dependencies {
- implementation("com.apollographql.apollo3:apollo-runtime:4.0.0-beta.5")
+ implementation("com.apollographql.apollo3:apollo-runtime:4.0.0-beta.7")
- // optional: if you want to use the normalized cache
- implementation("com.apollographql.apollo3:apollo-normalized-cache-sqlite:4.0.0-beta.5")
- // optional: if you just want the generated models and parsers and write your own HTTP code/cache code, you can remove apollo-runtime
+ // Optional: if you want to use the normalized cache
+ implementation("com.apollographql.apollo3:apollo-normalized-cache-sqlite:4.0.0-beta.7")
+ // Optional: if you just want the generated models and parsers and write your own HTTP code/cache code, you can remove apollo-runtime
// and use apollo-api instead
- implementation("com.apollographql.apollo3:apollo-api:4.0.0-beta.5")
+ implementation("com.apollographql.apollo3:apollo-api:4.0.0-beta.7")
}
```
@@ -213,7 +211,8 @@ pluginManagement {
}
}
```
-And then use the `4.0.0-beta.6-SNAPSHOT` version for the plugin and libraries.
+
+And then use the `4.0.0-beta.8-SNAPSHOT` version for the plugin and libraries.
These snapshots are updated on each push to `main`.
@@ -221,10 +220,10 @@ Weekly snapshots for the Android Studio / IntelliJ plugin [are also available](t
## Stability of different artifacts
-Apollo Kotlin is very modular and publishes several artifacts.
+Apollo Kotlin is very modular and publishes several artifacts.
* Artifacts ending with `-incubating` are not finalized yet and subject to change any time.
-* Other artifacts observe [Semantic Versioning](https://semver.org/).
+* Other artifacts observe [Semantic Versioning](https://semver.org/).
* No breaking change should be introduced in minor or patch releases except for symbols annotated with `@ApolloExperimental` that are subject to change at any time.
* Deprecated symbols may be removed in the next major release. We strongly recommend removing deprecated usages before migrating to the next major version.
diff --git a/docs/source/migration/4.0.mdx b/docs/source/migration/4.0.mdx
index 8f19fe0cc80..70843bfe02e 100644
--- a/docs/source/migration/4.0.mdx
+++ b/docs/source/migration/4.0.mdx
@@ -4,7 +4,9 @@ description: From 3.x
---
-Version 4 is currently under development and this page itself is a work in progress.
+
+**Version 4 is currently under development and this page itself is a work in progress.**
+
Apollo Kotlin 3.0 was a major rewrite of Apollo in Kotlin multiplatform.
@@ -13,24 +15,26 @@ Apollo Kotlin 4.0 focuses on tooling, stability and fixing some API regrets that
Because most of the common APIs stayed the same, we [kept the package name unchanged](https://github.com/apollographql/apollo-kotlin/issues/4710). Apollo Kotlin 4.0 removes some deprecated symbols. We strongly recommend removing deprecated usages before migrating to 4.0.
-If you are using a lib that depends on Apollo Kotlin transitively, you need it to update to 4.x before you can update your own app to 4.0.
+If you are using a library that depends on Apollo Kotlin transitively, you need it to update to 4.x before you can update your own application to 4.0.
## Automatic migration using the Android Studio plugin
-Apollo Kotlin 4 ships with a companion [Android Studio plugin that automates most of the migration](https://www.apollographql.com/docs/kotlin/v4/testing/android-studio-plugin#migration-helpers).
+Apollo Kotlin 4 ships with a companion [Android Studio plugin](../testing/android-studio-plugin#migration-helpers) that automates most of the migration.
-It automates most of the API replacements but cannot deal with behaviour changes like error handling.
+It automates most of the API changes but cannot deal with behaviour changes like error handling.
We recommend using the plugin to automate the repetitive tasks but still go through this document for the details.
## Error handling
+
Error handling changes are a behaviour change that is not detected at compile time. Usages of `execute`, `toFlow` and `watch` must be updated to the new error handling or changed to their v3 compat equivalent.
See [`executeV3` and `toFlowV3`](#migration-helpers) for temporary methods to help with the migration.
See [nullability](../advanced/nullability) for a quick peek at the future of GraphQL nullability and error handling.
+
### Fetch errors do not throw
@@ -102,7 +106,7 @@ client.subscription(MySubscription()).toFlow().collect { response ->
Note that this is true for all `Flows`, including watchers. If you don't want to receive error responses, filter them out:
-```
+```kotlin
// Replace
apolloClient.query(query).watch()
@@ -112,12 +116,12 @@ apolloClient.query(query).watch().filter { it.exception == null }
### ApolloCompositeException is not thrown anymore
-When using the cache, Apollo Kotlin 3.x threw `ApolloCompositeException` if no response could be found. For an example, a `CacheFirst` fetch policy would throw `ApolloCompositeException(cacheMissException, apolloNetworkException` if both cache and network failed.
+When using the cache, Apollo Kotlin 3.x threw `ApolloCompositeException` if no response could be found. For an example, a `CacheFirst` fetch policy would throw `ApolloCompositeException(cacheMissException, apolloNetworkException)` if both cache and network failed.
In those cases, Apollo Kotlin 4.0 throws the first exception and adds the second as a suppressed exception:
```kotlin
- // Replace
+// Replace
if (exception is ApolloCompositeException) {
val cacheMissException = exception.first
val networkException = exception.second
@@ -152,25 +156,27 @@ Because of the number of different options in 3.x and the complexity of error ha
## Other Apollo Runtime changes
-### HTTP headers
+### Non standard HTTP headers are not sent by default
`X-APOLLO-OPERATION-NAME` and `X-APOLLO-OPERATION-ID` are non-standard headers and are not sent by default anymore. If you used them for logging purposes or if you are using Apollo Server [CSRF prevention](https://www.apollographql.com/docs/apollo-server/security/cors/#preventing-cross-site-request-forgery-csrf), you can add them back using an [ApolloInterceptor](https://www.apollographql.com/docs/kotlin/kdoc/apollo-runtime/com.apollographql.apollo3.interceptor/-apollo-interceptor/index.html?query=interface%20ApolloInterceptor):
```kotlin
- val apolloClient = ApolloClient.Builder()
- .serverUrl(mockServer.url())
- .addInterceptor(object : ApolloInterceptor {
- override fun intercept(request: ApolloRequest, chain: ApolloInterceptorChain): Flow> {
- return chain.proceed(request.newBuilder()
- .addHttpHeader("X-APOLLO-OPERATION-NAME", request.operation.name())
- .addHttpHeader("X-APOLLO-OPERATION-ID", request.operation.id())
- .build()
- )
- }
- })
- .build()
+val apolloClient = ApolloClient.Builder()
+ .serverUrl(mockServer.url())
+ .addInterceptor(object : ApolloInterceptor {
+ override fun intercept(request: ApolloRequest, chain: ApolloInterceptorChain): Flow> {
+ return chain.proceed(request.newBuilder()
+ .addHttpHeader("X-APOLLO-OPERATION-NAME", request.operation.name())
+ .addHttpHeader("X-APOLLO-OPERATION-ID", request.operation.id())
+ .build()
+ )
+ }
+ })
+ .build()
```
+### `ApolloCall.Builder.httpHeaders` is additive
+
In v3, if HTTP headers were set on an `ApolloCall`, they would replace the ones set on `ApolloClient`. In v4 they are added instead by default. To replace them, call `ApolloCall.Builder.ignoreApolloClientHttpHeaders(true)`.
```kotlin
@@ -190,7 +196,43 @@ val call = client.query(MyQuery())
`HttpEngine` now implements `Closeable` and has its `dispose` method renamed to `close`. If you have a custom `HttpEngine`, you need to implement `close` instead of `dispose`.
-## Apollo Gradle Plugin
+
+## Maven artifacts reorganization
+
+Over the years, a lot of support functionality was added alongside `apollo-api` and `apollo-runtime`. While useful, most of this functionality doesn't share the same level of stability and maturity as the main artifacts and bundling them did not make much sense.
+
+Moving forward, some artifacts are released separately and have new Maven coordinates, GitHub repositories and package names. Others are deprecated.
+
+For the initial v4 release, most artifacts are kept with deprecation warnings and will be removed in the future.
+
+The artifacts are:
+
+* apollo-mockserver
+ * MockServer was born out of our own internal needs for a KMP-ready mockserver. Most of its public API is subject to change, and it has been moved to a separate repository.
+* apollo-cli-incubating
+ * The Apollo CLI contract is subject to change and it has been moved to a separate repository.
+* apollo-rx-support
+ * The RxJava{2-3} artifacts are very thin wrappers around kotlinx-coroutines-rx{2-3} and we recommend using those instead.
+* apollo-idling-resource
+ * ApolloIdlingResource is deprecated. We recommend using reactive patterns to test your UI instead. See [this article about ways to do so](https://medium.com/androiddevelopers/alternatives-to-idling-resources-in-compose-tests-8ae71f9fc473) for more details.
+
+### Summary
+
+| Old coordinates | New coordinates | New Repository |
+|--------------------------------------------------|------------------------------------------------|:----------------------------------------------------------|
+| com.apollographql.apollo3:apollo-mockserver | com.apollographql.mockserver:apollo-mockserver | https://github.com/apollographql/apollo-kotlin-mockserver |
+| com.apollographql.apollo3:apollo-cli-incubating | com.apollographql.cli:apollo-cli | https://github.com/apollographql/apollo-kotlin-cli |
+| com.apollographql.apollo3:apollo-idling-resource | Deprecated | Deprecated |
+| com.apollographql.apollo3:apollo-rx2-support | Deprecated | Deprecated |
+| com.apollographql.apollo3:apollo-rx3-support | Deprecated | Deprecated |
+
+
+| Old package name | New package name |
+|--------------------------------------|------------------------------|
+| com.apollographql.apollo3.mockserver | com.apollographql.mockserver |
+| com.apollographql.apollo3.cli | com.apollographql.cli |
+
+## Gradle Plugin
### Multi-module `dependsOn`
@@ -330,15 +372,58 @@ If you are using `packageNamesFromFilePaths` and `schemaFile`, you'll need to us
```
+
Apollo Kotlin 3 was using the operation root directories to compute the schema normalized path which could be wrong in some edge cases. Using fileTree ensures the normalized path is consistent.
+
-### Misc
+### Migrating to ApolloCompilerPlugin
+
+4.0 introduces `ApolloCompilerPlugin` as a way to customize code generation. `ApolloCompilerPlugin` are loaded using the [ServiceLoader](https://docs.oracle.com/javase/8/docs/api/java/util/ServiceLoader.html) API and run in a separate classloader from your Gradle build. As a result, using `Service.operationIdGenerator`/`Service.operationOutputGenerator` together with `ApolloCompilerPlugin` is not possible.
+
+`Service.operationIdGenerator`/`Service.operationOutputGenerator` are deprecated and will be removed in a future release. You can migrate to `ApolloCompilerPlugin` using the instructions [from the dedicated page](https://www.apollographql.com/docs/kotlin/v4/advanced/compiler-plugins) and the `ApolloCompilerPlugin.operationIds()` method:
+
+```kotlin
+// Replace (in your build scripts)
+val operationOutputGenerator = object: OperationOutputGenerator {
+ override fun generate(operationDescriptorList: Collection): OperationOutput {
+ return operationDescriptorList.associateBy {
+ it.source.sha1()
+ }
+ }
+ override val version: String = "v1"
+}
+
+// Or, if using OperationIdGenerator, replace
+val operationIdGenerator = object: OperationIdGenerator {
+ override fun apply(operationDocument: String, operationName: String): String {
+ return operationDocument.sha1()
+ }
+
+ override val version: String = "v1"
+}
+
+// With (in your build compiler plugin module)
+class MyPlugin: ApolloCompilerPlugin {
+ override fun operationIds(descriptors: List): List? {
+ return descriptors.map {
+ OperationId(it.source.sha1(), it.name)
+ }
+ }
+}
+```
+
+### Publishing is no longer configured automatically
+
+In Apollo Kotlin 3, maven publishing was automatically configured. In Apollo Kotlin 4, this is no longer the case, and you need to configure the publishing tasks yourself.
-* Publishing is no longer configured automatically.
-* Because Apollo Kotlin now supports different operation manifest formats, `operationOutput.json` has moved from `"build/generated/operationOutput/apollo/$service/operationOutput.json"` to `"build/generated/manifest/apollo/$service/operationOutput.json"`
-* useSchemaPackageNameForFragments is removed
+### Operation manifest file location
+Since Apollo Kotlin now supports [different operation manifest formats](../advanced/persisted-queries), the `operationOutput.json` file will be generated in `"build/generated/manifest/apollo/$service/operationOutput.json"` instead of `"build/generated/operationOutput/apollo/$service/operationOutput.json"`.
+
+### `useSchemaPackageNameForFragments` is removed
+
+This was provided for compatibility with 2.x and is now removed. If you need specific package names for fragments, you can use a [compiler plugin](../advanced/compiler-plugins) and `ApolloCompilerPlugin.layout()` instead.
## Apollo Compiler
@@ -405,7 +490,19 @@ data.hero.name
*/
data.hero.onCharacter?.name
```
-> The [Android Studio plugin](https://www.apollographql.com/docs/kotlin/v4/testing/android-studio-plugin#migration-helpers) provides a compat to operationBased migration tool which automates a lot of these changes.
+
+
+
+The [Android Studio plugin](../testing/android-studio-plugin#migration-helpers) provides a `compat` to `operationBased` migration tool which automates a lot of these changes.
+
+
+
+### Test builders are removed
+
+Test builders were an experimental feature that have been superseded by [data builders](../testing/data-builders), a simpler version that also plays nicer with custom scalars.
+
+In Apollo Kotlin 4.0, test builders are no longer available - please refer to the data builders documentation for more information.
+
### Enum class names now have their first letter capitalized
For consistency with other types, GraphQL enums are now capitalized in Kotlin. You can restore the previous behaviour using `@targetName`:
@@ -420,7 +517,7 @@ enum someEnum @targetName(name: "someEnum"){
### `__Schema` is in the `schema` subpackage
-If using the `generateSchema` option, and to avoid a name clash with the introspection type of the same name, the `__Schema` type is now generated in a `schema` subpackage (instead of `type`) when using the `generateSchema` option:
+When using the `generateSchema` option, to avoid a name clash with the introspection type of the same name, the `__Schema` type is now generated in a `schema` subpackage (instead of `type`):
```kotlin
// Replace
@@ -430,9 +527,9 @@ import com.example.type.__Schema
import data.builders.schema.__Schema
```
-### KotlinLabs directives are now version 0.2
+### KotlinLabs directives are now at version 0.3
-The embedded [kotlinlabs/0.2](https://specs.apollo.dev/kotlin_labs/v0.2/) directives are now version 0.2.
+The embedded [kotlin_labs](https://specs.apollo.dev/kotlin_labs/v0.3/) directives are now at version 0.3.
These are the client directives supported by Apollo Kotlin. They are imported automatically but if you relied on an explicit import for renames or another reason, you'll need to bump the version:
@@ -441,11 +538,45 @@ These are the client directives supported by Apollo Kotlin. They are imported au
extend schema @link(url: "https://specs.apollo.dev/kotlin_labs/v0.1/", import: ["@typePolicy"])
# With
-extend schema @link(url: "https://specs.apollo.dev/kotlin_labs/v0.2/", import: ["@typePolicy"])
+extend schema @link(url: "https://specs.apollo.dev/kotlin_labs/v0.3/", import: ["@typePolicy"])
```
This is a backward compatible change.
+### Directive usages are validated and require a matching directive definition
+
+In Apollo 4, all directive usages are validated against their definition. If you have queries using client side directives:
+
+```graphql
+query HeroName {
+ hero {
+ # WARNING: '@required' is not defined by the schema
+ name @required
+ }
+}
+```
+
+Those queries now required to have a matching directive definition in the schema. If the directive is a server directive, and you downloaded your schema using introspection, the directive definition should be present.
+
+In some cases, for client directives and/or if you did not use introspection, the directive definition might be missing. For those cases, you can add it explicitely in a `extra.graphqls` file:
+
+```graphql
+directive @required on FIELD
+```
+
+### Sealed class `UNKNOWN__` constructors are private
+
+When generating enums as sealed classes with the `sealedClassesForEnumsMatching` option, the `UNKNOWN__` constructor is now generated as private, to prevent its accidental usage.
+
+It is recommended to update your schema instead of instantiating an `UNKNOWN__` value, but if you need to, use the `safeValueOf` method instead:
+
+```kotlin
+// Replace
+val myEnum = MyEnum.UNKNOWN__("foo")
+
+// With
+val myEnum = MyEnum.safeValueOf("foo")
+```
## Cache
@@ -460,6 +591,22 @@ In Apollo Kotlin 4.0 this is still the case but the functions are no longer mark
The normalized cache must be configured before the auto persisted queries, configuring it after will now fail (see https://github.com/apollographql/apollo-kotlin/pull/4709).
+```kotlin
+// Replace
+val apolloClient = ApolloClient.Builder()
+ .serverUrl(...)
+ .autoPersistedQueries(...)
+ .normalizedCache(...)
+ .build()
+
+// With
+val apolloClient = ApolloClient.Builder()
+ .serverUrl(...)
+ .normalizedCache(...)
+ .autoPersistedQueries(...)
+ .build()
+```
+
## apollo-ast
The AST classes (`GQLNode` and subclasses) as well as `Introspection` classes are not data classes anymore (see https://github.com/apollographql/apollo-kotlin/pull/4704/). The class hierarchy has been tweaked so that `GQLNamed`, `GQLDescribed` and `GQLHasDirectives` are more consistently inherited from.
@@ -468,7 +615,7 @@ The AST classes (`GQLNode` and subclasses) as well as `Introspection` classes ar
`GQLInlineFragment.typeCondition` is now nullable to account for inline fragments who inherit their type condition.
-`SourceLocation.position` is renamed `SourceLocation.column` and is now 1-indexed. `GQLNode.sourceLocation` is now nullable to account for the cases where the nodes are constructed programmatically.
+`SourceLocation.position` is renamed to `SourceLocation.column` and is now 1-indexed. `GQLNode.sourceLocation` is now nullable to account for the cases where the nodes are constructed programmatically.
It is not possible to create a `Schema` from a File or String directly anymore. Instead, create a `GQLDocument` first and convert it to a schema with `toSchema()`.
@@ -506,7 +653,8 @@ apolloClient.query().rxSingle()
apolloClient.query().toFlow().asFlowable().firstOrError()
```
+
+
## Example of a migration
If you are looking for inspiration, we updated the [3.x integration tests to use 4.0](https://github.com/apollographql/apollo-kotlin/pull/5418/). If you have an open source project that migrated, feel free to share it and we'll include it here.
-
diff --git a/docs/source/testing/android-studio-plugin.mdx b/docs/source/testing/android-studio-plugin.mdx
index a16872d95b3..3e8f6624573 100644
--- a/docs/source/testing/android-studio-plugin.mdx
+++ b/docs/source/testing/android-studio-plugin.mdx
@@ -38,7 +38,7 @@ The file structure of the Apollo project is automatically contributed, so there
#### Kotlin โ GraphQL
-When editing Kotlin code, icons will show next to references to generated operation and fragment classes.
+When editing Kotlin code, icons will appear next to references to generated operation and fragment classes.
Clicking on them will navigate to the corresponding GraphQL definition.
You can also go to the GraphQL definition with Cmd Click (Mac) or Ctrl Click (Windows / Linux) on an operation, field, enum, etc.
@@ -81,7 +81,7 @@ This uses the Introspection endpoint or the Registry that you can [configure](..
You can open a GraphQL file in [Apollo Sandbox](https://studio.apollographql.com/sandbox/explorer) with right click | Open in | Apollo Sandbox.
This is a handy way to share operations with coworkers for instance. There, they will be able to execute the operation and see the result.
-This is also accessible from the button at the top of the editor.
+This is also accessible from the button at the top of the editor.
### High latency fields
@@ -106,7 +106,7 @@ To open _in-memory_ caches, consult [the Apollo Debug Server section](apollo-deb
You can also either drag and drop a `.db` file to the tool window to open it, or click on "Open file..." to pick a file to open.
-Once the cache is open, you can search for a record by ID, or browse them from the left side. Clicking on a record will show its fields and their values on the right side.
+Once the cache is open, you can search for records by cache key, or browse them from the left side. Clicking on a record will show its fields and their values on the right side.
diff --git a/docs/source/testing/apollo-debug-server.mdx b/docs/source/testing/apollo-debug-server.mdx
index 7a6d3b462b8..7e944779041 100644
--- a/docs/source/testing/apollo-debug-server.mdx
+++ b/docs/source/testing/apollo-debug-server.mdx
@@ -17,7 +17,7 @@ dependencies {
// ...
// For security, add the dependency to your debug builds only
- debugImplementation("com.apollographql.apollo3:apollo-debug-server:4.0.0-beta.5")
+ debugImplementation("com.apollographql.apollo3:apollo-debug-server:4.0.0-beta.7")
}
```
diff --git a/docs/source/testing/data-builders.mdx b/docs/source/testing/data-builders.mdx
index 78d3c40217d..f625c046f72 100644
--- a/docs/source/testing/data-builders.mdx
+++ b/docs/source/testing/data-builders.mdx
@@ -1,16 +1,22 @@
---
-title: Data builders (experimental)
+title: Data builders
---
-> โ ๏ธ **Data builders are experimental and subject to change.** If you have feedback on them, please let us know via [GitHub issues](https://github.com/apollographql/apollo-kotlin/issues/new?assignees=&labels=Type%3A+Bug&template=bug_report.md&title=[Data%20Builders]) or in the [Kotlin Slack community](https://slack.kotl.in/).
+
-Apollo Kotlin generates models for your operations and parsers that create instances of these models from your network responses. Sometimes though, during tests or in other occasions, it is useful to instantiate models manually with known values. Doing so is not as straightforward as it may seem, especially when fragments are used. Creating `operationBased` models requires instantiating every fragment as well as choosing an appropriate `__typename` for each composite type. Data builders make this easier by providing builders that match the structure of the Json document.
+**Data builders are currently [experimental](https://www.apollographql.com/docs/resources/product-launch-stages/#experimental-features) in Apollo Kotlin.** If you have feedback on them, please let us know via [GitHub issues](https://github.com/apollographql/apollo-kotlin/issues/new?assignees=&labels=Type%3A+Bug&template=bug_report.md) or in the [Kotlin Slack community](https://slack.kotl.in/).
-__Note: previous versions of Apollo Kotlin used test builders. Data builders are a simpler version of test builders that also plays nicer with custom scalars. If you're looking for the test builders documentation, it's still available [here](./test-builders).__
+
+
+Apollo Kotlin generates models for your operations and parsers that create instances of these models from your network responses. Sometimes though, during tests or in other occasions, it is useful to instantiate models manually with known values.
+
+Doing so is not as straightforward as it may seem, especially when fragments are used. Creating `operationBased` models requires instantiating every fragment as well as choosing an appropriate `__typename` for each composite type.
+
+Data builders make this easier by providing builders that match the structure of the Json document.
## Enabling data builders
-To enable data, set the `generateDataBuilders` option to `true`:
+To enable data builders, set the `generateDataBuilders` option to `true`:
```kotlin title="build.gradle[.kts]"
apollo {
@@ -123,7 +129,7 @@ val data = GetHeroes.Data {
## `@skip` and `@include` directives
-By default, the data builders match the types in your schema. If a field is non-null you will either have to provide a value or let the default resolver provide one. This is an issue for `@skip` and `@include` directives where a field might be absent even if it is non-nullable. To account for this case, use the same syntax as for aliases.
+By default, the data builders match the types in your schema. If a field is non-null you will either have to provide a value or let the default resolver provide one. This is an issue for `@skip` and `@include` directives where a field might be absent even if it is non-nullable. To account for this case, use the same syntax as for aliases and set the value to `Optional.Absent`.
```graphql
query Skip($skip: Boolean!) {
diff --git a/docs/source/testing/mocking-graphql-responses.mdx b/docs/source/testing/mocking-graphql-responses.mdx
index f8d3dd095b2..1b895c0b89f 100644
--- a/docs/source/testing/mocking-graphql-responses.mdx
+++ b/docs/source/testing/mocking-graphql-responses.mdx
@@ -1,8 +1,14 @@
---
-title: Mocking GraphQL responses (experimental)
+title: Mocking GraphQL responses
---
-`QueueTestNetworkTransport` is a high-level test API that enables you to specify the GraphQL responses that are returned by your `ApolloClient` instance.
+
+
+**The test network transports are currently [experimental](https://www.apollographql.com/docs/resources/product-launch-stages/#experimental-features) in Apollo Kotlin.** If you have feedback on them, please let us know via [GitHub issues](https://github.com/apollographql/apollo-kotlin/issues/new?assignees=&labels=Type%3A+Bug&template=bug_report.md) or in the [Kotlin Slack community](https://slack.kotl.in/).
+
+
+
+`QueueTestNetworkTransport` is a high-level test API that lets you specify the GraphQL responses that are returned by your `ApolloClient` instance.
> See also [`MockServer`](./mocking-http-responses), which creates a full HTTP server and helps test specific server behaviors, such as error cases, HTTP headers, and timeouts.
@@ -10,13 +16,13 @@ Add the dependency to your project's `build.gradle` file:
```kotlin title="build.gradle[.kts]"
dependencies {
- testImplementation("com.apollographql.apollo3:apollo-testing-support:4.0.0-beta.5")
+ testImplementation("com.apollographql.apollo3:apollo-testing-support:4.0.0-beta.7")
}
```
Enable the `QueueTestNetworkTransport` by passing it to the `ApolloClient` builder:
-```kotlin{2}
+```kotlin {2}
val apolloClient = ApolloClient.Builder()
.networkTransport(QueueTestNetworkTransport())
.build()
@@ -24,7 +30,7 @@ val apolloClient = ApolloClient.Builder()
You can then use the `enqueueTestResponse` extension function to specify the GraphQL responses to return:
-```kotlin{7}
+```kotlin {7}
val testQuery = GetHeroQuery("001")
val testData = GetHeroQuery.Data {
hero = droidHero {
@@ -39,7 +45,7 @@ assertEquals(testData.hero.name, actual.hero.name)
You can pass an `ApolloResponse` to the `enqueueTestResponse` function, or as a shortcut, you can pass a `Data` directly as shown above. If you do pass a `Data`, you _also_ need to pass an operation, because an `ApolloResponse` is built under the hood, which needs a reference to it.
-> To help create your mocked response data, you can use [test builders](./test-builders/).
+> To help create your mocked response data, you can use [data builders](./data-builders/).
### Advanced usage
@@ -49,7 +55,7 @@ In certain tests, it might be more convenient to **map** responses to operations
To achieve this, use `MapTestNetworkTransport` instead and call the `registerTestResponse` extension function:
-```kotlin{1,3-4}
+```kotlin {1,3-4}
val apolloClient = ApolloClient.Builder().networkTransport(MapTestNetworkTransport()).build()
apolloClient.registerTestResponse(query1, testData1)
diff --git a/docs/source/testing/mocking-http-responses.mdx b/docs/source/testing/mocking-http-responses.mdx
index 8d9078185f1..8e1733486f7 100644
--- a/docs/source/testing/mocking-http-responses.mdx
+++ b/docs/source/testing/mocking-http-responses.mdx
@@ -2,7 +2,11 @@
title: Mocking HTTP responses (experimental)
---
-> โน๏ธ `MockServer` is still experimental and most of the APIs are designed for Kotlin. `MockServer` is multiplatform but if you're using Java only, we recommend using [OkHttp MockWebServer](https://github.com/square/okhttp/tree/master/mockwebserver) which will provide idiomatic Java APIs.
+
+
+`MockServer` is still experimental and most of the APIs are designed for Kotlin. `MockServer` is multiplatform but if you're using Java only, we recommend using [OkHttp MockWebServer](https://github.com/square/okhttp/tree/master/mockwebserver) which will provide idiomatic Java APIs.
+
+
`MockServer` implements an HTTP server that you can use to mock responses. It's useful for testing specific server behaviors, such as error cases, HTTP headers, and timeouts. Using it requires minimal changes to your production code, because you only need to change your `serverUrl`.
@@ -12,7 +16,7 @@ Add the dependency to your project's `build.gradle` file:
```kotlin title="build.gradle[.kts]"
dependencies {
- testImplementation("com.apollographql.apollo3:apollo-mockserver:4.0.0-beta.5")
+ testImplementation("com.apollographql.mockserver:apollo-mockserver:0.0.1")
}
```
diff --git a/docs/source/testing/overview.mdx b/docs/source/testing/overview.mdx
index d2337fc3be0..3d0c9f8f59c 100644
--- a/docs/source/testing/overview.mdx
+++ b/docs/source/testing/overview.mdx
@@ -6,10 +6,8 @@ description: Overview
Apollo Kotlin provides the following tools to help with testing your code:
- [`MockServer`](./mocking-http-responses) (experimental): an HTTP server that you can use to mock any responses
-- [`TestNetworkTransport`](./mocking-graphql-responses) (experimental): enables you to specify the GraphQL responses returned
- by `ApolloClient`
+- [`TestNetworkTransport`](./mocking-graphql-responses) (experimental): lets you specify the GraphQL responses returned by `ApolloClient`
- [Test builders](./test-builders) (experimental): help instantiate your model classes by providing a DSL
-- An [`IdlingResource`](./ui-tests) that you can use in your Espresso UI Tests
`MockServer` creates a full HTTP server. It requires minimal changes to your production code (you only need to change `serverUrl`), which means you can use the same `ApolloClient` for tests and production. `MockServer` is also useful for testing specific server behaviors, such as error cases, HTTP headers, and timeouts.
diff --git a/docs/source/testing/ui-tests.mdx b/docs/source/testing/ui-tests.mdx
deleted file mode 100644
index 024575848f0..00000000000
--- a/docs/source/testing/ui-tests.mdx
+++ /dev/null
@@ -1,29 +0,0 @@
----
-title: UI Tests
----
-
-Apollo Kotlin provides a built-in [`IdlingResource`](https://developer.android.com/reference/androidx/test/espresso/IdlingResource) to help you write UI tests with Espresso. The `ApolloIdlingResource` makes sure that your tests wait for your GraphQL queries to terminate before proceeding.
-
-Add the `apollo-idling-resource` dependency:
-
-```kotlin title="build.gradle[.kts]"
-implementation("com.apollographql.apollo3:apollo-idling-resource:4.0.0-beta.5")
-```
-
-> If you have multiple `ApolloClient`s, you need to create and register a different `ApolloIdlingResource` with a different name for each. Registering multiple `IdlingResource`s with the same name will cause your test suite to crash.
-
-```kotlin
-// Create your IdlingResource
-val idlingResource = ApolloIdlingResource("apolloIdlingResource")
-
-// Register the idlingResource before running your tests (once per client).
-IdlingRegistry.getInstance().register(idlingResource)
-
-// Intruct your ApolloClient to update the IdlingResource
-val apolloClient = ApolloClient.Builder()
- .serverUrl("https://example.com/graphql")
- .idlingResource(idlingResource)
- .build()
-```
-
-In the example above, all operations executed by `apolloClient` (except subscriptions, which might run for a long time) will update the `IdlingResource` so that no automatic actions take place while your app is waiting for data.
diff --git a/docs/source/tutorial/01-configure-project.mdx b/docs/source/tutorial/01-configure-project.mdx
index 9b0cbc398d1..5d2473c51c0 100644
--- a/docs/source/tutorial/01-configure-project.mdx
+++ b/docs/source/tutorial/01-configure-project.mdx
@@ -35,7 +35,7 @@ Now let's add Apollo Kotlin to the project.
You can find the latest version of Apollo Kotlin from the [GitHub releases page](https://github.com/apollographql/apollo-kotlin/releases). It is also displayed at the top of the [apollo-kotlin repo](https://github.com/apollographql/apollo-kotlin/).
-This tutorial uses `4.0.0-beta.5` because it is the latest version at the time of writing. Feel free to use a more recent version if one is available.
+This tutorial uses `4.0.0-beta.7` because it is the latest version at the time of writing. Feel free to use a more recent version if one is available.
## Apply the plugin
@@ -45,7 +45,7 @@ Apply the Apollo plugin in `app/build.gradle.kts`. There are two `build.gradle.k
plugins {
id("com.android.application")
// ...
- id("com.apollographql.apollo3") version "4.0.0-beta.5"
+ id("com.apollographql.apollo3") version "4.0.0-beta.7"
}
```
@@ -72,7 +72,7 @@ Now add `apollo-runtime` to the list of dependencies. This is the code that exec
```kotlin title="app/build.gradle.kts"
dependencies {
// ...
- implementation("com.apollographql.apollo3:apollo-runtime:4.0.0-beta.5")
+ implementation("com.apollographql.apollo3:apollo-runtime:4.0.0-beta.7")
}
```
diff --git a/gradle.properties b/gradle.properties
index ff7008cbf66..a40ca7222a2 100644
--- a/gradle.properties
+++ b/gradle.properties
@@ -1,6 +1,6 @@
# Publishing defaults, could ultimately be moved to build scripts
GROUP=com.apollographql.apollo3
-VERSION_NAME=4.0.0-beta.6-SNAPSHOT
+VERSION_NAME=4.0.0-beta.8-SNAPSHOT
POM_URL=https://github.com/apollographql/apollo-kotlin/
POM_SCM_URL=https://github.com/apollographql/apollo-kotlin/
diff --git a/gradle/ge.gradle b/gradle/ge.gradle
index febd0002e1a..6f5bba3f928 100644
--- a/gradle/ge.gradle
+++ b/gradle/ge.gradle
@@ -25,7 +25,7 @@ buildCache {
remote(develocity.buildCache) {
enabled = true
// Check access key presence to avoid build cache errors on PR builds when access key is not present
- def accessKey = System.getenv("GRADLE_ENTERPRISE_ACCESS_KEY")
+ def accessKey = System.getenv("DEVELOCITY_ACCESS_KEY")
push = isCI && accessKey
}
}
\ No newline at end of file
diff --git a/gradle/libraries.toml b/gradle/libraries.toml
index 39b1f0d22ed..ac03ab6601e 100644
--- a/gradle/libraries.toml
+++ b/gradle/libraries.toml
@@ -14,25 +14,27 @@ android-sdkversion-benchmark-min = "24"
android-sdkversion-target = "30"
androidx-sqlite = "2.3.1"
# This is used by the gradle integration tests to get the artifacts locally
-apollo = "4.0.0-beta.6-SNAPSHOT"
+apollo = "4.0.0-beta.8-SNAPSHOT"
+apollo-execution = "0.0.1"
+apollo-normalizedcache-incubating-snapshot = "0.0.2-SNAPSHOT"
# Used by the apollo-tooling project which uses a published version of Apollo
-apollo-published = "4.0.0-beta.3"
-atomicfu = "0.23.1"
+apollo-published = "4.0.0-beta.6"
+atomicfu = "0.24.0"
cache = "2.0.2"
compose = "1.5.1"
guava = "31.1-jre"
javaPoet = "1.13.0"
jetbrains-annotations = "24.0.1"
junit = "4.13.2"
-kotlin-plugin-min = "1.8.0"
-kotlin-plugin = "2.0.0-RC1"
-kotlin-plugin-max = "2.0.0-RC1"
-kotlin-stdlib = "2.0.0-RC1"
+kotlin-plugin-min = "1.9.0"
+kotlin-plugin = "2.1.0-dev-436"
+kotlin-plugin-max = "2.1.0-dev-436"
+kotlin-stdlib = "2.1.0-dev-436"
kotlinx-coroutines = "1.8.0"
kotlinx-datetime = "0.5.0"
kotlinx-serialization-runtime = "1.6.2"
-ksp = "2.0.0-RC1-1.0.20"
-ktor = "2.3.7"
+ksp = "2.0.0-1.0.23-SNAPSHOT"
+ktor = "2.3.11"
moshix = "0.14.1"
node-fetch = "2.6.7"
node-ws = "8.14.2"
@@ -56,7 +58,6 @@ androidx-core = "androidx.core:core-ktx:1.12.0"
androidx-espresso-idlingresource = { group = "androidx.test.espresso", name = "espresso-idling-resource", version = "3.5.1" }
androidx-lint-rules = "androidx.lint:lint-gradle:1.0.0-alpha01"
androidx-lint-gradle-plugin = { module = "com.android.lint:com.android.lint.gradle.plugin", version.ref = "android-plugin" }
-androidx-multidex = "androidx.multidex:multidex:2.0.1"
androidx-paging-compose = "androidx.paging:paging-compose:1.0.0-alpha18"
androidx-profileinstaller = "androidx.profileinstaller:profileinstaller:1.3.1"
androidx-sqlite = { group = "androidx.sqlite", name = "sqlite", version.ref = "androidx-sqlite" }
@@ -67,26 +68,24 @@ apollo-api = { group = "com.apollographql.apollo3", name = "apollo-api", version
apollo-api-java = { group = "com.apollographql.apollo3", name = "apollo-api-java", version.ref = "apollo" }
apollo-httpCache = { group = "com.apollographql.apollo3", name = "apollo-http-cache", version.ref = "apollo" }
apollo-idlingresource = { group = "com.apollographql.apollo3", name = "apollo-idling-resource", version.ref = "apollo" }
-apollo-mockserver = { group = "com.apollographql.apollo3", name = "apollo-mockserver", version.ref = "apollo" }
-# Used by the apollo-tooling project which uses a published version of Apollo
-apollo-mockserver-published = { group = "com.apollographql.apollo3", name = "apollo-mockserver", version.ref = "apollo-published" }
+apollo-mockserver = { group = "com.apollographql.mockserver", name = "apollo-mockserver", version = "0.0.3" }
apollo-mpputils = { group = "com.apollographql.apollo3", name = "apollo-mpp-utils", version.ref = "apollo" }
apollo-normalizedcache = { group = "com.apollographql.apollo3", name = "apollo-normalized-cache", version.ref = "apollo" }
-apollo-normalizedcache-incubating = { group = "com.apollographql.apollo3", name = "apollo-normalized-cache-incubating", version.ref = "apollo" }
+apollo-normalizedcache-incubating-snapshot = { group = "com.apollographql.cache", name = "normalized-cache-incubating", version.ref = "apollo-normalizedcache-incubating-snapshot" }
apollo-normalizedcache-sqlite = { group = "com.apollographql.apollo3", name = "apollo-normalized-cache-sqlite", version.ref = "apollo" }
-apollo-normalizedcache-sqlite-incubating = { group = "com.apollographql.apollo3", name = "apollo-normalized-cache-sqlite-incubating", version.ref = "apollo" }
-apollo-rx2-support-java = { group = "com.apollographql.apollo3", name = "apollo-rx2-support-java", version.ref = "apollo" }
+apollo-normalizedcache-sqlite-incubating-snapshot = { group = "com.apollographql.cache", name = "normalized-cache-sqlite-incubating", version.ref = "apollo-normalizedcache-incubating-snapshot" }
apollo-plugin = { group = "com.apollographql.apollo3", name = "apollo-gradle-plugin", version.ref = "apollo" }
apollo-runtime = { group = "com.apollographql.apollo3", name = "apollo-runtime", version.ref = "apollo" }
apollo-compiler = { group = "com.apollographql.apollo3", name = "apollo-compiler", version.ref = "apollo" }
apollo-ast = { group = "com.apollographql.apollo3", name = "apollo-ast", version.ref = "apollo" }
-apollo-execution = { group = "com.apollographql.apollo3", name = "apollo-execution-incubating", version.ref = "apollo" }
+apollo-execution = { group = "com.apollographql.execution", name = "runtime", version.ref = "apollo-execution" }
+apollo-execution-ktor = { group = "com.apollographql.execution", name = "runtime-ktor", version.ref = "apollo-execution" }
+apollo-execution-processor = { group = "com.apollographql.execution", name = "processor", version.ref = "apollo-execution" }
+apollo-execution-gradle-plugin = { group = "com.apollographql.execution", name = "gradle-plugin", version.ref = "apollo-execution" }
# Used by the apollo-tooling project which uses a published version of Apollo
apollo-runtime-published = { group = "com.apollographql.apollo3", name = "apollo-runtime", version.ref = "apollo-published" }
apollo-annotations = { group = "com.apollographql.apollo3", name = "apollo-annotations", version.ref = "apollo" }
-apollo-runtime-java = { group = "com.apollographql.apollo3", name = "apollo-runtime-java", version.ref = "apollo" }
apollo-engine-ktor = { group = "com.apollographql.apollo3", name = "apollo-engine-ktor", version.ref = "apollo" }
-apollo-rx3-java = { group = "com.apollographql.apollo3", name = "apollo-rx3-support-java", version.ref = "apollo" }
apollo-testingsupport = { group = "com.apollographql.apollo3", name = "apollo-testing-support", version.ref = "apollo" }
# Used by the apollo-tooling project which uses a published version of Apollo
apollo-testingsupport-published = { group = "com.apollographql.apollo3", name = "apollo-testing-support", version.ref = "apollo-published" }
@@ -100,7 +99,7 @@ clikt = { group = "com.github.ajalt.clikt", name = "clikt", version = "3.5.2" }
compose-runtime = { group = "androidx.compose.runtime", name = "runtime", version.ref = "compose" }
compose-ui = { group = "androidx.compose.ui", name = "ui", version.ref = "compose" }
dokkatoo = "dev.adamko.dokkatoo:dokkatoo-plugin:2.1.0"
-dgp = "com.gradle:develocity-gradle-plugin:3.17.2" # // sync with settings.gradle.kts
+dgp = "com.gradle:develocity-gradle-plugin:3.17.5" # // sync with settings.gradle.kts
# Not updating because it fails in apollo-compiler Java tests with
# annotation @org.jetbrains.annotations.Nullable not applicable in this type context
google-testing-compile = { group = "com.google.testing.compile", name = "compile-testing", version = "0.19" }
@@ -156,7 +155,7 @@ kotlin-node = "org.jetbrains.kotlin-wrappers:kotlin-node:18.16.12-pre.634"
kotlinx-serialization-plugin = { group = "org.jetbrains.kotlin", name = "kotlin-serialization", version.ref = "kotlin-plugin" }
kotlinx-serialization-core = { group = "org.jetbrains.kotlinx", name = "kotlinx-serialization-core", version.ref = "kotlinx-serialization-runtime" }
kotlinx-serialization-json = { group = "org.jetbrains.kotlinx", name = "kotlinx-serialization-json", version.ref = "kotlinx-serialization-runtime" }
-kotlinx-binarycompatibilityvalidator = { group = "org.jetbrains.kotlinx", name = "binary-compatibility-validator", version = "0.13.2" }
+kotlinx-binarycompatibilityvalidator = { group = "org.jetbrains.kotlinx", name = "binary-compatibility-validator", version = "0.15.0-Beta.2" }
ksp = { module = "com.google.devtools.ksp:symbol-processing-gradle-plugin", version.ref = "ksp" }
ksp-api = { module = "com.google.devtools.ksp:symbol-processing-api", version.ref = "ksp" }
ktor-client-core = { group = "io.ktor", name= "ktor-client-core", version.ref = "ktor" }
@@ -198,7 +197,8 @@ truth = { group = "com.google.truth", name = "truth", version.ref = "truth" }
turbine = { group = "app.cash.turbine", name = "turbine", version = "1.1.0" }
uuid = { group = "com.benasher44", name = "uuid", version = "0.8.2" }
vespene = { group = "net.mbonnin.vespene", name = "vespene-lib", version = "0.5" }
-slf4j = "org.slf4j:slf4j-simple:2.0.9"
+slf4j-simple = "org.slf4j:slf4j-simple:2.0.13"
+slf4j-nop = "org.slf4j:slf4j-nop:2.0.13"
[plugins]
apollo = { id = "com.apollographql.apollo3", version.ref = "apollo" }
@@ -207,6 +207,7 @@ kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin-plugin" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin-plugin" }
kotlin-android-min = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin-plugin-min" }
kotlin-android-max = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin-plugin-max" }
+kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin-plugin" }
kotlin-jvm-min = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin-plugin-min" }
kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin-plugin" }
android-application = { id = "com.android.application", version.ref = "android-plugin" }
diff --git a/gradle/repositories.gradle.kts b/gradle/repositories.gradle.kts
index 184ded3c238..58a467fb30d 100644
--- a/gradle/repositories.gradle.kts
+++ b/gradle/repositories.gradle.kts
@@ -1,7 +1,9 @@
listOf(pluginManagement.repositories, dependencyResolutionManagement.repositories).forEach {
it.apply {
// Uncomment this one to use the Kotlin "dev" repository
- // maven { url = uri("https://maven.pkg.jetbrains.space/kotlin/p/kotlin/dev/") }
+ maven { url = uri("https://maven.pkg.jetbrains.space/kotlin/p/kotlin/dev/") }
+maven { url = uri("https://oss.sonatype.org/content/repositories/snapshots/") }
+
mavenCentral()
exclusiveContent {
diff --git a/gradle/wrapper/gradle-wrapper.properties b/gradle/wrapper/gradle-wrapper.properties
index 38de112f6b6..a4413138c96 100644
--- a/gradle/wrapper/gradle-wrapper.properties
+++ b/gradle/wrapper/gradle-wrapper.properties
@@ -1,6 +1,6 @@
distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-rc-1-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.8-bin.zip
networkTimeout=10000
validateDistributionUrl=true
zipStoreBase=GRADLE_USER_HOME
diff --git a/gradlew b/gradlew
index 1aa94a42690..b740cf13397 100755
--- a/gradlew
+++ b/gradlew
@@ -55,7 +55,7 @@
# Darwin, MinGW, and NonStop.
#
# (3) This script is generated from the Groovy template
-# https://github.com/gradle/gradle/blob/HEAD/subprojects/plugins/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
+# https://github.com/gradle/gradle/blob/HEAD/platforms/jvm/plugins-application/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
# within the Gradle project.
#
# You can find Gradle at https://github.com/gradle/gradle/.
diff --git a/intellij-plugin/README.md b/intellij-plugin/README.md
index 1d74e785170..1cc4ae2db50 100644
--- a/intellij-plugin/README.md
+++ b/intellij-plugin/README.md
@@ -22,7 +22,7 @@ This plugin for Android Studio and IntelliJ helps you work with the
## Compatibility
-- Most features are intended to work with Apollo Kotlin 4.x which is currently under development
+- Most features are intended to work with Apollo Kotlin 4.x
- Automatic code generation works with Apollo Kotlin 3.x and above
diff --git a/intellij-plugin/build.gradle.kts b/intellij-plugin/build.gradle.kts
index a54b851c4c8..a1eee5bebd1 100644
--- a/intellij-plugin/build.gradle.kts
+++ b/intellij-plugin/build.gradle.kts
@@ -19,7 +19,8 @@ commonSetup()
// XXX: this should use the settings repositories instead
repositories {
// Uncomment this one to use the Kotlin "dev" repository
- // maven { url = uri("https://maven.pkg.jetbrains.space/kotlin/p/kotlin/dev/") }
+ maven { url = uri("https://maven.pkg.jetbrains.space/kotlin/p/kotlin/dev/") }
+maven { url = uri("https://oss.sonatype.org/content/repositories/snapshots/") }
mavenCentral()
}
@@ -177,7 +178,7 @@ dependencies {
implementation(project(":apollo-normalized-cache-sqlite"))
implementation(libs.sqlite.jdbc)
implementation(libs.apollo.runtime.published)
- runtimeOnly(libs.slf4j)
+ runtimeOnly(libs.slf4j.simple)
testImplementation(libs.google.testparameterinjector)
}
@@ -186,10 +187,10 @@ fun isSnapshotBuild() = System.getenv("IJ_PLUGIN_SNAPSHOT").toBoolean()
apollo {
service("apolloDebug") {
packageName.set("com.apollographql.apollo3.debug")
- schemaFiles.from(file("../libraries/apollo-debug-server/src/androidMain/resources/schema.graphqls"))
+ schemaFiles.from(file("../libraries/apollo-debug-server/graphql/schema.graphqls"))
introspection {
endpointUrl.set("http://localhost:12200/")
- schemaFile.set(file("../libraries/apollo-debug-server/src/androidMain/resources/schema.graphqls"))
+ schemaFile.set(file("../libraries/apollo-debug-server/graphql/schema.graphqls"))
}
}
}
diff --git a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/gradle/ApolloKotlinService.kt b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/gradle/ApolloKotlinService.kt
index 8a4dd3ead8d..f561731a595 100644
--- a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/gradle/ApolloKotlinService.kt
+++ b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/gradle/ApolloKotlinService.kt
@@ -1,25 +1,56 @@
package com.apollographql.ijplugin.gradle
import com.intellij.util.messages.Topic
+import com.intellij.util.xmlb.annotations.Attribute
+import com.intellij.util.xmlb.annotations.Transient
+import com.intellij.util.xmlb.annotations.XCollection
interface ApolloKotlinServiceListener {
companion object {
@Topic.ProjectLevel
- val TOPIC: Topic = Topic.create("ApolloKotlinServices are available", ApolloKotlinServiceListener::class.java)
+ val TOPIC: Topic =
+ Topic.create("ApolloKotlinServices are available", ApolloKotlinServiceListener::class.java)
}
fun apolloKotlinServicesAvailable()
}
+/**
+ * Represents an Apollo Kotlin service as configured in the Apollo Gradle plugin configuration.
+ *
+ * These are built from the [com.apollographql.apollo3.gradle.api.ApolloGradleToolingModel] and are used to configure the GraphQL plugin,
+ * and are cached into the project settings.
+ *
+ * @see com.apollographql.ijplugin.gradle.GradleToolingModelService
+ * @see com.apollographql.ijplugin.graphql.ApolloGraphQLConfigContributor
+ * @see com.apollographql.ijplugin.settings.ProjectSettingsService
+ */
data class ApolloKotlinService(
- val gradleProjectPath: String,
- val serviceName: String,
- val schemaPaths: List,
- val operationPaths: List,
- val endpointUrl: String?,
- val endpointHeaders: Map?,
+ @Attribute
+ val gradleProjectPath: String = "",
+
+ @Attribute
+ val serviceName: String = "",
+
+ @XCollection
+ val schemaPaths: List = emptyList(),
+
+ @XCollection
+ val operationPaths: List = emptyList(),
+
+ @Attribute
+ val endpointUrl: String? = null,
+
+ @XCollection
+ val endpointHeaders: Map? = null,
) {
- data class Id(val gradleProjectPath: String, val serviceName: String) {
+ data class Id(
+ @Attribute
+ val gradleProjectPath: String = "",
+
+ @Attribute
+ val serviceName: String = "",
+ ) {
override fun toString(): String {
val formattedPath = gradleProjectPath.split(":").filterNot { it.isEmpty() }.joinToString("-")
return "$formattedPath/$serviceName"
@@ -34,5 +65,8 @@ data class ApolloKotlinService(
}
}
- val id = Id(gradleProjectPath, serviceName)
+ val id
+ @Transient
+ get() = Id(gradleProjectPath, serviceName)
+
}
diff --git a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/gradle/GradleToolingModelService.kt b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/gradle/GradleToolingModelService.kt
index e418f0eedc4..fbec3e8b7ad 100644
--- a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/gradle/GradleToolingModelService.kt
+++ b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/gradle/GradleToolingModelService.kt
@@ -44,7 +44,8 @@ class GradleToolingModelService(
private var fetchToolingModelsTask: FetchToolingModelsTask? = null
- var apolloKotlinServices: List = emptyList()
+ var apolloKotlinServices: List = project.projectSettingsState.apolloKotlinServices
+ private set
init {
logd("project=${project.name}")
@@ -52,6 +53,11 @@ class GradleToolingModelService(
startOrStopObserveGradleHasSynced()
startOrAbortFetchToolingModels()
startObserveSettings()
+
+ if (apolloKotlinServices.isNotEmpty()) {
+ // Services are available, notify interested parties
+ project.messageBus.syncPublisher(ApolloKotlinServiceListener.TOPIC).apolloKotlinServicesAvailable()
+ }
}
private fun startObserveApolloProject() {
@@ -261,10 +267,12 @@ class GradleToolingModelService(
apolloKotlinServices += getApolloKotlinService(toolingModel.projectPathCompat, serviceInfo.name)
}
}
- this.apolloKotlinServices = apolloKotlinServices
logd("apolloKotlinServices=$apolloKotlinServices")
+ this.apolloKotlinServices = apolloKotlinServices
+ // Cache the ApolloKotlinServices into the project settings
+ project.projectSettingsState.apolloKotlinServices = apolloKotlinServices
- // Project files are available, notify interested parties
+ // Services are available, notify interested parties
project.messageBus.syncPublisher(ApolloKotlinServiceListener.TOPIC).apolloKotlinServicesAvailable()
}
diff --git a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/graphql/ApolloClientDirectiveStripper.kt b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/graphql/ApolloClientDirectiveStripper.kt
index 2650daa7bf6..7242ffdba01 100644
--- a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/graphql/ApolloClientDirectiveStripper.kt
+++ b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/graphql/ApolloClientDirectiveStripper.kt
@@ -10,8 +10,8 @@ import com.apollographql.apollo3.ast.parseAsGQLDocument
import com.apollographql.apollo3.ast.toUtf8
import com.apollographql.apollo3.ast.transform
import com.apollographql.apollo3.ast.validateAsSchemaAndAddApolloDefinition
-import com.apollographql.ijplugin.inspection.schemaFiles
import com.apollographql.ijplugin.util.logw
+import com.apollographql.ijplugin.util.schemaFiles
import com.intellij.lang.jsgraphql.psi.GraphQLFile
import com.intellij.openapi.editor.Editor
import com.intellij.psi.PsiDocumentManager
diff --git a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/graphql/ApolloGraphQLConfigContributor.kt b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/graphql/ApolloGraphQLConfigContributor.kt
index 26baa4cf15b..91069cafae1 100644
--- a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/graphql/ApolloGraphQLConfigContributor.kt
+++ b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/graphql/ApolloGraphQLConfigContributor.kt
@@ -36,7 +36,7 @@ class ApolloGraphQLConfigContributor : GraphQLConfigContributor {
private fun ApolloKotlinService.toGraphQLRawProjectConfig() = GraphQLRawProjectConfig(
schema = schemaPaths.map { GraphQLRawSchemaPointer(it) },
- include = operationPaths.map { "$it/*.graphql" },
+ include = operationPaths.map { "$it/**/*.graphql" },
extensions = endpointUrl?.let {
mapOf(
GraphQLConfigKeys.EXTENSION_ENDPOINTS to mapOf(
diff --git a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/graphql/BuiltInRedefinitionErrorFilter.kt b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/graphql/BuiltInRedefinitionErrorFilter.kt
deleted file mode 100644
index b424ac1ca39..00000000000
--- a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/graphql/BuiltInRedefinitionErrorFilter.kt
+++ /dev/null
@@ -1,50 +0,0 @@
-package com.apollographql.ijplugin.graphql
-
-import com.intellij.lang.jsgraphql.ide.validation.GraphQLErrorFilter
-import com.intellij.lang.jsgraphql.types.GraphQLError
-import com.intellij.lang.jsgraphql.types.language.DirectiveDefinition
-import com.intellij.lang.jsgraphql.types.language.EnumTypeDefinition
-import com.intellij.lang.jsgraphql.types.language.ObjectTypeDefinition
-import com.intellij.lang.jsgraphql.types.language.ScalarTypeDefinition
-import com.intellij.lang.jsgraphql.types.schema.idl.errors.DirectiveRedefinitionError
-import com.intellij.lang.jsgraphql.types.schema.idl.errors.TypeRedefinitionError
-import com.intellij.openapi.project.Project
-import com.intellij.psi.PsiElement
-
-/**
- * Suppress redefinition errors for built-in GraphQL types/directives.
- *
- * TODO: remove this once https://github.com/JetBrains/js-graphql-intellij-plugin/issues/665 is fixed
- */
-class BuiltInRedefinitionErrorFilter : GraphQLErrorFilter {
- private val builtInScalarTypes = listOf("Int", "Float", "String", "Boolean", "ID")
- private val builtInDirectives = listOf("skip", "include", "deprecated", "defer", "specifiedBy")
-
- override fun isGraphQLErrorSuppressed(project: Project, error: GraphQLError, element: PsiElement?): Boolean {
- return when (error) {
- is TypeRedefinitionError -> {
- when (val node = error.node) {
- is ScalarTypeDefinition -> {
- node.name in builtInScalarTypes
- }
-
- is ObjectTypeDefinition -> {
- node.name.startsWith("__")
- }
-
- is EnumTypeDefinition -> {
- node.name.startsWith("__")
- }
-
- else -> false
- }
- }
-
- is DirectiveRedefinitionError -> {
- (error.node as DirectiveDefinition).name in builtInDirectives
- }
-
- else -> false
- }
- }
-}
diff --git a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/inspection/ApolloGraphQLConfigFilePresentInspection.kt b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/inspection/ApolloGraphQLConfigFilePresentInspection.kt
new file mode 100644
index 00000000000..dbe1e4cb175
--- /dev/null
+++ b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/inspection/ApolloGraphQLConfigFilePresentInspection.kt
@@ -0,0 +1,84 @@
+package com.apollographql.ijplugin.inspection
+
+import com.apollographql.ijplugin.ApolloBundle
+import com.apollographql.ijplugin.project.apolloProjectService
+import com.apollographql.ijplugin.settings.projectSettingsState
+import com.apollographql.ijplugin.telemetry.TelemetryEvent
+import com.apollographql.ijplugin.telemetry.telemetryService
+import com.intellij.codeInsight.intention.preview.IntentionPreviewInfo
+import com.intellij.codeInsight.intention.preview.IntentionPreviewUtils
+import com.intellij.codeInspection.LocalInspectionTool
+import com.intellij.codeInspection.LocalQuickFix
+import com.intellij.codeInspection.ProblemDescriptor
+import com.intellij.codeInspection.ProblemsHolder
+import com.intellij.lang.annotation.AnnotationHolder
+import com.intellij.lang.annotation.Annotator
+import com.intellij.lang.annotation.HighlightSeverity
+import com.intellij.openapi.project.Project
+import com.intellij.openapi.util.Condition
+import com.intellij.openapi.vfs.VirtualFile
+import com.intellij.psi.PsiElement
+import com.intellij.psi.PsiElementVisitor
+
+private val graphQLConfigFileNames = setOf(
+ "graphql.config.json",
+ "graphql.config.js",
+ "graphql.config.cjs",
+ "graphql.config.ts",
+ "graphql.config.yaml",
+ "graphql.config.yml",
+ ".graphqlrc",
+ ".graphqlrc.json",
+ ".graphqlrc.yaml",
+ ".graphqlrc.yml",
+ ".graphqlrc.js",
+ ".graphqlrc.ts"
+)
+
+class ApolloGraphQLConfigFilePresentInspection : LocalInspectionTool() {
+ override fun buildVisitor(holder: ProblemsHolder, isOnTheFly: Boolean): PsiElementVisitor {
+ return object : PsiElementVisitor() {
+ override fun visitElement(element: PsiElement) {
+ if (!element.project.apolloProjectService.apolloVersion.isAtLeastV4 || !element.project.projectSettingsState.contributeConfigurationToGraphqlPlugin) return
+ if (element.containingFile.name in graphQLConfigFileNames && element.containingFile == element) {
+ holder.registerProblem(element, ApolloBundle.message("inspection.graphQLConfigFilePresent.reportText"), ApolloGraphQLConfigFilePresentQuickFix(element.containingFile.name))
+ }
+ }
+ }
+ }
+}
+
+private class ApolloGraphQLConfigFilePresentQuickFix(private val fileName: String) : LocalQuickFix {
+ override fun getName(): String {
+ return ApolloBundle.message("inspection.graphQLConfigFilePresent.quickFix", fileName)
+ }
+
+ override fun getFamilyName() = name
+
+ override fun availableInBatchMode() = false
+
+ override fun generatePreview(project: Project, previewDescriptor: ProblemDescriptor): IntentionPreviewInfo = IntentionPreviewInfo.EMPTY
+
+ override fun applyFix(project: Project, descriptor: ProblemDescriptor) {
+ if (!IntentionPreviewUtils.isIntentionPreviewActive()) project.telemetryService.logEvent(TelemetryEvent.ApolloIjGraphQLConfigFilePresentQuickFix())
+ val psiFile = descriptor.psiElement.containingFile
+ psiFile.virtualFile.delete(this)
+ }
+}
+
+class ApolloGraphQLConfigFilePresentAnnotator : Annotator {
+ override fun annotate(element: PsiElement, holder: AnnotationHolder) {
+ if (!element.project.apolloProjectService.apolloVersion.isAtLeastV4 || !element.project.projectSettingsState.contributeConfigurationToGraphqlPlugin) return
+ if (element.containingFile.name in graphQLConfigFileNames && element.containingFile == element) {
+ holder.newAnnotation(HighlightSeverity.WARNING, ApolloBundle.message("inspection.graphQLConfigFilePresent.reportText"))
+ .range(element)
+ .create()
+ }
+ }
+}
+
+class GraphQLConfigFileFilter : Condition {
+ override fun value(virtualFile: VirtualFile): Boolean {
+ return virtualFile.name in graphQLConfigFileNames
+ }
+}
diff --git a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/inspection/ApolloMissingGraphQLDefinitionImportInspection.kt b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/inspection/ApolloMissingGraphQLDefinitionImportInspection.kt
index fd0cf8a96bc..9ccab0f2217 100644
--- a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/inspection/ApolloMissingGraphQLDefinitionImportInspection.kt
+++ b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/inspection/ApolloMissingGraphQLDefinitionImportInspection.kt
@@ -12,9 +12,18 @@ import com.apollographql.ijplugin.gradle.gradleToolingModelService
import com.apollographql.ijplugin.project.apolloProjectService
import com.apollographql.ijplugin.telemetry.TelemetryEvent
import com.apollographql.ijplugin.telemetry.telemetryService
+import com.apollographql.ijplugin.util.KOTLIN_LABS_DEFINITIONS
+import com.apollographql.ijplugin.util.KOTLIN_LABS_URL
+import com.apollographql.ijplugin.util.NULLABILITY_DEFINITIONS
+import com.apollographql.ijplugin.util.NULLABILITY_URL
import com.apollographql.ijplugin.util.cast
-import com.apollographql.ijplugin.util.findChildrenOfType
-import com.apollographql.ijplugin.util.quoted
+import com.apollographql.ijplugin.util.createLinkDirective
+import com.apollographql.ijplugin.util.createLinkDirectiveSchemaExtension
+import com.apollographql.ijplugin.util.directives
+import com.apollographql.ijplugin.util.isImported
+import com.apollographql.ijplugin.util.linkDirectives
+import com.apollographql.ijplugin.util.nameForImport
+import com.apollographql.ijplugin.util.schemaFiles
import com.apollographql.ijplugin.util.unquoted
import com.intellij.codeInsight.intention.preview.IntentionPreviewInfo
import com.intellij.codeInsight.intention.preview.IntentionPreviewUtils
@@ -26,7 +35,6 @@ import com.intellij.codeInspection.ProblemsHolder
import com.intellij.lang.jsgraphql.psi.GraphQLArrayValue
import com.intellij.lang.jsgraphql.psi.GraphQLDirective
import com.intellij.lang.jsgraphql.psi.GraphQLElementFactory
-import com.intellij.lang.jsgraphql.psi.GraphQLSchemaExtension
import com.intellij.lang.jsgraphql.psi.GraphQLVisitor
import com.intellij.openapi.project.Project
import com.intellij.psi.PsiElementVisitor
@@ -139,40 +147,3 @@ private class ImportDefinitionQuickFix(
}
}
}
-
-private fun createLinkDirectiveSchemaExtension(
- project: Project,
- importedNames: Set,
- definitions: List,
- definitionsUrl: String,
-): GraphQLSchemaExtension {
- // If any of the imported name is a directive, add its argument types to the import list
- val knownDefinitionNames = definitions.filterIsInstance().map { it.name }
- val additionalNames = importedNames.flatMap { importedName ->
- definitions.directives().firstOrNull { "@${it.name}" == importedName }
- ?.arguments
- ?.map { it.type.rawType().name }
- ?.filter { it in knownDefinitionNames }.orEmpty()
- }.toSet()
-
- return GraphQLElementFactory.createFile(
- project,
- """
- extend schema
- @link(
- url: "$definitionsUrl",
- import: [${(importedNames + additionalNames).joinToString { it.quoted() }}]
- )
- """.trimIndent()
- )
- .findChildrenOfType().single()
-}
-
-private fun createLinkDirective(
- project: Project,
- importedNames: Set,
- definitions: List,
- definitionsUrl: String,
-): GraphQLDirective {
- return createLinkDirectiveSchemaExtension(project, importedNames, definitions, definitionsUrl).directives.single()
-}
diff --git a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/inspection/ApolloUnusedFieldInspection.kt b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/inspection/ApolloUnusedFieldInspection.kt
index e75f481a492..d8d32b1cbd8 100644
--- a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/inspection/ApolloUnusedFieldInspection.kt
+++ b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/inspection/ApolloUnusedFieldInspection.kt
@@ -9,6 +9,7 @@ import com.apollographql.ijplugin.project.apolloProjectService
import com.apollographql.ijplugin.telemetry.TelemetryEvent
import com.apollographql.ijplugin.telemetry.telemetryService
import com.apollographql.ijplugin.util.isProcessCanceled
+import com.apollographql.ijplugin.util.matchingFieldCoordinates
import com.intellij.codeInsight.intention.preview.IntentionPreviewInfo
import com.intellij.codeInsight.intention.preview.IntentionPreviewUtils
import com.intellij.codeInspection.LocalInspectionTool
diff --git a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/inspection/GraphQLUnresolvedReferenceInspectionSuppressor.kt b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/inspection/GraphQLUnresolvedReferenceInspectionSuppressor.kt
index 1d86bc223d7..64442722c31 100644
--- a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/inspection/GraphQLUnresolvedReferenceInspectionSuppressor.kt
+++ b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/inspection/GraphQLUnresolvedReferenceInspectionSuppressor.kt
@@ -2,6 +2,12 @@ package com.apollographql.ijplugin.inspection
import com.apollographql.apollo3.ast.GQLDirectiveDefinition
import com.apollographql.apollo3.ast.linkDefinitions
+import com.apollographql.ijplugin.util.KOTLIN_LABS_DEFINITIONS
+import com.apollographql.ijplugin.util.NULLABILITY_DEFINITIONS
+import com.apollographql.ijplugin.util.NULLABILITY_URL
+import com.apollographql.ijplugin.util.directives
+import com.apollographql.ijplugin.util.isImported
+import com.apollographql.ijplugin.util.nameWithoutPrefix
import com.intellij.codeInspection.InspectionSuppressor
import com.intellij.codeInspection.SuppressQuickFix
import com.intellij.lang.jsgraphql.psi.GraphQLArgument
@@ -10,13 +16,14 @@ import com.intellij.lang.jsgraphql.psi.GraphQLDirectivesAware
import com.intellij.psi.PsiElement
private val KNOWN_DIRECTIVES: List by lazy {
- linkDefinitions().directives() + NULLABILITY_DEFINITIONS.directives()
+ linkDefinitions().directives() + NULLABILITY_DEFINITIONS.directives() + KOTLIN_LABS_DEFINITIONS.directives()
}
/**
* Do not highlight certain known directives as unresolved references.
*
- * TODO: remove this once https://github.com/JetBrains/js-graphql-intellij-plugin/pull/698 is merged.
+ * Note: we'll need this workaround until there is a way for a plugin to provide their own known definitions to the GraphQL plugin.
+ * See https://github.com/JetBrains/js-graphql-intellij-plugin/issues/697.
*/
class GraphQLUnresolvedReferenceInspectionSuppressor : InspectionSuppressor {
override fun isSuppressedFor(element: PsiElement, toolId: String): Boolean {
@@ -26,8 +33,9 @@ class GraphQLUnresolvedReferenceInspectionSuppressor : InspectionSuppressor {
"GraphQLMissingType" -> element is GraphQLDirectivesAware && element.directives.all { it.isKnownDirective() }
- // We need to suppress this one too because the plugin doesn't know that @link is repeatable
- "GraphQLDuplicateDirective" -> element is GraphQLDirective && element.name == "link"
+ // We need to suppress this one too because the plugin doesn't know that certain directives (e.g. @link) are repeatable
+ "GraphQLDuplicateDirective" -> element is GraphQLDirective &&
+ KNOWN_DIRECTIVES.any { it.name == element.name && it.repeatable }
else -> false
}
@@ -43,5 +51,6 @@ private fun PsiElement.isKnownDirective(): Boolean {
private fun PsiElement.isKnownDirectiveArgument(): Boolean {
return this is GraphQLArgument &&
parent?.parent?.isKnownDirective() == true &&
- name in KNOWN_DIRECTIVES.firstOrNull { it.name == (parent.parent as GraphQLDirective).nameWithoutPrefix }?.arguments?.map { it.name }.orEmpty()
+ name in KNOWN_DIRECTIVES.firstOrNull { it.name == (parent.parent as GraphQLDirective).nameWithoutPrefix }?.arguments?.map { it.name }
+ .orEmpty()
}
diff --git a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/navigation/LogNavigationPsiElement.kt b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/navigation/LogNavigationPsiElement.kt
index 8c26f9ce6b3..9c50fa63b91 100644
--- a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/navigation/LogNavigationPsiElement.kt
+++ b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/navigation/LogNavigationPsiElement.kt
@@ -7,6 +7,7 @@ import com.intellij.navigation.NavigationItem
import com.intellij.platform.backend.navigation.NavigationRequest
import com.intellij.pom.Navigatable
import com.intellij.psi.PsiElement
+import javax.swing.Icon
private class LogNavigationPsiElement(
private val wrapped: PsiElement,
@@ -24,8 +25,13 @@ private class LogNavigationPsiElement(
return (wrapped as? NavigationItem)?.name
}
- override fun getPresentation(): ItemPresentation? {
- return (wrapped as? NavigationItem)?.presentation
+ override fun getPresentation(): ItemPresentation {
+ return (wrapped as? NavigationItem)?.presentation ?: object : ItemPresentation {
+ // We don't want the presentation to be too wide: fallback to the first line of text, truncated to 80 characters
+ override fun getPresentableText(): String? = wrapped.text.split('\n').firstOrNull()?.take(80)
+
+ override fun getIcon(unused: Boolean): Icon? = null
+ }
}
@Suppress("UnstableApiUsage")
diff --git a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/normalizedcache/NormalizedCache.kt b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/normalizedcache/NormalizedCache.kt
index 6fc331af13c..d441b57ccfe 100644
--- a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/normalizedcache/NormalizedCache.kt
+++ b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/normalizedcache/NormalizedCache.kt
@@ -10,7 +10,7 @@ data class NormalizedCache(
)
data class Field(
- val name: String,
+ val key: String,
val value: FieldValue,
)
diff --git a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/normalizedcache/provider/DatabaseNormalizedCacheProvider.kt b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/normalizedcache/provider/DatabaseNormalizedCacheProvider.kt
index be2fd46bfd8..c7009b3ba8f 100644
--- a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/normalizedcache/provider/DatabaseNormalizedCacheProvider.kt
+++ b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/normalizedcache/provider/DatabaseNormalizedCacheProvider.kt
@@ -39,8 +39,8 @@ class DatabaseNormalizedCacheProvider : NormalizedCacheProvider {
apolloRecords.map { (key, apolloRecord) ->
NormalizedCache.Record(
key = key,
- fields = apolloRecord.map { (fieldName, fieldValue) ->
- Field(fieldName, fieldValue.toFieldValue())
+ fields = apolloRecord.map { (fieldKey, fieldValue) ->
+ Field(fieldKey, fieldValue.toFieldValue())
},
sizeInBytes = apolloRecord.sizeInBytes
)
diff --git a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/normalizedcache/ui/FieldTreeTable.kt b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/normalizedcache/ui/FieldTreeTable.kt
index ef423816bcf..8e6f06559bc 100644
--- a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/normalizedcache/ui/FieldTreeTable.kt
+++ b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/normalizedcache/ui/FieldTreeTable.kt
@@ -40,11 +40,14 @@ class FieldTreeTable(selectRecord: (String) -> Unit) : JBTreeTable(FieldTreeTabl
is NormalizedCache.FieldValue.StringValue -> append("\"${v.value}\"")
is NormalizedCache.FieldValue.NumberValue -> append(v.value.toString())
is NormalizedCache.FieldValue.BooleanValue -> append(v.value.toString())
- is NormalizedCache.FieldValue.ListValue -> append(when (val size = v.value.size) {
- 0 -> ApolloBundle.message("normalizedCacheViewer.fields.list.empty")
- 1 -> ApolloBundle.message("normalizedCacheViewer.fields.list.single")
- else -> ApolloBundle.message("normalizedCacheViewer.fields.list.multiple", size)
- }, SimpleTextAttributes.GRAY_ITALIC_ATTRIBUTES)
+ is NormalizedCache.FieldValue.ListValue -> append(
+ when (val size = v.value.size) {
+ 0 -> ApolloBundle.message("normalizedCacheViewer.fields.list.empty")
+ 1 -> ApolloBundle.message("normalizedCacheViewer.fields.list.single")
+ else -> ApolloBundle.message("normalizedCacheViewer.fields.list.multiple", size)
+ },
+ SimpleTextAttributes.GRAY_ITALIC_ATTRIBUTES
+ )
is NormalizedCache.FieldValue.CompositeValue -> append("{...}", SimpleTextAttributes.GRAY_ITALIC_ATTRIBUTES)
NormalizedCache.FieldValue.Null -> append("null")
diff --git a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/normalizedcache/ui/FieldTreeTableModel.kt b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/normalizedcache/ui/FieldTreeTableModel.kt
index fc2fafbf112..da8c84ac059 100644
--- a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/normalizedcache/ui/FieldTreeTableModel.kt
+++ b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/normalizedcache/ui/FieldTreeTableModel.kt
@@ -14,7 +14,8 @@ class FieldTreeTableModel : ListTreeTableModel(
override fun getColumnClass() = TreeTableModel::class.java
override fun valueOf(item: Unit) = Unit
},
- object : ColumnInfo(ApolloBundle.message("normalizedCacheViewer.fields.column.value")) {
+ object :
+ ColumnInfo(ApolloBundle.message("normalizedCacheViewer.fields.column.value")) {
override fun getColumnClass() = NormalizedCache.Field::class.java
override fun valueOf(item: NormalizedCacheFieldTreeNode) = item.field
},
@@ -42,7 +43,7 @@ class FieldTreeTableModel : ListTreeTableModel(
class NormalizedCacheFieldTreeNode(val field: NormalizedCache.Field) : DefaultMutableTreeNode() {
init {
- userObject = field.name
+ userObject = field.key
}
}
}
diff --git a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/project/ApolloProjectManagerListener.kt b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/project/ApolloProjectManagerListener.kt
index 8631bb6b161..e8081949ac9 100644
--- a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/project/ApolloProjectManagerListener.kt
+++ b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/project/ApolloProjectManagerListener.kt
@@ -22,9 +22,9 @@ internal class ApolloProjectManagerListener : ProjectManagerListener {
DumbService.getInstance(project).runWhenSmart {
logd("apolloVersion=" + project.apolloProjectService.apolloVersion)
project.service()
+ project.service()
project.service()
project.service()
- project.service()
project.service()
project.service()
project.service()
diff --git a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/refactoring/GraphQLDefinitionRenameProcessor.kt b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/refactoring/GraphQLDefinitionRenameProcessor.kt
new file mode 100644
index 00000000000..c2c34befdf4
--- /dev/null
+++ b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/refactoring/GraphQLDefinitionRenameProcessor.kt
@@ -0,0 +1,115 @@
+package com.apollographql.ijplugin.refactoring
+
+import com.apollographql.ijplugin.navigation.compat.KotlinFindUsagesHandlerFactoryCompat
+import com.apollographql.ijplugin.navigation.findKotlinFragmentClassDefinitions
+import com.apollographql.ijplugin.navigation.findKotlinOperationDefinitions
+import com.apollographql.ijplugin.util.isGenerated
+import com.intellij.lang.jsgraphql.psi.GraphQLFragmentDefinition
+import com.intellij.lang.jsgraphql.psi.GraphQLIdentifier
+import com.intellij.lang.jsgraphql.psi.GraphQLTypedOperationDefinition
+import com.intellij.openapi.editor.Editor
+import com.intellij.openapi.project.Project
+import com.intellij.psi.PsiElement
+import com.intellij.psi.PsiReference
+import com.intellij.psi.search.SearchScope
+import com.intellij.refactoring.rename.RenameDialog
+import com.intellij.refactoring.rename.RenamePsiElementProcessor
+import com.intellij.usageView.UsageInfo
+import com.intellij.util.Processor
+
+/**
+ * Allows to rename the corresponding usage in Kotlin code when renaming a GraphQL operation or fragment definition.
+ * The file name is also renamed if it matches the current operation or fragment name (as is customary).
+ */
+class GraphQLDefinitionRenameProcessor : RenamePsiElementProcessor() {
+ private var newName: String = ""
+
+ override fun canProcessElement(element: PsiElement): Boolean {
+ return element is GraphQLIdentifier && (element.parent is GraphQLTypedOperationDefinition || element.parent is GraphQLFragmentDefinition)
+ }
+
+ override fun createRenameDialog(
+ project: Project,
+ element: PsiElement,
+ nameSuggestionContext: PsiElement?,
+ editor: Editor?,
+ ): RenameDialog {
+ if (element.parent !is GraphQLTypedOperationDefinition) {
+ return super.createRenameDialog(project, element, nameSuggestionContext, editor)
+ }
+ return object : RenameDialog(project, element, nameSuggestionContext, editor) {
+ override fun getFullName(): String {
+ val definition = element.parent as GraphQLTypedOperationDefinition
+ val type = definition.operationType.text
+ return "$type '${definition.name}'"
+ }
+ }
+ }
+
+ override fun prepareRenaming(element: PsiElement, newName: String, allRenames: MutableMap) {
+ prepareRenamingFile(element, allRenames, newName)
+ this.newName = newName
+ }
+
+ private fun prepareRenamingFile(
+ element: PsiElement,
+ allRenames: MutableMap,
+ newName: String,
+ ) {
+ val file = element.containingFile ?: return
+ val virtualFile = file.virtualFile ?: return
+ val elementCurrentName = (element as GraphQLIdentifier).referenceName
+ if (virtualFile.nameWithoutExtension == elementCurrentName) {
+ allRenames[file] = newName + "." + virtualFile.extension
+ }
+ }
+
+ override fun findReferences(
+ element: PsiElement,
+ searchScope: SearchScope,
+ searchInCommentsAndStrings: Boolean,
+ ): Collection {
+ val references = mutableListOf()
+ val kotlinDefinitions = when (val parent = element.parent) {
+ is GraphQLTypedOperationDefinition -> {
+ if (!(newName.endsWith("Query") || newName.endsWith("Mutation") || newName.endsWith("Subscription"))) {
+ // When useSemanticNaming is true (the default), renaming e.g. FooQuery to FooQuery2 will generate FooQuery2Query.
+ // For now we'll only support the happy case, and won't try to rename references otherwise.
+ // TODO: We could support this by looking at the value of useSemanticNaming from the Gradle Tooling Model, and implementing
+ // the same naming logic as the Apollo compiler.
+ return super.findReferences(element, searchScope, searchInCommentsAndStrings)
+ }
+
+ findKotlinOperationDefinitions(parent)
+ }
+
+ is GraphQLFragmentDefinition -> {
+ findKotlinFragmentClassDefinitions(parent)
+ }
+
+ else -> emptyList()
+ }.ifEmpty {
+ return super.findReferences(element, searchScope, searchInCommentsAndStrings)
+ }
+
+ val kotlinFindUsagesHandlerFactory = KotlinFindUsagesHandlerFactoryCompat(element.project)
+ val processor = object : Processor {
+ override fun process(t: UsageInfo): Boolean {
+ if (t.virtualFile?.isGenerated(t.project) != true) {
+ t.reference?.let { references.add(it) }
+ }
+ return true
+ }
+ }
+ for (kotlinDefinition in kotlinDefinitions) {
+ if (kotlinFindUsagesHandlerFactory.canFindUsages(kotlinDefinition)) {
+ val kotlinFindUsagesHandler = kotlinFindUsagesHandlerFactory.createFindUsagesHandler(kotlinDefinition, false)
+ ?: break
+ val findUsageOptions = kotlinFindUsagesHandlerFactory.findClassOptions ?: break
+ kotlinFindUsagesHandler.processElementUsages(kotlinDefinition, processor, findUsageOptions)
+ }
+ }
+
+ return super.findReferences(element, searchScope, searchInCommentsAndStrings) + references
+ }
+}
diff --git a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/refactoring/migration/v3tov4/ApolloV3ToV4MigrationProcessor.kt b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/refactoring/migration/v3tov4/ApolloV3ToV4MigrationProcessor.kt
index 6da4eaeb9dd..c1be74522ce 100644
--- a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/refactoring/migration/v3tov4/ApolloV3ToV4MigrationProcessor.kt
+++ b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/refactoring/migration/v3tov4/ApolloV3ToV4MigrationProcessor.kt
@@ -13,8 +13,10 @@ import com.apollographql.ijplugin.refactoring.migration.item.UpdateGradleDepende
import com.apollographql.ijplugin.refactoring.migration.item.UpdateGradlePluginInBuildKts
import com.apollographql.ijplugin.refactoring.migration.item.UpdateMethodCall
import com.apollographql.ijplugin.refactoring.migration.item.UpdateMethodName
+import com.apollographql.ijplugin.refactoring.migration.v3tov4.item.AddLinkDirective
import com.apollographql.ijplugin.refactoring.migration.v3tov4.item.EncloseInService
import com.apollographql.ijplugin.refactoring.migration.v3tov4.item.RemoveFieldInService
+import com.apollographql.ijplugin.refactoring.migration.v3tov4.item.RemoveGraphqlConfigFiles
import com.apollographql.ijplugin.refactoring.migration.v3tov4.item.RemoveMethodInService
import com.apollographql.ijplugin.refactoring.migration.v3tov4.item.RemoveWatchMethodArguments
import com.apollographql.ijplugin.refactoring.migration.v3tov4.item.UpdateEnumClassUpperCase
@@ -29,7 +31,7 @@ import com.intellij.openapi.project.Project
*/
class ApolloV3ToV4MigrationProcessor(project: Project) : ApolloMigrationRefactoringProcessor(project) {
companion object {
- const val apollo4LatestVersion = "4.0.0-beta.5"
+ const val apollo4LatestVersion = "4.0.0-beta.7"
}
override val refactoringName = ApolloBundle.message("ApolloV3ToV4MigrationProcessor.title")
@@ -95,5 +97,11 @@ class ApolloV3ToV4MigrationProcessor(project: Project) : ApolloMigrationRefactor
UpdateCustomTypeMappingInBuildKts,
UpdateMultiModuleConfiguration,
EncloseInService,
+
+ // Add @link to extra.graphqls
+ AddLinkDirective,
+
+ // Graphql Config
+ RemoveGraphqlConfigFiles,
)
}
diff --git a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/refactoring/migration/v3tov4/item/AddLinkDirective.kt b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/refactoring/migration/v3tov4/item/AddLinkDirective.kt
new file mode 100644
index 00000000000..6e7b78fd56e
--- /dev/null
+++ b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/refactoring/migration/v3tov4/item/AddLinkDirective.kt
@@ -0,0 +1,72 @@
+package com.apollographql.ijplugin.refactoring.migration.v3tov4.item
+
+import com.apollographql.ijplugin.refactoring.migration.item.MigrationItem
+import com.apollographql.ijplugin.refactoring.migration.item.MigrationItemUsageInfo
+import com.apollographql.ijplugin.refactoring.migration.item.toMigrationItemUsageInfo
+import com.apollographql.ijplugin.util.KOTLIN_LABS_DEFINITIONS
+import com.apollographql.ijplugin.util.KOTLIN_LABS_URL
+import com.apollographql.ijplugin.util.NULLABILITY_DEFINITIONS
+import com.apollographql.ijplugin.util.NULLABILITY_URL
+import com.apollographql.ijplugin.util.cast
+import com.apollographql.ijplugin.util.createLinkDirective
+import com.apollographql.ijplugin.util.createLinkDirectiveSchemaExtension
+import com.apollographql.ijplugin.util.directives
+import com.apollographql.ijplugin.util.findPsiFilesByName
+import com.apollographql.ijplugin.util.isImported
+import com.apollographql.ijplugin.util.linkDirectives
+import com.apollographql.ijplugin.util.nameForImport
+import com.apollographql.ijplugin.util.unquoted
+import com.intellij.lang.jsgraphql.psi.GraphQLArrayValue
+import com.intellij.lang.jsgraphql.psi.GraphQLDirective
+import com.intellij.lang.jsgraphql.psi.GraphQLElementFactory
+import com.intellij.lang.jsgraphql.psi.GraphQLFile
+import com.intellij.lang.jsgraphql.psi.GraphQLRecursiveVisitor
+import com.intellij.openapi.project.Project
+import com.intellij.psi.PsiMigration
+import com.intellij.psi.search.GlobalSearchScope
+
+object AddLinkDirective : MigrationItem() {
+ override fun findUsages(project: Project, migration: PsiMigration, searchScope: GlobalSearchScope): List {
+ val usages = mutableListOf()
+ val extraGraphqlsFiles: List = project.findPsiFilesByName("extra.graphqls", searchScope).filterIsInstance()
+ for (file in extraGraphqlsFiles) {
+ file.accept(object : GraphQLRecursiveVisitor() {
+ override fun visitDirective(o: GraphQLDirective) {
+ super.visitDirective(o)
+ if (o.name in NULLABILITY_DEFINITIONS.directives().map { it.name }) {
+ if (!o.isImported(NULLABILITY_URL)) {
+ usages.add(o.toMigrationItemUsageInfo(true))
+ }
+ }
+ if (o.name in KOTLIN_LABS_DEFINITIONS.directives().map { it.name }) {
+ if (!o.isImported(KOTLIN_LABS_URL)) {
+ usages.add(o.toMigrationItemUsageInfo(false))
+ }
+ }
+ }
+ })
+ }
+ return usages
+ }
+
+ override fun performRefactoring(project: Project, migration: PsiMigration, usage: MigrationItemUsageInfo) {
+ val directive = usage.element as GraphQLDirective
+ val extraSchemaFile = directive.containingFile as GraphQLFile
+ val definitions = if (usage.attachedData()) NULLABILITY_DEFINITIONS else KOTLIN_LABS_DEFINITIONS
+ val definitionsUrl = if (usage.attachedData()) NULLABILITY_URL else KOTLIN_LABS_URL
+ val linkDirective = extraSchemaFile.linkDirectives(definitionsUrl).firstOrNull()
+ if (linkDirective == null) {
+ val linkDirectiveSchemaExtension =
+ createLinkDirectiveSchemaExtension(project, setOf(directive.nameForImport), definitions, definitionsUrl)
+ val addedElement = extraSchemaFile.addBefore(linkDirectiveSchemaExtension, extraSchemaFile.firstChild)
+ extraSchemaFile.addAfter(GraphQLElementFactory.createWhiteSpace(project, "\n\n"), addedElement)
+ } else {
+ val importedNames = buildSet {
+ addAll(linkDirective.arguments!!.argumentList.firstOrNull { it.name == "import" }?.value?.cast()?.valueList.orEmpty()
+ .map { it.text.unquoted() })
+ add(directive.nameForImport)
+ }
+ linkDirective.replace(createLinkDirective(project, importedNames, definitions, definitionsUrl))
+ }
+ }
+}
diff --git a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/refactoring/migration/v3tov4/item/RemoveGraphqlConfigFiles.kt b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/refactoring/migration/v3tov4/item/RemoveGraphqlConfigFiles.kt
new file mode 100644
index 00000000000..2a714d3eef9
--- /dev/null
+++ b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/refactoring/migration/v3tov4/item/RemoveGraphqlConfigFiles.kt
@@ -0,0 +1,37 @@
+package com.apollographql.ijplugin.refactoring.migration.v3tov4.item
+
+import com.apollographql.ijplugin.refactoring.migration.item.DeletesElements
+import com.apollographql.ijplugin.refactoring.migration.item.MigrationItem
+import com.apollographql.ijplugin.refactoring.migration.item.MigrationItemUsageInfo
+import com.apollographql.ijplugin.refactoring.migration.item.toMigrationItemUsageInfo
+import com.apollographql.ijplugin.util.findPsiFilesByName
+import com.intellij.openapi.project.Project
+import com.intellij.psi.PsiMigration
+import com.intellij.psi.search.GlobalSearchScope
+
+private val graphQLConfigFileNames = setOf(
+ "graphql.config.json",
+ "graphql.config.js",
+ "graphql.config.cjs",
+ "graphql.config.ts",
+ "graphql.config.yaml",
+ "graphql.config.yml",
+ ".graphqlrc",
+ ".graphqlrc.json",
+ ".graphqlrc.yaml",
+ ".graphqlrc.yml",
+ ".graphqlrc.js",
+ ".graphqlrc.ts"
+)
+
+object RemoveGraphqlConfigFiles : MigrationItem(), DeletesElements {
+ override fun findUsages(project: Project, migration: PsiMigration, searchScope: GlobalSearchScope): List {
+ return graphQLConfigFileNames.flatMap {
+ project.findPsiFilesByName(it, searchScope)
+ }.map { it.toMigrationItemUsageInfo() }
+ }
+
+ override fun performRefactoring(project: Project, migration: PsiMigration, usage: MigrationItemUsageInfo) {
+ usage.element.delete()
+ }
+}
diff --git a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/settings/ProjectSettingsService.kt b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/settings/ProjectSettingsService.kt
index 3fb64a39e9b..d445a04e815 100644
--- a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/settings/ProjectSettingsService.kt
+++ b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/settings/ProjectSettingsService.kt
@@ -71,7 +71,14 @@ class ProjectSettingsService(private val project: Project) : PersistentStateComp
_state.telemetryInstanceId = value
}
+ override var apolloKotlinServices: List
+ get() = _state.apolloKotlinServices
+ set(value) {
+ _state.apolloKotlinServices = value
+ }
+
private var lastNotifiedState: ProjectSettingsState? = null
+
private fun notifySettingsChanged() {
if (lastNotifiedState != _state) {
lastNotifiedState = _state.copy()
@@ -98,8 +105,17 @@ interface ProjectSettingsState {
var contributeConfigurationToGraphqlPlugin: Boolean
var apolloKotlinServiceConfigurations: List
var telemetryInstanceId: String
+
+ /**
+ * Cache of the ApolloKotlinServices constructed from the Gradle tooling models.
+ * @see com.apollographql.ijplugin.gradle.GradleToolingModelService
+ */
+ var apolloKotlinServices: List
}
+/**
+ * User configuration associated with an [ApolloKotlinService].
+ */
data class ApolloKotlinServiceConfiguration(
@Attribute
val id: String = "",
@@ -133,6 +149,7 @@ data class ProjectSettingsStateImpl(
override var contributeConfigurationToGraphqlPlugin: Boolean = true,
override var apolloKotlinServiceConfigurations: List = emptyList(),
override var telemetryInstanceId: String = "",
+ override var apolloKotlinServices: List = emptyList(),
) : ProjectSettingsState
diff --git a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/telemetry/TelemetrySession.kt b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/telemetry/TelemetrySession.kt
index e5d05cf9ca1..388bc8d8027 100644
--- a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/telemetry/TelemetrySession.kt
+++ b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/telemetry/TelemetrySession.kt
@@ -339,6 +339,11 @@ sealed class TelemetryEvent(
*/
class ApolloIjApollo4AvailableQuickFix : TelemetryEvent("akij_apollo4_available_quickfix", null)
+ /**
+ * User applied the quickfix for the 'GraphQL config file present' inspection of the Apollo Kotlin IntelliJ plugin.
+ */
+ class ApolloIjGraphQLConfigFilePresentQuickFix : TelemetryEvent("akij_graphql_config_file_present_quickfix", null)
+
/**
* User applied the quickfix for the 'Endpoint not configured' inspection of the Apollo Kotlin IntelliJ plugin.
*/
diff --git a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/inspection/GraphQL.kt b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/util/GraphQL.kt
similarity index 97%
rename from intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/inspection/GraphQL.kt
rename to intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/util/GraphQL.kt
index c87952ba3d5..7af93d17016 100644
--- a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/inspection/GraphQL.kt
+++ b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/util/GraphQL.kt
@@ -1,6 +1,5 @@
-package com.apollographql.ijplugin.inspection
+package com.apollographql.ijplugin.util
-import com.apollographql.ijplugin.util.findPsiFileByUrl
import com.intellij.lang.jsgraphql.ide.config.GraphQLConfigProvider
import com.intellij.lang.jsgraphql.psi.GraphQLDirective
import com.intellij.lang.jsgraphql.psi.GraphQLElement
diff --git a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/inspection/Link.kt b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/util/Link.kt
similarity index 69%
rename from intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/inspection/Link.kt
rename to intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/util/Link.kt
index 7e923cd31f9..d5b023a2d90 100644
--- a/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/inspection/Link.kt
+++ b/intellij-plugin/src/main/kotlin/com/apollographql/ijplugin/util/Link.kt
@@ -1,24 +1,26 @@
@file:OptIn(ApolloInternal::class)
-package com.apollographql.ijplugin.inspection
+package com.apollographql.ijplugin.util
import com.apollographql.apollo3.annotations.ApolloInternal
import com.apollographql.apollo3.ast.GQLDefinition
import com.apollographql.apollo3.ast.GQLDirectiveDefinition
+import com.apollographql.apollo3.ast.GQLNamed
import com.apollographql.apollo3.ast.KOTLIN_LABS_VERSION
import com.apollographql.apollo3.ast.NULLABILITY_VERSION
import com.apollographql.apollo3.ast.kotlinLabsDefinitions
import com.apollographql.apollo3.ast.nullabilityDefinitions
-import com.apollographql.ijplugin.util.quoted
-import com.apollographql.ijplugin.util.unquoted
+import com.apollographql.apollo3.ast.rawType
import com.intellij.lang.jsgraphql.psi.GraphQLArrayValue
import com.intellij.lang.jsgraphql.psi.GraphQLDirective
import com.intellij.lang.jsgraphql.psi.GraphQLElement
+import com.intellij.lang.jsgraphql.psi.GraphQLElementFactory
import com.intellij.lang.jsgraphql.psi.GraphQLFile
import com.intellij.lang.jsgraphql.psi.GraphQLNamedElement
import com.intellij.lang.jsgraphql.psi.GraphQLSchemaDefinition
import com.intellij.lang.jsgraphql.psi.GraphQLSchemaExtension
import com.intellij.lang.jsgraphql.psi.GraphQLStringValue
+import com.intellij.openapi.project.Project
const val NULLABILITY_URL = "https://specs.apollo.dev/nullability/$NULLABILITY_VERSION"
@@ -79,10 +81,48 @@ private fun GraphQLFile.hasImportFor(name: String, isDirective: Boolean, definit
return false
}
-val String.nameWithoutPrefix get() = substringAfter("__")
+private val String.nameWithoutPrefix get() = substringAfter("__")
val GraphQLNamedElement.nameWithoutPrefix get() = name!!.nameWithoutPrefix
fun String.nameForImport(isDirective: Boolean) = "${if (isDirective) "@" else ""}${this.nameWithoutPrefix}"
val GraphQLNamedElement.nameForImport get() = if (this is GraphQLDirective) "@$nameWithoutPrefix" else nameWithoutPrefix
+
+
+fun createLinkDirectiveSchemaExtension(
+ project: Project,
+ importedNames: Set,
+ definitions: List,
+ definitionsUrl: String,
+): GraphQLSchemaExtension {
+ // If any of the imported name is a directive, add its argument types to the import list
+ val knownDefinitionNames = definitions.filterIsInstance().map { it.name }
+ val additionalNames = importedNames.flatMap { importedName ->
+ definitions.directives().firstOrNull { "@${it.name}" == importedName }
+ ?.arguments
+ ?.map { it.type.rawType().name }
+ ?.filter { it in knownDefinitionNames }.orEmpty()
+ }.toSet()
+
+ return GraphQLElementFactory.createFile(
+ project,
+ """
+ extend schema
+ @link(
+ url: "$definitionsUrl",
+ import: [${(importedNames + additionalNames).joinToString { it.quoted() }}]
+ )
+ """.trimIndent()
+ )
+ .findChildrenOfType().single()
+}
+
+fun createLinkDirective(
+ project: Project,
+ importedNames: Set,
+ definitions: List,
+ definitionsUrl: String,
+): GraphQLDirective {
+ return createLinkDirectiveSchemaExtension(project, importedNames, definitions, definitionsUrl).directives.single()
+}
diff --git a/intellij-plugin/src/main/resources/ApolloIconsMapping.json b/intellij-plugin/src/main/resources/ApolloIconsMapping.json
new file mode 100644
index 00000000000..36f8ecf845a
--- /dev/null
+++ b/intellij-plugin/src/main/resources/ApolloIconsMapping.json
@@ -0,0 +1,7 @@
+{
+ "icons": {
+ "newui": {
+ "toolwindow-normalized-cache-viewer.svg": "icons/toolwindow-normalized-cache-viewer.svg"
+ }
+ }
+}
diff --git a/intellij-plugin/src/main/resources/META-INF/plugin.xml b/intellij-plugin/src/main/resources/META-INF/plugin.xml
index 81becd40349..2cc9ab429e7 100644
--- a/intellij-plugin/src/main/resources/META-INF/plugin.xml
+++ b/intellij-plugin/src/main/resources/META-INF/plugin.xml
@@ -63,6 +63,10 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
kotlin
@@ -238,15 +275,18 @@
groupKey="advanced.setting.apollo"
default="false"
/>
+
+
+
-
-
-
-
diff --git a/intellij-plugin/src/main/resources/icons/newui/toolwindow-normalized-cache-viewer.svg b/intellij-plugin/src/main/resources/icons/newui/toolwindow-normalized-cache-viewer.svg
new file mode 100644
index 00000000000..f46ad77bb7a
--- /dev/null
+++ b/intellij-plugin/src/main/resources/icons/newui/toolwindow-normalized-cache-viewer.svg
@@ -0,0 +1,14 @@
+
+
diff --git a/intellij-plugin/src/main/resources/icons/newui/toolwindow-normalized-cache-viewer@20x20.svg b/intellij-plugin/src/main/resources/icons/newui/toolwindow-normalized-cache-viewer@20x20.svg
new file mode 100644
index 00000000000..f5e5ef5df44
--- /dev/null
+++ b/intellij-plugin/src/main/resources/icons/newui/toolwindow-normalized-cache-viewer@20x20.svg
@@ -0,0 +1,14 @@
+
+
diff --git a/intellij-plugin/src/main/resources/icons/newui/toolwindow-normalized-cache-viewer@20x20_dark.svg b/intellij-plugin/src/main/resources/icons/newui/toolwindow-normalized-cache-viewer@20x20_dark.svg
new file mode 100644
index 00000000000..a2fb56e560e
--- /dev/null
+++ b/intellij-plugin/src/main/resources/icons/newui/toolwindow-normalized-cache-viewer@20x20_dark.svg
@@ -0,0 +1,14 @@
+
+
diff --git a/intellij-plugin/src/main/resources/icons/newui/toolwindow-normalized-cache-viewer_dark.svg b/intellij-plugin/src/main/resources/icons/newui/toolwindow-normalized-cache-viewer_dark.svg
new file mode 100644
index 00000000000..acca68e44a3
--- /dev/null
+++ b/intellij-plugin/src/main/resources/icons/newui/toolwindow-normalized-cache-viewer_dark.svg
@@ -0,0 +1,14 @@
+
+
diff --git a/intellij-plugin/src/main/resources/inspectionDescriptions/ApolloGraphQLConfigFilePresent.html b/intellij-plugin/src/main/resources/inspectionDescriptions/ApolloGraphQLConfigFilePresent.html
new file mode 100644
index 00000000000..0a6bf4ada3a
--- /dev/null
+++ b/intellij-plugin/src/main/resources/inspectionDescriptions/ApolloGraphQLConfigFilePresent.html
@@ -0,0 +1,15 @@
+
+
+Suggests to delete GraphQL config files on projects using Apollo Kotlin 4.
+
+ It is no longer useful to have a GraphQL config file, as the Apollo plugin automatically provides the location of your
+ project's operations and schema files to the GraphQL plugin,
+
+
+ Note: the Apollo plugin uses the Gradle tooling API to retrieve the project's GraphQL configuration.
+
icons will show next to references to generated operation and fragment classes.
+When editing Kotlin code, 
button at the top of the editor.
+This is also accessible from the