You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/source/migration/4.0.mdx
+68-63Lines changed: 68 additions & 63 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,23 +11,53 @@ description: From version 3
11
11
12
12
Apollo Kotlin 3 was a major rewrite of Apollo in Kotlin multiplatform.
13
13
14
-
Apollo Kotlin 4 focuses on tooling, stability and fixing some API regrets that came with 3.
15
-
16
-
While most of the common APIs stayed the same, Apollo Kotlin 4 contains a few binary breaking changes. To account for that, and in order to be more future proof, we [changed the package name](https://github.com/apollographql/apollo-kotlin/issues/4710) to `com.apollographql.apollo`.
14
+
Apollo Kotlin 4 focuses on tooling, stability and making the library more maintainable, so it can evolve smoothly for the many years to come.
17
15
18
16
Apollo Kotlin 4 removes some deprecated symbols. We strongly recommend removing deprecated usages before migrating to version 4.
19
17
20
-
If you are using a library that depends on Apollo Kotlin transitively, you need it to update to version 4 before you can update your own application to version 4.
21
-
22
-
## Automatic migration using the Android Studio plugin
18
+
## Automatic migration using the Android Studio/IntelliJ plugin
23
19
24
-
Apollo Kotlin 4 ships with a companion [Android Studio plugin](../testing/android-studio-plugin#migration-helpers) that automates most of the migration.
20
+
Apollo Kotlin 4 ships with a companion [Android Studio/IntelliJ plugin](../testing/android-studio-plugin#migration-helpers) that automates most of the migration.
25
21
26
22
It automates most of the API changes but cannot deal with behavior changes like error handling.
27
23
28
24
We recommend using the plugin to automate the repetitive tasks but still go through this document for the details.
29
25
30
-
## Error handling
26
+
## Moved artifacts
27
+
28
+
Over the years, a lot of support functionality was added alongside the `apollo-api` and `apollo-runtime` artifacts. While useful, most of this functionality doesn't share the same level of stability and maturity as the core artifacts and bundling them did not make much sense.
29
+
30
+
Moving forward, only the core artifacts remain in the `apollo-kotlin` repository and are released together.
31
+
32
+
Other artifacts are moved to new maven coordinates and GitHub repositories.
33
+
34
+
| Old coordinates | New coordinates | New Repository |
@@ -39,9 +69,7 @@ See [nullability](../advanced/nullability) for a quick peek at the future of Gra
39
69
40
70
</Caution>
41
71
42
-
### Fetch errors do not throw
43
-
44
-
In Apollo Kotlin 3, non-GraphQL errors like network errors, cache misses, and parsing errors were surfaced by throwing exceptions in `ApolloCall.execute()` and in Flows (`ApolloCall.toFlow()`, `ApolloCall.watch()`). This was problematic because it was a difference in how to handle GraphQL errors vs other errors. Moreover, throwing terminates a Flow and consumers would have to handle re-collection.
72
+
In Apollo Kotlin 3, non-GraphQL errors like network errors, cache misses, and parsing errors were surfaced by throwing exceptions in `ApolloCall.execute()` and in Flows (`ApolloCall.toFlow()`, `ApolloCall.watch()`). This was problematic because it was a difference in how to handle GraphQL errors vs other errors and it was easy to forget catching the exceptions. Uncaught network errors is by far the number one error reported by the [Google Play SDK Index](https://play.google.com/sdks). Moreover, throwing terminates a Flow and consumers would have to handle re-collection.
45
73
46
74
In Apollo Kotlin 4, a new field `ApolloResponse.exception` has been added and these errors are now surfaced by returning (for `execute()`) or emitting (for Flows) an `ApolloResponse` with a non-null `exception` instead of throwing it.
### ApolloCompositeException is not thrown anymore
147
+
### ApolloCompositeException is not thrown
120
148
121
149
When using the cache, Apollo Kotlin 3 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.
122
150
@@ -134,6 +162,8 @@ val cacheMissException = exception
134
162
val networkException = exception.suppressedExceptions.firstOrNull()
135
163
```
136
164
165
+
For more control over the exception, use `toFlow()` and collect the different `ApolloResponse`.
166
+
137
167
### emitCacheMisses(Boolean) is removed
138
168
139
169
In Apollo Kotlin 3, when using the normalized cache, you could set `emitCacheMisses` to `true` to emit cache misses instead of throwing.
@@ -154,9 +184,7 @@ Those helper functions:
154
184
* make `CacheFirst`, `NetworkFirst` and `CacheAndNetwork` policies ignore fetch errors.
155
185
* throw ApolloComposite exception if needed.
156
186
157
-
Because of the number of different options in version 3 and the complexity of error handling, these functions may not 100% match the 3 behavior, especially in the advanced cases involving watchers. If you are in one of those cases, we strongly recommend using the 4 functions that are easier to reason about.
158
-
159
-
## Other Apollo Runtime changes
187
+
Because of the number of different options in version 3 and the complexity of error handling, these functions may not 100% match the version 3 behavior, especially in the advanced cases involving watchers. If you are in one of those cases, we strongly recommend using the version 4 functions that are easier to reason about.
160
188
161
189
### Non standard HTTP headers are not sent by default
162
190
@@ -194,47 +222,11 @@ val call = client.query(MyQuery())
194
222
.execute()
195
223
```
196
224
197
-
### `HttpEngine`now implements `Closeable`
225
+
### `HttpEngine` implements `Closeable`
198
226
199
227
`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`.
200
228
201
-
202
-
## Maven artifacts reorganization
203
-
204
-
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.
205
-
206
-
Moving forward, some artifacts are released separately and have new Maven coordinates, GitHub repositories and package names. Others are deprecated.
207
-
208
-
For the initial version 4 release, most artifacts are kept with deprecation warnings and will be removed in the future.
209
-
210
-
The artifacts are:
211
-
212
-
* apollo-mockserver
213
-
* 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.
214
-
* apollo-cli-incubating
215
-
* The Apollo CLI contract is subject to change and it has been moved to a separate repository.
216
-
* apollo-rx-support
217
-
* The RxJava{2-3} artifacts are very thin wrappers around kotlinx-coroutines-rx{2-3} and we recommend using those instead.
218
-
* apollo-idling-resource
219
-
* 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.
220
-
221
-
### Summary
222
-
223
-
| Old coordinates | New coordinates | New Repository |
### Publishing is no longer configured automatically
321
+
322
+
Apollo artifacts are not automatically published anymore. To publish them, create a `MavenPublication`:
323
+
324
+
```kotlin
325
+
publishing {
326
+
publications {
327
+
create("apollo", MavenPublication::class.java) {
328
+
from(components["apollo"])
329
+
artifactId ="${project.name}-apollo"
330
+
}
331
+
}
332
+
}
333
+
```
328
334
329
335
### Custom scalars declaration
330
336
@@ -415,10 +421,6 @@ class MyPlugin: ApolloCompilerPlugin {
415
421
}
416
422
```
417
423
418
-
### Publishing is no longer configured automatically
419
-
420
-
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.
421
-
422
424
### Operation manifest file location
423
425
424
426
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"`.
@@ -427,7 +429,7 @@ Since Apollo Kotlin now supports [different operation manifest formats](../advan
427
429
428
430
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.
429
431
430
-
## Apollo Compiler
432
+
## apollo-compiler
431
433
432
434
### "compat" `codegenModels` is removed
433
435
@@ -580,7 +582,7 @@ val myEnum = MyEnum.UNKNOWN__("foo")
580
582
val myEnum = MyEnum.safeValueOf("foo")
581
583
```
582
584
583
-
## Cache
585
+
## apollo-normalized-cache
584
586
585
587
### Configuration order
586
588
@@ -614,12 +616,13 @@ The AST classes (`GQLNode` and subclasses) as well as `Introspection` classes ar
614
616
615
617
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()`.
616
618
619
+
## apollo-rx{2-3}-support
617
620
618
-
## Using RxJava artifacts is now an error
621
+
The `apollo-rx2-support` and `apollo-rx3-support` artifacts are deprecated.
619
622
620
-
The `apollo-rx2-support` and `apollo-rx3-support` artifacts are very thin wrappers around [`kotlinx-coroutines-rx2`](https://github.com/Kotlin/kotlinx.coroutines/tree/master/reactive/kotlinx-coroutines-rx2) or [`kotlinx-coroutines-rx3`](https://github.com/Kotlin/kotlinx.coroutines/tree/master/reactive/kotlinx-coroutines-rx3) and will be removed in a future version.
623
+
They were very thin wrappers around [`kotlinx-coroutines-rx2`](https://github.com/Kotlin/kotlinx.coroutines/tree/master/reactive/kotlinx-coroutines-rx2) or [`kotlinx-coroutines-rx3`](https://github.com/Kotlin/kotlinx.coroutines/tree/master/reactive/kotlinx-coroutines-rx3) and will be removed in a future version.
621
624
622
-
In Apollo Kotlin 4, use `kotlinx-coroutines-rx${version}` instead. Replacetheartifactinyourbuildscript:
625
+
Use `kotlinx-coroutines-rx${version}`directlylinstead. Replacetheartifactinyourbuildscript:
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.
Copy file name to clipboardExpand all lines: libraries/apollo-adapters/README.md
-1Lines changed: 0 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -15,4 +15,3 @@ apollo-adapters contains adapters for common date and big decimal GraphQL scalar
15
15
|`com.apollographql.apollo3.adapter.JavaOffsetDateTimeAdapter`| For `java.time.OffsetDateTime` ISO8601 dates |
16
16
|`com.apollographql.apollo3.adapter.DateAdapter`| For `java.util.Date` ISO8601 dates |
17
17
|`com.apollographql.apollo3.adapter.BigDecimalAdapter`| For a Multiplatform `com.apollographql.apollo3.adapter.BigDecimal` class holding big decimal values |
18
-
|`com.apollographql.apollo3.network.adapter.KtorHttpUrlAdapter`| For `io.ktor.http.Url` class holding url values |
0 commit comments