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 generate Java code instead:

build.gradle[.kts]

1
apollo {
2
  service("service") {
3
    generateKotlinModels.set(false)
4
  }
5
}

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:

build.gradle[.kts]

1
dependencies {
2
  // ...
3

4
  // Use apollo-runtime-java instead of apollo-runtime
5
  implementation("com.apollographql.apollo3:apollo-runtime-java:4.0.0-beta.7")
6
}

Note that the Java runtime currently doesn't support the HTTP or normalized caches.

The Java runtime has a callbacks based API. This snippet demonstrates initializing an ApolloClient and executing a query in Java:

1
import com.apollographql.apollo3.runtime.java.ApolloClient;
2
// (...)
3

4
// Create and configure an ApolloClient
5
ApolloClient client = ApolloClient.Builder builder = new ApolloClient.Builder()
6
  .serverUrl("https://example.com/graphql")
7
  .build();
8

9
// Call enqueue() to execute a query asynchronously
10
apolloClient.query(new MyQuery()).enqueue(response -> {
11
  if (response.data != null) {
12
    // Handle (potentially partial) data
13
    System.out.println(response.data);
14
  } else {
15
    // Something wrong happened
16
    if (response.exception != null) {
17
      // Handle non-GraphQL errors, e.g. network issues
18
      response.exception.printStackTrace();
19
    } else {
20
      // Handle GraphQL errors in response.errors
21
      System.out.println(response.getErrors().get(0));
22
    }
23
  }
24
});

Cancelling requests

euqueue returns an ApolloDisposable that can be used to cancel the request:

1
ApolloDisposable disposable = apolloClient.subscription(new MySubscription()).enqueue(response -> ...)
2
// ...
3
disposable.dispose();

Subscriptions

Please refer to the subscriptions documentation for more information about subscriptions in general, and the available protocols.

When executing subscriptions with the Java runtime, the callback passed to enqueue() can be called several times:

1
ApolloClient apolloClient = new ApolloClient.Builder()
2
  .serverUrl("https://example.com/graphql")
3
  // Configure a protocol factory
4
  .wsProtocolFactory(new ApolloWsProtocol.Factory())
5
  .build();
6

7
// Execute the subscription
8
ApolloDisposable disposable = apolloClient.subscription(new MySubscription()).enqueue(response -> {
9
  System.out.println(response.dataOrThrow());
10
});
11

12
// Observe the disposable to know when the subscription is terminated
13
disposable.addListener(() -> {
14
  // Will be called when an operation terminates (either successfully or due to an error)
15
});

Interceptors

Like the Kotlin runtime, the Java runtime supports interceptors.

HTTP interceptors (HttpInterceptor) can be used to add headers to requests (e.g. for authentication), log requests and responses, etc.
GraphQL interceptors (ApolloInterceptor) can be used to modify GraphQL requests and responses, implement retry logic, etc.

1
// An HTTP interceptor that adds a custom header to each request
2
HttpInterceptor httpInterceptor = (request, chain, callback) -> {
3
  request = request.newBuilder().addHeader("my-header", "true").build();
4
  chain.proceed(request, callback);
5
};
6

7
// A GraphQL interceptor that logs the name of each operation before executing it
8
ApolloInterceptor apolloInterceptor = new ApolloInterceptor() {
9
  @Override
10
  public <D extends Operation.Data> void intercept(@NotNull ApolloRequest<D> request, @NotNull ApolloInterceptorChain chain, @NotNull ApolloCallback<D> callback) {
11
    System.out.println("Executing operation: " + request.getOperation().name());
12
    chain.proceed(request, callback);
13
  }
14
};
15

16
// Configure the interceptors when building the ApolloClient
17
apolloClient = new ApolloClient.Builder()
18
  .serverUrl(...)
19
  .addHttpInterceptor(httpInterceptor)
20
  .addInterceptor(apolloInterceptor)
21
  .build();

If you already have implemented OkHttp interceptors, you can also use them by passing your OkHttpClient instance to the ApolloClient.Builder:

1
OkHttpClient okHttpClient = new OkHttpClient.Builder()
2
  .okHttpClient(myOkHttpClient)
3
  .build();

RxJava extensions

If your project uses RxJava, you can use Apollo's RxJava extensions with the Java runtime.

To do so, add the apollo-rx2-support-java or apollo-rx3-support-java dependency to your project:

build.gradle[.kts]

1
dependencies {
2
  // ...
3

4
  // For RxJava 2
5
  implementation("com.apollographql.apollo3:apollo-rx2-support-java:4.0.0-beta.7")
6

7
  // For RxJava 3
8
  implementation("com.apollographql.apollo3:apollo-rx3-support-java:4.0.0-beta.7")
9
}

Then use the Rx2Apollo or Rx3Apollo classes to execute GraphQL operations and get RxJava observables:

1
import com.apollographql.apollo3.rx3.java.Rx3Apollo;
2

3
// (...)
4

5
// Query
6
ApolloCall<MyQuery.Data> queryCall = client.query(new MyQuery());
7
Single<ApolloResponse<MyQuery.Data>> queryResponse = Rx3Apollo.single(queryCall);
8
queryResponse.subscribe( /* ... */ );
9

10
// Mutation
11
ApolloCall<MyMutation.Data> mutationCall = client.mutation(new MyMutation("my-parameter"));
12
Single<ApolloResponse<MyMutation.Data>> mutationResponse = Rx3Apollo.single(mutationCall);
13
mutationResponse.subscribe( /* ... */ );
14

15
// Subscription
16
ApolloCall<MySubscription.Data> subscriptionCall = client.subscription(new MySubscription());
17
Flowable<ApolloResponse<MySubscription.Data>> subscriptionResponse = Rx3Apollo.flowable(subscriptionCall);
18
subscriptionResponse.subscribe( /* ... */ );

Using aliases

Apollo AST