Java runtime doc (#5119)

Author: BoD

docs/source/advanced/java.mdx

@@ -16,33 +16,61 @@ apollo {
 }
 ```
 
-## Build the client
+## The Java runtime
 
-This snippet demonstrates initializing an `ApolloClient` instance in Java:
+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-alpha.2")
+}
+```
+
+The Java runtime has a callbacks based API. This snippet demonstrates initializing and using an `ApolloClient` in Java:
 
 ```java
-import com.apollographql.apollo3.cache.normalized.NormalizedCache;
-import com.apollographql.apollo3.cache.http.HttpCache;
+import com.apollographql.apollo3.runtime.java.ApolloClient;
 // (...)
 
-ApolloClient.Builder builder = new ApolloClient.Builder()
+ApolloClient client = ApolloClient.Builder builder = new ApolloClient.Builder()
   .serverUrl("http://localhost:4000/graphql")
+  .build();
 
-// Optionally, set an http cache
-HttpCache.configureApolloClientBuilder(builder, cacheDirectory, cacheMaxSize);
+// 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.
 
-// Optionally, set a normalized cache
-NormalizedCache.configureApolloClientBuilder(
-  builder,
-  new MemoryCacheFactory(10 * 1024 * 1024, -1),
-  TypePolicyCacheKeyGenerator.INSTANCE,
-  FieldPolicyCacheResolver.INSTANCE,
-  false
-);
+### 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();
 
-ApolloClient client = builder.build();
 ```
 
-## Use RxJava extensions
+### RxJava extensions
 
-Apollo Kotlin has a coroutines / Flow-based API that isn't well suited to using with Java. To achieve a similar effect, you can use Apollo's [RxJava extensions](./rxjava/).
+If your project uses RxJava, you can use Apollo's [RxJava extensions](./rxjava/) with the Java runtime.

docs/source/advanced/rxjava.mdx

@@ -2,9 +2,23 @@
 title: RxJava support
 ---
 
-If you're using Apollo Kotlin in a [Java project](java) or a Kotlin project that uses RxJava, you can use Apollo's RxJava extensions.
+If you're using Apollo Kotlin in a [Java project](java) or Kotlin project that uses RxJava, you can use Apollo's RxJava extensions.
 
-To do so, add the `apollo-rx2-support` or `apollo-rx3-support` dependency to your project:
+To do so, add the `apollo-rx2-support-java` / `apollo-rx3-support-java` (Java) or `apollo-rx2-support` / `apollo-rx3-support` (Kotlin) dependency to your project:
+
+<MultiCodeBlock>
+
+```java title="build.gradle[.kts]"
+dependencies {
+  // ...
+
+  // For RxJava 2
+  implementation("com.apollographql.apollo3:apollo-rx2-support-java:4.0.0-alpha.2")
+
+  // For RxJava 3
+  implementation("com.apollographql.apollo3:apollo-rx3-support-java:4.0.0-alpha.2")
+}
+```
 
 ```kotlin title="build.gradle[.kts]"
 dependencies {
@@ -18,30 +32,35 @@ dependencies {
 }
 ```
 
+</MultiCodeBlock>
+
+
 ## Executing operations
 
-Use the `rxSingle` / `rxFlowable` extensions to execute GraphQL operations and get RxJava observables:
+In Java, Use the `Rx2Apollo` or `Rx3Apollo` classes to execute GraphQL operations and get RxJava observables.
+
+In Kotlin, use the `rxSingle()` / `rxFlowable()` extensions.
 
 <MultiCodeBlock>
 
 ```java
-import com.apollographql.apollo3.rx2.Rx2Apollo;
+import com.apollographql.apollo3.rx3.java.Rx3Apollo;
 
 // (...)
 
 // Query
 ApolloCall<MyQuery.Data> queryCall = client.query(new MyQuery());
-Single<ApolloResponse<MyQuery.Data>> queryResponse = Rx2Apollo.single(queryCall);
+Single<ApolloResponse<MyQuery.Data>> queryResponse = Rx3Apollo.single(queryCall);
 queryResponse.subscribe( /* ... */ );
 
 // Mutation
 ApolloCall<MyMutation.Data> mutationCall = client.mutation(new MyMutation("my-parameter"));
-Single<ApolloResponse<MyMutation.Data>> mutationResponse = Rx2Apollo.single(mutationCall);
+Single<ApolloResponse<MyMutation.Data>> mutationResponse = Rx3Apollo.single(mutationCall);
 mutationResponse.subscribe( /* ... */ );
 
 // Subscription
 ApolloCall<MySubscription.Data> subscriptionCall = client.subscription(new MySubscription());
-Flowable<ApolloResponse<MySubscription.Data>> subscriptionResponse = Rx2Apollo.flowable(subscriptionCall);
+Flowable<ApolloResponse<MySubscription.Data>> subscriptionResponse = Rx3Apollo.flowable(subscriptionCall);
 subscriptionResponse.subscribe( /* ... */ );
 ```