Version 3.1.0 introduces new APIs for testing, mapping scalars as well a redesigned cache pipeline.
It also contains bugfixes around the @include directives, MemoryCache and GraphQL validation amongst other changes.
useSchemaPackageNameForFragments (#3775)If you're using packageNameFromFilePath(), the package name of generated fragment classes has changed.
Different generated types have different package names:
Previously, fragments were using the schema path which is inconsistent because fragments are not defined in the schema but are executable files, like operations.
Version 3.1.0 now uses the same logic for fragments as for operations. To revert to the previous behaviour, you can use useSchemaPackageNameForFragments:
apollo {
useSchemaPackageNameForFragments.set(true)
}
This is also done automatically if you're using useVersion2Compat(). Moving forward, the plan is to remove useSchemaPackageNameForFragments in favor of setting a custom PackageNameGenerator. If you have use cases that require useSchemaPackageNameForFragments, please reach out.
QueueTestNetworkTransport (#3757)3.1.0 introduces QueueTestNetworkTransport to test at the GraphQL layer without needing to run an HTTP server.
To use it, configure your ApolloClient:
// This uses a QueueTestNetworkTransport that will play the queued responses
val apolloClient = ApolloClient.Builder()
.networkTransport(QueueTestNetworkTransport())
.build()
You can then use the enqueueTestResponse extension function to specify the GraphQL responses to return:
val testQuery = GetHeroQuery("001")
val testData = GetHeroQuery.Data {
hero = droidHero {
name = "R2D2"
}
}
apolloClient.enqueueTestResponse(testQuery, testData)
val actual = apolloClient.query(testQuery).execute().data!!
assertEquals(testData.hero.name, actual.hero.name)
MockServerHandler (#3757)If you're testing at the HTTP layer, you can now define your own MockServerHandler to customize how the server is going to answer to requests:
val customHandler = object : MockServerHandler {
override fun handle(request: MockRequest): MockResponse {
return if (/* Your custom logic here */) {
MockResponse(
body = """{"data": {"random": 42}}""",
headers = mapOf("X-Test" to "true"),
)
} else {
MockResponse(
body = "Internal server error",
statusCode = 500,
)
}
}
}
val mockServer = MockServer(customHandler)
FetchPolicy.CacheAndNetwork (#3828)Previously, FetchPolicys were limited to policies that emitted at most one response. There was a executeCacheAndNetwork() method but it felt asymmetrical. This version introduces FetchPolicy.CacheAndNetwork that can emit up to two responses:
apolloClient.query(query)
// Check the cache and also use the network (1 or 2 values can be emitted)
.fetchPolicy(FetchPolicy.CacheAndNetwork)
// Execute the query and collect the responses
.toFlow().collect { response ->
// ...
}
ApolloCall<D>.fetchPolicyInterceptor(interceptor: ApolloInterceptor) (#3743)If you need more customized ways to fetch data from the cache or more fine-grained error handling that does not come with the built-in FetchPolicy, you can now use fetchPolicyInterceptor:
// An, interceptor that will only use the network after getting a successful response
val refetchPolicyInterceptor = object : ApolloInterceptor {
var hasSeenValidResponse: Boolean = false
override fun <D : Operation.Data> intercept(request: ApolloRequest<D>, chain: ApolloInterceptorChain): Flow<ApolloResponse<D>> {
return if (!hasSeenValidResponse) {
CacheOnlyInterceptor.intercept(request, chain).onEach {
if (it.data != null) {
// We have valid data, we can now use the network
hasSeenValidResponse = true
}
}
} else {
// If for some reason we have a cache miss, get fresh data from the network
CacheFirstInterceptor.intercept(request, chain)
}
}
}
apolloClient.query(myQuery)
.refetchPolicyInterceptor(cacheOnlyInterceptor)
.watch()
.collect {
//
}
Service.mapScalar Gradle API (#3779)You can now use mapScalar to specify your scalar mappings:
apollo {
// Replace
customScalarsMapping.set(mapOf(
"Date" to "java.util.Date"
))
// With
mapScalar("Date", "java.util.Date")
}
mapScalar also works with built-in scalar types so you can map the ID type to a kotlin Long:
apollo {
// This requires registering an adapter at runtime with `addCustomScalarAdapter()`
mapScalar("ID", "kotlin.Long")
}
As an optimization, you can also provide the adapter at compile time. This will avoid a lookup at runtime everytime such a scalar is read:
apollo {
// No need to call `addCustomScalarAdapter()`, the generated code will use the provided adapter
mapScalar("ID", "kotlin.Long", "com.apollographql.apollo3.api.LongAdapter")
}
For convenience, a helper function is provided for common types:
apollo {
// The generated code will use `kotlin.Long` and the builtin LongAdapter
mapScalarToKotlinLong("ID")
// The generated code will use `kotlin.String` and the builtin StringAdapter
mapScalarToKotlinString("Date")
// The generated code will use `com.apollographql.apollo3.api.Upload` and the builtin UploadAdapter
mapScalarToUpload("Upload")
}
convertApolloSchema and downloadApolloSchema now use paths relative to the root of the project (#3773, #3752)Apollo Kotlin adds two tasks to help to manage schemas: convertApolloSchema and downloadApolloSchema. These tasks are meant to be used from the commandline.
Previously, paths were interpreted using the current working directory with File(path). Unfortunately, this is unreliable because Gradle might change the current working directory in some conditions (see Gradle#13927 or Gradle#6074 for an example).
With 3.1.0 and onwards, paths, will be interpreted relative to the root project directory (project.rootProject.file(path)):
# schema is now interpreted relative to the root project directory and
# not the current working directory anymore. This example assumes there
# is a 'app' module that applies the apollo plugin
./gradlew downloadApolloSchema \
--endpoint="https://your.domain/graphql/endpoint" \
--schema="app/src/main/graphql/com/example/schema.graphqls"
Many thanks to @dhritzkiv, @mune0903, @StylianosGakis, @AchrafAmil and @jamesonwilliams for their awesome contributions! You rock 🎸 🤘 !
reconnectWhen suspend and pass attempt number (#3772).okHttpClient (#3771)convertApolloSchema and downloadApolloSchema use path from the root of the project (#3773, #3752)This is the first stable release for Apollo Android 3 Apollo Kotlin 3 🎉!
There is documentation, a migration guide and a blog post.
In a nutshell, Apollo Kotlin 3 brings:
Feel free to ask questions by either opening an issue on our GitHub repo, joining the community or stopping by our channel in the KotlinLang Slack(get your invite here).
3.0.0-rc03:Compared to the previous RC, this version adds a few new convenience API and fixes 3 annoying issues.
💙 Many thanks to @mateuszkwiecinski, @schoeda and @fn-jt for all the feedback 💙
ApolloCall.operation public (#3698)SubscriptionWsProtocolAdapter (#3697)Operation.composeJsonRequest (#3697)@fieldPolicy (#3686)💙 Many thanks to @michgauz, @joeldenke, @rohandhruva, @schoeda, @CoreFloDev and @sproctor for all the feedback 💙
In order to simplify the API and keep the symmetry with ApolloRequest<D> and ApolloResponse<D>, ApolloQueryCall<D, E>, ApolloSubscriptionCall<D, E>, ApolloMutationCall<D, E> are replaced with ApolloCall<D>. This change should be mostly transparent but it's technically a breaking change. If you are passing ApolloQueryCall<D, E> variables, it is safe to drop the second type parameter and use ApolloCall<D> instead.
WebSocketNetworkTransport.reconnectWhen {} (#3674)You now have the option to reconnect a WebSocket automatically when an error happens and re-subscribe automatically after the reconnection has happened. To do so, use the webSocketReconnectWhen parameter:
val apolloClient = ApolloClient.Builder()
.httpServerUrl("http://localhost:8080/graphql")
.webSocketServerUrl("http://localhost:8080/subscriptions")
.wsProtocol(
SubscriptionWsProtocol.Factory(
connectionPayload = {
mapOf("token" to upToDateToken)
}
)
)
.webSocketReconnectWhen {
// this is called when an error happens on the WebSocket
it is ApolloWebSocketClosedException && it.code == 1001
}
.build()
The HttpBatchingEngine has been moved to an HttpInterceptor. You can now configure Http batching with a specific method:
apolloClient = ApolloClient.Builder()
.serverUrl(mockServer.url())
.httpBatching(batchIntervalMillis = 10)
.build()
Rx2Apollo, prefetch(), customAttributes(), ApolloIdlingResource.create()) to help the transition (#3679)WebSocketNetworkTransport.reconnectWhen {} (#3674)This version is the release candidate for Apollo Android 3 🚀. Please try it and report any issues, we'll fix them urgently.
There is documentation and a migration guide. More details are coming soon. In a nutshell, Apollo Android 3 brings, amongst other things:
Compared to beta05, this version changes the default value of generateOptionalOperationVariables, is compatible with Gradle configuration cache and fixes a few other issues.
The default value for the generateOptionalOperationVariables config is now true.
What this means:
Optional parametersFor instance:
query GetTodos($first: Int, $offset: Int) {
todos(first: $first, offset: $offset) {
...Todo
}
}
// Before
val query = GetTodosQuery(100, null)
// After
val query = GetTodosQuery(Optional.Present(100), Optional.Absent)
generateOptionalOperationVariables to false to generate non-optional parameters globally@optional directiveWe think this change will make more sense to the majority of users (and is consistent with Apollo Android v2's behavior) even though it may be more verbose, which is why it is possible to change the behavior via the generateOptionalOperationVariables config.
To keep the beta05 behavior, set generateOptionalOperationVariables to false in your Gradle configuration:
apollo {
generateOptionalOperationVariables.set(false)
}
You can now pass WebSocket related options to the ApolloClient.Builder directly (previously this would have been done via NetworkTransport):
// Before
val apolloClient = ApolloClient.Builder()
// (...)
.subscriptionNetworkTransport(WebSocketNetworkTransport(
serverUrl = "https://example.com/graphql",
idleTimeoutMillis = 1000L,
wsProtocol = SubscriptionWsProtocol.Factory()
))
.build()
// After
val apolloClient = ApolloClient.Builder()
// (...)
.wsProtocol(SubscriptionWsProtocol.Factory())
.webSocketIdleTimeoutMillis(1000L)
.build()
This version upgrades OkHttp to 4.9.3 (from 3.12.11). This means Apollo Android now requires Android apiLevel 21+. As OkHttp 3 enters end of life at the end of the year and the vast majority of devices now support apiLevel 21, we felt this was a reasonable upgrade.
We intended this version to be the first release candidate but we found a few bugs justifying a new beta instead. Many thanks to @CoreFloDev, @olivierg13, @rohandhruva, @adavis and @sproctor for identifying the bugs and sending feedback, this helps a ton 🙏 💙 . Next one should be release candidate 🤞 🚀
The escaping of Kotlin keywords used in field names now uses Kotlin's backtick escaping (`keyword`) convention instead of suffixing an underscore (keyword_). This could impact the generated code in your projects if a schema contains such fields. (#3630)
Before going stable, the public API has been tweaked to ensure consistency.
Upload creation (#3613)Creating an Upload used to be possible by calling Upload.fromXyz() methods and now has been changed to use a Builder API which is more consistent with the rest of the API:
// Before
val upload = Upload.fromSource(okioSource)
// or if you're on the JVM
val upload = Upload.fromFile(file)
// After
val upload = DefaultUpload.Builder()
.content(bufferedSource)
// or if you're on the JVM
.content(file)
.build()
The method to enable or disable Automatic Persisted Queries on a specific call has been renamed to a more meaningful name:
// Before
val response = apolloClient.query(HeroNameQuery())
.hashedQuery(false)
.execute()
// After
val response = apolloClient.query(HeroNameQuery())
.enableAutoPersistedQueries(false)
.execute()
During the course of the alpha and beta, a number of APIs have been evolving, and to allow a smooth transition by early adopters, some early APIs have been marked as deprecated in favor of new ones.
Now that we are soon reaching a stable API, it is time to remove these early APIs.
This means if you were using 3.0.0-beta04 or earlier you may want to first review the deprecation warnings and update your code to use the newer APIs, before upgrading to this version.
ApolloResponse, you can now do so by using a Builder API (#3608)BufferedSource as input. (#3620)HttpEngine (OkHttpEngine, NSURLSessionHttpEngine, and KtorHttpEngine) have all been renamed to DefaultHttpEngine for consistency (#3617)// Before
String result = StringAdapter.INSTANCE.fromJson(jsonReader,CustomScalarAdapters.Empty);
// After
String result = Adapters.StringAdapter.fromJson(jsonReader,CustomScalarAdapters.Empty);
IOException in Adapter APIs, making it possible to catch it in Java code (#3603)This version is planned to be the last beta of Apollo Android 3 before a release candidate 🚀. It mainly focuses on stabilization and tweaks to the public API, makes it easier to work with the Java9 module system, and fixes a few issues.
Before going stable, we tweaked the public API to ensure consistency. The following methods have been renamed:
| Before | After |
|---|---|
ApolloClient.mutate() | ApolloClient.mutation() |
ApolloClient.subscribe() | ApolloClient.subscription() |
ApolloSubscriptionCall.execute() | ApolloSubscriptionCall.toFlow() |
In order to better support Java 9 and remove split packages, the following classes have been moved:
| Before | After |
|---|---|
com.apollographql.apollo3.cache.ApolloCacheHeaders | com.apollographql.apollo3.cache.normalized.api.ApolloCacheHeaders |
com.apollographql.apollo3.cache.CacheHeaders | com.apollographql.apollo3.cache.normalized.api.CacheHeaders |
com.apollographql.apollo3.cache.CacheHeaders.Builder | com.apollographql.apollo3.cache.normalized.api.CacheHeaders.Builder |
com.apollographql.apollo3.cache.CacheHeaders.Companion | com.apollographql.apollo3.cache.normalized.api.CacheHeaders.Companion |
com.apollographql.apollo3.cache.normalized.CacheKey | com.apollographql.apollo3.cache.normalized.api.CacheKey |
com.apollographql.apollo3.cache.normalized.CacheKey.Companion | com.apollographql.apollo3.cache.normalized.api.CacheKey.Companion |
com.apollographql.apollo3.cache.normalized.CacheKeyResolver | com.apollographql.apollo3.cache.normalized.api.CacheKeyResolver |
com.apollographql.apollo3.cache.normalized.CacheResolver | com.apollographql.apollo3.cache.normalized.api.CacheResolver |
com.apollographql.apollo3.cache.normalized.DefaultCacheResolver | com.apollographql.apollo3.cache.normalized.api.DefaultCacheResolver |
com.apollographql.apollo3.cache.normalized.FieldPolicyCacheResolver | com.apollographql.apollo3.cache.normalized.api.FieldPolicyCacheResolver |
com.apollographql.apollo3.cache.normalized.NormalizedCache.Companion | com.apollographql.apollo3.cache.normalized.api.NormalizedCache.Companion |
com.apollographql.apollo3.cache.normalized.NormalizedCacheFactory | com.apollographql.apollo3.cache.normalized.api.NormalizedCacheFactory |
com.apollographql.apollo3.cache.normalized.ReadOnlyNormalizedCache | com.apollographql.apollo3.cache.normalized.api.ReadOnlyNormalizedCache |
com.apollographql.apollo3.cache.normalized.Record | com.apollographql.apollo3.cache.normalized.api.Record |
com.apollographql.apollo3.cache.normalized.RecordFieldJsonAdapter | com.apollographql.apollo3.cache.normalized.api.RecordFieldJsonAdapter |
com.apollographql.apollo3.cache.normalized.MemoryCache | com.apollographql.apollo3.cache.normalized.api.MemoryCache |
com.apollographql.apollo3.cache.normalized.MemoryCacheFactory | com.apollographql.apollo3.cache.normalized.api.MemoryCacheFactory |
com.apollographql.apollo3.cache.normalized.OperationCacheExtensionsKt | com.apollographql.apollo3.cache.normalized.api.OperationCacheExtensionsKt |
Other renames
| Before | After |
|---|---|
com.apollographql.apollo3.api.ApolloExperimental | com.apollographql.apollo3.annotations.ApolloExperimental |
com.apollographql.apollo3.api.ApolloInternal | com.apollographql.apollo3.annotations.ApolloInternal |
com.apollographql.apollo3.cache.normalized.ObjectIdGenerator | com.apollographql.apollo3.cache.normalized.api.CacheKeyGenerator |
com.apollographql.apollo3.cache.normalized.ObjectIdGeneratorContext | com.apollographql.apollo3.cache.normalized.api.CacheKeyGeneratorContext |
com.apollographql.apollo3.network.http.OkHttpEngine | com.apollographql.apollo3.network.http.DefaultHttpEngine |
ApolloClient's mutate and subscribe methods have been renamed to mutation and subscription respectively. This
creates a more consistent API by reusing the GraphQL specification terminology.
Also, mutate(), subscribe() could be misleading as despite being verbs, no action is done until execute() is
called. Using mutation()/subscription() hints that execute() is required as a terminal operation.
// Before
val data = client.mutate(MyMutation()).execute()
// After
val data = client.mutation(MyMutation()).execute()
Also, ApolloSubscriptionCall.execute() has been renamed to ApolloSubscriptionCall.toFlow() to make it clearer that it
returns a cold Flow that can be collected several times:
// Before
val flow = client.subscription(MySubscription).execute()
// After
val flow = client.subscription(MySubscription).toFlow()
CacheKeys were sometimes referred to as Cache ids, Object ids, despite all of them being the same concept (the key
of an object in the cache). For consistency inside the Apollo Android codebase and with the iOS and Web
clients, CacheKey is going to be used everywhere moving forward
// Before
val objectIdGenerator = object : ObjectIdGenerator {
override fun cacheKeyForObject(obj: Map<String, Any?>, context: ObjectIdGeneratorContext): CacheKey? {
// Retrieve the id from the object itself
return CacheKey(obj["id"] as String)
}
}
val apolloClient = ApolloClient.Builder()
.serverUrl("https://...")
.normalizedCache(
normalizedCacheFactory = cacheFactory,
objectIdGenerator = objectIdGenerator,
)
.build()
// After
val cacheKeyGenerator = object : CacheKeyGenerator {
override fun cacheKeyForObject(obj: Map<String, Any?>, context: CacheKeyGeneratorContext): CacheKey? {
// Retrieve the id from the object itself
return CacheKey(obj["id"] as String)
}
}
val apolloClient = ApolloClient.Builder()
.serverUrl("https://...")
.normalizedCache(
normalizedCacheFactory = cacheFactory,
cacheKeyGenerator = cacheKeyGenerator,
)
.build()
dataAssertNoErrors (#3534)To reflect more accurately what this method does, dataOrThrow is now dataAssertNoErrors.
Apollo Android can either generate GraphQL enums as Kotlin enums or sealed classes. In previous 3.0 releases, the
default was to generate sealed classes but it is now enums, as this will be more expected, works better with Swift, and
is consistent with the 2.x behavior. To fallback to the previous behaviour of always generating sealed classes, use the sealedClassesForEnumsMatching Gradle option:
apollo {
sealedClassesForEnumsMatching.set(listOf(".*"))
}
Using Apollo Android from Java should be less cumbersome thanks to a few API tweaks in this release. For example, to set up a normalized cache:
// Before
builder = ClientCacheExtensionsKt.normalizedCache(
builder,
new MemoryCacheFactory(10 * 1024 * 1024, -1),
TypePolicyObjectIdGenerator.INSTANCE,
FieldPolicyCacheResolver.INSTANCE,
false
);
// After
NormalizedCache.configureApolloClientBuilder(
builder,
new MemoryCacheFactory(10 * 1024 * 1024, -1),
);
HttpNetworkTransport and WebSocketNetworkTransport now use the Builder pattern for instantiationFlowDecorator have been removed from ApolloClient as ApolloInterceptor can be used insteadhttpHeader extension is now addHttpHeaderApollo Android now publishes jar files containing the Automatic-Module-Name property and non-split packages. This
change makes it easier to work with Apollo Android from a Java 9+ modularized application.
You no longer need to register any of the built-in adapters after declaring a custom scalar type that maps to a built-in type (Int, Long, String, etc.).
For instance, when declaring this custom scalar type:
apollo {
customScalarsMapping = [
"MyCustomNumber": "kotlin.Long"
]
}
There is no need to call addCustomScalarAdapter on the builder anymore, as since it is for a kotlin.Long it will
automatically fall back to the built-in LongAdapter.
Version 2.5.11 is a maintenance release with fixes for registerApolloOperations and query batching.
💜 Many thanks to @AOrobator and @rocketraman for their awesome contributions and feedback !💜
Full Changelog: https://github.com/apollographql/apollo-android/compare/v2.5.10...v2.5.11
3.0.0-beta03 is a hotfix release to fix an issue where the SQLite cache could trigger SQLiteDatabaseLockedException under load (#3503). If you're using the SQLite cache, we strongly recommend updating.
This version introduces fluent APIs on operations, more multiplatform targets, more compatibility helpers to ease transition from v2.x, and other fixes.
The API to execute operations now uses the Fluent style, where you can chain method calls together. The ApolloClient query, mutate and subscribe methods now return an ApolloCall that can be configured, and on which you can call execute to execute the operation.
Before:
val request = ApolloRequest.Builder(HeroQuery()).fetchPolicy(FetchPolicy.NetworkOnly).build()
val response = apolloClient.query(request)
After (fluent):
val response = apolloClient.query(HeroQuery())
.fetchPolicy(FetchPolicy.NetworkOnly)
.execute()
If you were using cacheAndNetwork, it's now executeCacheAndNetwork:
// Before
apolloClient.cacheAndNetwork(query)
// After
apolloClient.query(query).executeCacheAndNetwork()
This release adds support for these new targets:
macosArm64iosArm64iosSimulatorArm64watchosArm64watchosSimulatorArm64tvosArm64tvosX64tvosSimulatorArm64Additionally, apollo-api (models) is now compiled for linuxX64. Follow this issue for updates on this - and contributions on this area are welcome!
When using the responseBased codegen, now interfaces will be generated as sealed when possible.
Because sealed interfaces are only available since Kotlin 1.5, a new Gradle option languageVersion has been introduced to control this behavior (and potentially future language features used by the codegen).
To ease transition from 2.x, this release provides:
CustomTypeAdapter that can be used for custom scalars in the same way as in 2.xInput helper that will map to 3.x Optional automaticallyThese helpers are deprecated and are to be used only as a temporary measure - they will be removed in a future version.
Thanks to @davidec-twinlogix, @pauldavies83 @nachtien and @Pitel for their awesome contributions!
Version 3.0.0-beta01 is the first Beta release for Apollo Android 3 🎉. While there are no API stability guarantees just yet, 3.0.0-beta01 introduces binary compatibility validation to monitor the breaking changes and they should happen less frequently from now on.
One important API change in 3.0.0-beta01 is the change from with-ers to Builders. It also has a useVersion2Compat Gradle property to ease the transition from 2.x.
In addition, 3.0.0-beta01 introduces JavaScript runtime and cache support and new Test Builders APIs to generate fake data models.
💜 Many thanks to @Pitel and @dchappelle for the awesome additions to this release !💜
Version 3.0.0-beta01 has support for JavaScript targets courtesy of @Pitel. It contains both IR and LEGACY artifacts. To use it in your builds, add apollo-runtime and apollo-normalized-cache dependencies to your build.gradle[.kts]:
kotlin {
js(IR) { // or js(LEGACY)
sourceSets {
val commonMain by getting {
// To use HTTP and runtime
implementation("com.apollographql.apollo3:apollo-runtime:3.0.0-beta01")
// To use in-memory cache
implementation("com.apollographql.apollo3:apollo-normalized-cache:3.0.0-beta01")
}
}
}
}
This is everything needed. All the APIs work the same as their equivalent JVM/native ones.
Two caveats:
Contributions are very welcome, feel free to reach out on the kotlin lang slack to get started!
You can now opt-in generation of Test Builders that make it easier to build fake models for your operations. Test Builders allow to generate fake data using a type safe DSL and provides mock values for fields so that you don't have to specify them all.
To enable Test Builders, add the below to your Gradle scripts:
apollo {
generateTestBuilders.set(true)
}
This will generate builders and add them to your test sourceSets. You can use them to generate fake data:
// Import the generated TestBuilder
import com.example.test.SimpleQuery_TestBuilder.Data
@Test
fun test() {
// Data is an extension function that will build a SimpleQuery.Data model
val data = SimpleQuery.Data {
// Specify values for fields that you want to control
hero = droidHero {
name = "R2D2"
friends = listOf(
friend {
name = "Luke"
}
)
// leave other fields untouched, and they will be returned with mocked data
// planet = ...
}
}
// Use the returned data
}
You can control the returned mock data using the TestResolver API:
val myTestResolver = object: DefaultTestResolver() {
fun resolveInt(path: List<Any>): Int {
// Always return 42 in fake data for Int fields
return 42
}
}
val data = SimpleQuery.Data(myTestResolver) {}
// Yay, now every Int field in `data` is 42!
3.0.0-beta01 introduces new Gradle options for better compatibility with versions 2. Most of the changes in this section can be reverted through configuration options but some had breaking side effects like valueOf being renamed to safeValueOf for enums.
sealedClassesForEnumsMatching allows generating Kotlin enums for GraphQL enums.Apollo 3.x generates sealed classes for Kotlin enums. As paradoxical as it may seem, sealed classes a better representation of GraphQL enums because they allow to expose the rawValue of new enums that are not know at compile time. Sealed classes can also handle when exhaustivity just like Kotlin enums and are generally more flexible. Using them may change the calling code though so as a temporary migration helper, you can now fallback to enum like in 2.x by setting sealedClassesForEnumsMatching to an empty list instead of the default listOf(".*"):
apollo {
sealedClassesForEnumsMatching.set(emptyList())
}
One side effect of this change is that the generated MySealedClass.valueOf() has been renamed to MySealedClass.safeValueOf().
generateOptionalOperationVariables allows wrapping your variables in Optional<>.By default Apollo Android 3 skips the Optional<> wrapper for nullable variables. This simplifies the call site in the vast majority of cases where the variable is actually sent alongside the query.
There might be some rare occasions where you want to be able to omit a variable. For these cases, you can add an @optional directive:
# a query that allows omitting before and/or after for bi-directional pagination
query MyQuery($before: String @optional, $after: String @optional) {
items {
title
}
}
If you have a lot of those queries, or if you prefer the 2.x behaviour, you can now opt-out globally:
apollo {
generateOptionalOperationVariables.set(true)
}
codegenModels defaults to "operationBased"3.0.0-beta01 now defaults to "operationBased" models. "operationBased" models match your GraphQL operations 1:1 and skip the extra .fragment synthetic fields that are present in "compat" models. Because they are simpler to understand, generate and execute, they are now the default. You can revert to "compat" codegen with the codegenModels Gradle option:
apollo {
codegenModels.set(MODELS_COMPAT)
}
useVersion2Compat()For all these options, you can now fallback to the 2.x behaviour with useVersion2Compat(). This is a shorthand function that configures the above options to match the 2.x behaviour. useVersion2Compat is a helper to facilitate the migration and will be removed in a future update.
Following the with-er vs Builder vs DSL RFC, we decided to move the main APIs to Builders. Builders are widely accepted, battle proven APIs that play nicely with Java and will make it easier to maintain Apollo Android in the long run.
While this beta-01 release keeps the with-ers, they will be removed before Apollo Android 3 goes stable so now is a good time to update.
To build an ApolloClient:
// Replace
val apolloClient = ApolloClient("https://com.example/graphql")
.withNormalizedCache(normalizedCacheFactory)
// With
val apolloClient = ApolloClient.Builder()
.serverUrl("https://com.example/graphql")
.normalizedCache(normalizedCacheFactory)
.build()
To build a ApolloRequest:
// Replace
val apolloRequest = ApolloRequest(query)
.withFetchPolicy(FetchPolicy.CacheFirst)
// With
val apolloRequest = ApolloRequest.Builder(query)
.fetchPolicy(FetchPolicy.CacheFirst)
.build()
The WebSocket code has been revamped to support client-initiated ping-pong for graphql-ws as well as a better separation between common code and protocol specific code.
A side effect is that WebSocket protocols are now configured using a WsProtocol.Factory:
// Replace
val apolloClient = ApolloClient(
networkTransport = WebSocketNetworkTransport(
serverUrl = "http://localhost:9090/graphql",
protocol = GraphQLWsProtocol()
)
)
// With
val apolloClient = ApolloClient.Builder()
.networkTransport(
WebSocketNetworkTransport(
serverUrl = "http://localhost:9090/graphql",
protocolFactory = GraphQLWsProtocol.Factory()
)
)
.build()
Full Changelog: https://github.com/apollographql/apollo-android/compare/v3.0.0-alpha07...v3.0.0-beta01
Version 2.5.10 is a maintenance release with a few bugfixes, mutiny support and a new Gradle register${VariantName}ApolloOperations task to register your operations to the Apollo registry.
💜 Many thanks to @ProVir, @aoudiamoncef and @jgarrow for their contributions !💜
Version 2.5.10 adds support for the Mutiny reactive library.
Add the dependency:
// Mutiny support
implementation 'com.apollographql.apollo:apollo-mutiny-support:x.y.z'
And convert your ApolloCall to a Mutiny Uni:
// Create a query object
val query = EpisodeHeroNameQuery(episode = Episode.EMPIRE.toInput())
// Directly create Uni with Kotlin extension
val uni = apolloClient.mutinyQuery(query)
Read more in the documentation
register${VariantName}ApolloOperations (#3403)If you're using Apollo safelisting, you can now upload the transformed operations from Gradle directly. Add a registerOperations {} block to the apollo {} block:
apollo {
service("service") {
registerOperations {
// You can get your key from https://studio.apollographql.com/graph/$graph/settings
key.set(System.getenv("APOLLO_KEY"))
graph.set(System.getenv("APOLLO_GRAPH"))
// Use "current" by default or any other graph variant
graphVariant.set("current")
}
}
}
Then call ./gradlew registerMainServiceApolloOperations to register your operations to the registry. The operations will be registered including the added __typename fields that might be added during codegen.
Full Changelog: https://github.com/apollographql/apollo-android/compare/v2.5.9...v2.5.10
Version 3.0.0-alpha07 has new builtin Adapters for java.time, better custom scalar handling for multi module projects and multiple fixes for MPP and json parsers.
💜 Many thanks to @ProVir, @ychescale9 and @pauldavies83 for all the feedback and investigations !💜
Like there were adapters for kotlinx.datetime, you can now use java.time adapters from the apollo-adapters package:
com.apollographql.apollo3.adapter.JavaInstantAdaptercom.apollographql.apollo3.adapter.JavaLocalDateAdaptercom.apollographql.apollo3.adapter.JavaLocalDateTimeAdapterkotlinx.datetime AdaptersTo keep things symmetrical with the java.timeadapters, the kotlinx.datetime adapters are now named:
com.apollographql.apollo3.adapter.KotlinxInstantAdaptercom.apollographql.apollo3.adapter.KotlinxLocalDateAdaptercom.apollographql.apollo3.adapter.KotlinxLocalDateTimeAdapterLongAdapter package nameBecause LongAdapter is widely used and doesn't require any additional dependencies, it is now in the builtin apollo-api package
// Replace
com.apollographql.apollo3.adapter.LongAdapter
// With
com.apollographql.apollo3.api.LongAdapter
Hotfix release to fix Android Studio autocomplete for generated files (#3354)
3.0.0-alpha05 is an incremental update on top of alpha04 with a few important fixes. Many thanks to all the feedback, in particular from @rickclephas, @ProVir, @ychescale9 and @james on the Kotlinlang slack. Thank you 💜!
The Kotlin Native runtime was too strict in ensuring the Continuations were never frozen, which caused exceptions when used with coroutines-native-mt. This check has been removed.
To ease the transition from 2.x, clearNormalizedCache has been added as a deprecated function and will be removed for 3.1
Because only used types are generated in alpha04, we lost the ability to compute possible types in a typesafe way. This PR re-introduces this with an opt-it generateSchema Gradle property:
apollo {
generateSchema.set(true)
}
This will:
__Schema class that will hold a list of all composite typesThe __Schema class has a possibleTypes() function that can lookup possible types from the list of types:
assertEquals(
setOf(Cat.type, Dog.type, Crocodile.type),
__Schema.possibleTypes(Animal.type).toSet()
)
For multi-project builds, custom scalar were registered twice, leading to a validation error. This is now fixed.
3.0.0-alpha04 brings Java codegen and ApolloIdlingResource in Apollo Android 3. These were the final pieces that were not ported to Apollo Android 3 yet 🎉..
In addition, it brings some consistency improvements in the codegen/Gradle setup as well bump the max json stack size to 256 and other ergonomic improvements and fixes.
As we move towards a stable version, we'll have to settle for the current with-er API or Builders. Let us know what you think by letting a comment on the RFC.
Apollo Android 3 now generates Java models if the Kotlin plugin is not applied in your project. This is detected automatically and should work in the vast majority of cases. If you want to force Java codegen while still using the Kotlin plugin, you can set generateKotlinModels.set(false) in your Gradle scripts:
apollo {
// Generate Java classes regardless of whether the Kotlin plugin is applied
generateKotlinModels.set(false)
}
Java models work like Kotlin models and use the same runtime. With the exception of default parameters, they are compatible with Kotlin operationBased models so you can change the target language without having to update most of your code.
apollo-idling-resource is now available in Apollo Android 3. You can include it with the apollo-idling-resource artifact:
dependencies {
testImplementation("com.apollographql.apollo3:apollo-idling-resource:$version")
}
And create an ApolloClient that will update the IdlingResource:
val idlingResource = ApolloIdlingResource("test")
val apolloClient = ApolloClient("https://...")
.withIdlingResource(idlingResource)
valueOf for enumsMany thanks to @kubode for the contribution 💜
For GraphQL enums generated as sealed class, you can now call valueOf to parse a String to a given enum value (or Unknown__ if unknown):
Given the below enum:
enum Direction {
NORTH,
EAST,
SOUTH,
WEST
}
You can use:
assertEquals(Direction.NORTH, Direction.valueOf("NORTH"))
assertEquals(Direction.Unknown__("NORTH-WEST"), Direction.valueOf("NORTH-WEST"))
ApolloNetworkErrorMany thanks to @ProVir for the help getting this done 💜
When something wrong happens during a network request, the runtime will throw a ApolloNetworkError exception. You can now access the underlying platform error with ApolloNetworkError.platformCause:
// On iOS you can cast to NSError
try {
apolloClient.query(query)
} catch (e: ApolloNetworkError) {
when ((e.platformCause as NSError?)?.domain) {
NSURLErrorDomain -> // handle NSURLErrorDomain errors ...
}
}
// On Android/JVM, platformCause is the same Throwable as Cause:
try {
apolloClient.query(query)
} catch (e: ApolloNetworkError) {
when (e.cause) {
is UnknownHostException -> // handle UnknownHostException errors ...
}
}
Because the default of an empty package name creates issues with kapt, it is now mandatory to set the package name of generated models:
apollo {
// Use the same packageName for all generated models
packageName.set("com.example")
// Or use a package name derived from the file location
packageNamesFromFilePaths()
}
For consistency, and in order to support multi-modules scenarios where some types are only generated in some modules, custom scalars, object and interface types are now generated as top-level classes in the .type package name, like input objects and enums instead of being wrapped in a Types object. Each schema type has a static type: CompiledType property so you can access the type name in a type safe way.
// Replace
Types.Launch.name
// With
Launch.type.name
If you were using generated CustomScalarType instances to register your custom scalar adapters, these are moved to the top level as well:
// Replace
ApolloClient("https://").withCustomScalarAdapter(Types.GeoPoint, geoPointAdapter)
// With
ApolloClient("https://").withCustomScalarAdapter(GeoPoint.type, geoPointAdapter)
DefaultHttpRequestComposerParamsBecause DefaultHttpRequestComposerParams was setting multiple parameters at the same time (HTTP headers, method, etc..), setting one of them would overwrite a default set on the client. Instead of using DefaultHttpRequestComposerParams, set parameters individually:
apolloClient.withHttpHeader("name", "value")
apolloRequest.withHttpHeader("otherName", "otherValue")
valueOf to the enum types (#3328)3.0.0-alpha03 is a release with a bunch of bugfixes and documentation fixes.
The Kdoc for the current dev-3.x version is now available at: https://apollographql.github.io/apollo-android/kdoc/
Many thanks to @dchapelle for the work on WebSockets and @PHPirates and @omaksymov for the documentation fixes!
This version reworks the CacheResolver API to hopefully clarify its usage as well as allow more advanced use cases if needed.
ObjectIdGenerator and CacheResolver APIsThis version splits the CacheResolver API in two distinct parts:
ObjectIdGenerator.cacheKeyForObject
CacheResolver.resolveField
CacheKey for objects but it can also be any other data if needed. In that respect, it's closer to a resolver as might be found in apollo-serverPreviously, both methods were in CacheResolver even if under the hood, the code path were very different. By separating them, it makes it explicit and also makes it possible to only implement one of them.
Note: In general, prefer using @typePolicy and @fieldPolicy that provide a declarative/easier way to manage normalization and resolution.
ObjectIdGenerator is usually the most common one. It gives objects a unique id:
type Product {
uid: String!
name: String!
price: Float!
}
// An ObjectIdGenerator that uses the "uid" property if it exists
object UidObjectIdGenerator : ObjectIdGenerator {
override fun cacheKeyForObject(obj: Map<String, Any?>, context: ObjectIdGeneratorContext): CacheKey? {
val typename = obj["__typename"]?.toString()
val uid = obj["uid"]?.toString()
return if (typename != null && uid != null) {
CacheKey.from(typename, listOf(uid))
} else {
null
}
}
}
CacheResolver allows resolving a specific field from a query:
query GetProduct($uid: String!) {
product(uid: $uid) {
uid
name
price
}
}
object UidCacheResolver: CacheResolver {
override fun resolveField(field: CompiledField, variables: Executable.Variables, parent: Map<String, Any?>, parentId: String): Any? {
var type = field.type
if (type is CompiledNotNullType) {
type = type.ofType
}
if (type !is ObjectType) {
// This only works for concrete types
return MapCacheResolver.resolveField(field, variables, parent, parentId)
}
val uid = field.resolveArgument("uid", variables)?.toString()
if (uid != null) {
return CacheKey.from(type.name, listOf(uid))
}
// Always fallback to the default resolver
return MapCacheResolver.resolveField(field, variables, parent, parentId)
}
}
This version is the first alpha on the road to a 3.0.0 release!
Apollo Android 3 rewrites a lot of the internals to be Kotlin first and support a multiplatform cache. It also has performance improvements, new codegen options, support for multiple client directives and much more!
This document lists the most important changes. For more details, consult the preliminary docs and the migration guide.
This is a big release and the code is typically less mature than in the main branch. Please report any issue, we'll fix them urgently. You can also reach out in kotlinlang's #apollo-android slack channel for more general discussions.
This version is 100% written in Kotlin, generates Kotlin models by default and exposes Kotlin first APIs.
Using Kotlin default parameters, Builders are removed:
import com.apollographql.apollo3.ApolloClient
val apolloClient = ApolloClient("https://com.example/graphql")
Queries are suspend fun, Subscriptions are Flow<Response<D>>:
val response = apolloClient.query(MyQuery())
// do something with response
apolloClient.subscribe(MySubscription()).collect { response ->
// react to changes in your backend
}
Java codegen is not working but will be added in a future update. For details and updates, see this GitHub issue
This version unifies apollo-runtime and apollo-runtime-kotlin. You can now use apollo-runtime for both the JVM and iOS/MacOS:
kotlin {
sourceSets {
val commonMain by getting {
dependencies {
implementation("com.apollographql.apollo3:apollo-runtime:3.0.0-alpha01")
}
}
}
}
The normalized cache is multiplatform too and both apollo-normalized-cache (for memory cache) and apollo-normalized-cache-sqlite (for persistent cache) can be added to the commonMain sourceSet.
The In-Memory cache uses a custom LruCache that supports maxSize and weighter options. The SQLite cache uses SQLDelight to support both JVM and native targets.
val apolloClient = ApolloClient("https://com.example/graphql")
.withNormalizedCache(MemoryCacheFactory(maxSize = 1024 * 1024))
val apolloRequest = ApolloRequest(GetHeroQuery()).withFetchPolicy(FetchPolicy.CacheFirst)
val apolloResponse = apolloClient.query(apolloRequest)
Current feature matrix:
| JVM | iOS/MacOS | JS | |
|---|---|---|---|
| apollo-api (models) | ✅ | ✅ | ✅ |
| apollo-runtime (network, query batching, apq, ...) | ✅ | ✅ | 🚫 |
| apollo-normalized-cache | ✅ | ✅ | 🚫 |
| apollo-normalized-cache-sqlite | ✅ | ✅ | 🚫 |
| apollo-http-cache | ✅ | 🚫 | 🚫 |
SQLite batching batches SQL requests instead of executing them sequentially. This can speed up reading a complex query by a factor 2x+ (benchmarks). This is especially true for queries that contain lists:
{
"data": {
"launches": {
"launches": [
{
"id": "0",
"site": "CCAFS SLC 40"
},
...
{
"id": "99",
"site": "CCBGS 80"
}
]
}
}
}
Reading the above data from the cache would take 103 SQL queries with Apollo Android 2 (1 for the root, 1 for data, 1 for launches, 1 for each launch). Apollo Android 3 uses 4 SQL queries, executing all the launches at the same time.
When it's possible, the parsers create the models as they read bytes from the network. By amortizing parsing during IO, the latency is smaller leading to faster UIs. It's not always possible though. At the moment, the parsers fall back to buffering when fragments are encountered because fragments may contain merged fields that need to rewind in the json stream:
{
hero {
friend {
name
}
... on Droid {
# friend is a merged field which Apollo Android needs to read twice
friend {
id
}
}
}
}
A future version might be more granular and only fallback to buffering when merged fields are actually used.
The codegen has been rethought with the goal of supporting Fragments as Interfaces.
To say it turned out to be a complex feature would be a understatement. GraphQL is a very rich language and supporting all the edge cases that come with polymorphism, @include/@skip directives and more would not only be very difficult to implement but also generate very complex code (see 3144). While fragments as interfaces are not enabled by default, the new codegen allows to experiment with different options and features.
The codegen supports 3 modes:
compat (default) uses the same structure as 2.x.operationBased generates simpler models that map the GraphQL operation 1:1.responseBased generates more complex models that map the Sson response 1:1.responseBased models will generate fragments as interfaces and can always use streaming parsers. They do not support @include/@skip directives on fragments and will generate sensibly more complex code.
Read Codegen.md for more details about the different codegen modes.
To change the codegen mode, add this to your build.gradle[.kts]:
apollo {
codegenModels.set("responseBased") // or "operationBased", or "compat"
}
The codegen now generates a list of the different types in the schema.
You can use these to get the different __typename in a type-safe way:
val typename = Types.Human.name
// "Human"
or find the possible types of a given interface:
val possibleTypes = Types.possibleTypes(Types.Character)
// listOf(Types.Human, Types.Droid)
This version includes apollo-graphql-ast that can parse GraphQL documents into an AST. Use it to analyze/modify GraphQL files:
file.parseAsGQLDocument()
.definitions
.filterIsInstance<GQLOperationDefinition>
.forEach {
println("File $file.name contains operation '$it.name'")
}
@nonnull turns nullable GraphQL fields into non-null Kotlin properties. Use them if such a field being null is generally the result of a larger error that you want to catch in a central place (more in docs):
query GetHero {
# data.hero will be non-null
hero @nonnull {
name
}
}
Apollo Android distinguishes between:
null or notThe GraphQL spec makes non-nullable variables optional. A query like this:
query GetHero($id: String) {
hero(id: $id) {
name
}
}
will be generated with an optional id constructor parameter:
class GetHeroQuery(val id: Optional<String?> = Optional.Absent)
While this is correct, this is also cumbersome. If you added the id variable in the first place, there is a very high chance you want to use it. Apollo Android 3 makes variables non-optional by default (but possibly nullable):
class GetHeroQuery(val id: String?)
If for some reason, you need to be able to omit the variable, you can opt-in optional again:
# id will be an optional constructor parameter
query GetHero($id: String @optional) {
hero(id: $id) {
name
}
}
You can use @typePolicy to tell the runtime how to compute a cache key from object fields:
extend type Book @typePolicy(keyFields: "isbn")
The above will add isbn wherever a Book is queried and use "Book:$isbn" as a cache key.
Since this works at the schema level, you can either modify your source schema or add an extra extra.graphqls file next to it that will be parsed at the same time.
Symmetrically from @typePolicy, you can use @fieldPolicy to tell the runtime how to compute a cache key from a field and query variables.
Given this schema:
type Query {
book(isbn: String!): Book
}
you can tell the runtime to use the isbn argument as a cache key with:
extend type Query @fieldPolicy(forField: "book", keyArgs: "isbn")
This version includes an apollo-adapters artifact that includes Adapters for common custom scalar types:
kotlinx.datetime.Instant ISO8601 dateskotlinx.datetime.LocalDate ISO8601 datesjava.util.Date ISO8601 datesjava.lang.Longcom.apollographql.apollo3.BigDecimal class holding big decimal valuesThis version comes with builtin graphql-ws support in addition to the default graphql-transport-ws. You can use graphql-ws for queries and mutation in addition to subscriptions if your server supports it.
// Creates a client that will use WebSockets and `graphql-ws` for all queries/mutations/subscriptions
val apolloClient = ApolloClient(
networkTransport = WebSocketNetworkTransport(serverUrl = "wss://com.example/graphql", protocol = GraphQLWsProtocol())
)
A mini-release to include a fix for query batching (#3146) that didn't make it in time for 2.5.8.