|
2 | 2 | title: Using Java |
3 | 3 | --- |
4 | 4 |
|
5 | | -This article describes how to use Apollo Kotlin in Java projects. |
6 | | - |
7 | | -## Use the Java codegen |
8 | | - |
9 | | -Apollo Kotlin generates Kotlin code by default, but you can configure it to generate Java code instead: |
10 | | - |
11 | | -```kotlin title="build.gradle[.kts]" |
12 | | -apollo { |
13 | | - service("service") { |
14 | | - generateKotlinModels.set(false) |
15 | | - } |
16 | | -} |
17 | | -``` |
18 | | - |
19 | | -## The Java runtime |
20 | | - |
21 | | -The default runtime for Apollo Kotlin, `apollo-runtime`, exposes a coroutines / Flow-based API that isn't well suited to be consumed from Java. |
22 | | -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: |
23 | | - |
24 | | -```kotlin title="build.gradle[.kts]" |
25 | | -dependencies { |
26 | | - // ... |
27 | | - |
28 | | - // Use apollo-runtime-java instead of apollo-runtime |
29 | | - implementation("com.apollographql.apollo3:apollo-runtime-java:4.0.0-beta.7") |
30 | | -} |
31 | | -``` |
32 | | -Note that the Java runtime currently doesn't support the HTTP or normalized caches. |
33 | | - |
34 | | -The Java runtime has a callbacks based API. This snippet demonstrates initializing an `ApolloClient` and executing a query in Java: |
35 | | - |
36 | | -```java |
37 | | -import com.apollographql.apollo3.runtime.java.ApolloClient; |
38 | | -// (...) |
39 | | - |
40 | | -// Create and configure an ApolloClient |
41 | | -ApolloClient client = ApolloClient.Builder builder = new ApolloClient.Builder() |
42 | | - .serverUrl("https://example.com/graphql") |
43 | | - .build(); |
44 | | - |
45 | | -// Call enqueue() to execute a query asynchronously |
46 | | -apolloClient.query(new MyQuery()).enqueue(response -> { |
47 | | - if (response.data != null) { |
48 | | - // Handle (potentially partial) data |
49 | | - System.out.println(response.data); |
50 | | - } else { |
51 | | - // Something wrong happened |
52 | | - if (response.exception != null) { |
53 | | - // Handle non-GraphQL errors, e.g. network issues |
54 | | - response.exception.printStackTrace(); |
55 | | - } else { |
56 | | - // Handle GraphQL errors in response.errors |
57 | | - System.out.println(response.getErrors().get(0)); |
58 | | - } |
59 | | - } |
60 | | -}); |
61 | | -``` |
62 | | - |
63 | | -### Cancelling requests |
64 | | - |
65 | | -`euqueue` returns an `ApolloDisposable` that can be used to cancel the request: |
66 | | - |
67 | | -```java |
68 | | -ApolloDisposable disposable = apolloClient.subscription(new MySubscription()).enqueue(response -> ...) |
69 | | -// ... |
70 | | -disposable.dispose(); |
71 | | - |
72 | | -``` |
73 | | - |
74 | | -### Subscriptions |
75 | | - |
76 | | -Please refer to the [subscriptions documentation](../essentials/subscriptions/) for more information about subscriptions in general, and the available protocols. |
77 | | - |
78 | | -When executing subscriptions with the Java runtime, the callback passed to `enqueue()` can be called several times: |
79 | | - |
80 | | -```java |
81 | | -ApolloClient apolloClient = new ApolloClient.Builder() |
82 | | - .serverUrl("https://example.com/graphql") |
83 | | - // Configure a protocol factory |
84 | | - .wsProtocolFactory(new ApolloWsProtocol.Factory()) |
85 | | - .build(); |
86 | | - |
87 | | -// Execute the subscription |
88 | | -ApolloDisposable disposable = apolloClient.subscription(new MySubscription()).enqueue(response -> { |
89 | | - System.out.println(response.dataOrThrow()); |
90 | | -}); |
91 | | - |
92 | | -// Observe the disposable to know when the subscription is terminated |
93 | | -disposable.addListener(() -> { |
94 | | - // Will be called when an operation terminates (either successfully or due to an error) |
95 | | -}); |
96 | | - |
97 | | -``` |
98 | | -### Interceptors |
99 | | - |
100 | | -[Like the Kotlin runtime](./interceptors-http), the Java runtime supports interceptors. |
101 | | - |
102 | | -- HTTP interceptors (`HttpInterceptor`) can be used to add headers to requests (e.g. for authentication), log requests and responses, etc. |
103 | | -- GraphQL interceptors (`ApolloInterceptor`) can be used to modify GraphQL requests and responses, implement retry logic, etc. |
104 | | - |
105 | | -```java |
106 | | -// An HTTP interceptor that adds a custom header to each request |
107 | | -HttpInterceptor httpInterceptor = (request, chain, callback) -> { |
108 | | - request = request.newBuilder().addHeader("my-header", "true").build(); |
109 | | - chain.proceed(request, callback); |
110 | | -}; |
111 | | - |
112 | | -// A GraphQL interceptor that logs the name of each operation before executing it |
113 | | -ApolloInterceptor apolloInterceptor = new ApolloInterceptor() { |
114 | | - @Override |
115 | | - public <D extends Operation.Data> void intercept(@NotNull ApolloRequest<D> request, @NotNull ApolloInterceptorChain chain, @NotNull ApolloCallback<D> callback) { |
116 | | - System.out.println("Executing operation: " + request.getOperation().name()); |
117 | | - chain.proceed(request, callback); |
118 | | - } |
119 | | -}; |
120 | | - |
121 | | -// Configure the interceptors when building the ApolloClient |
122 | | -apolloClient = new ApolloClient.Builder() |
123 | | - .serverUrl(...) |
124 | | - .addHttpInterceptor(httpInterceptor) |
125 | | - .addInterceptor(apolloInterceptor) |
126 | | - .build(); |
127 | | -``` |
128 | | - |
129 | | -If you already have implemented OkHttp interceptors, you can also use them by passing your `OkHttpClient` instance to the `ApolloClient.Builder`: |
130 | | - |
131 | | -```java |
132 | | -OkHttpClient okHttpClient = new OkHttpClient.Builder() |
133 | | - .okHttpClient(myOkHttpClient) |
134 | | - .build(); |
135 | | -``` |
136 | | - |
137 | | -## RxJava extensions |
138 | | - |
139 | | -If your project uses RxJava, you can use Apollo's RxJava extensions with the Java runtime. |
140 | | - |
141 | | -To do so, add the `apollo-rx2-support-java` or `apollo-rx3-support-java` dependency to your project: |
142 | | - |
143 | | -```java title="build.gradle[.kts]" |
144 | | -dependencies { |
145 | | - // ... |
146 | | - |
147 | | - // For RxJava 2 |
148 | | - implementation("com.apollographql.apollo3:apollo-rx2-support-java:4.0.0-beta.7") |
149 | | - |
150 | | - // For RxJava 3 |
151 | | - implementation("com.apollographql.apollo3:apollo-rx3-support-java:4.0.0-beta.7") |
152 | | -} |
153 | | -``` |
154 | | -Then use the `Rx2Apollo` or `Rx3Apollo` classes to execute GraphQL operations and get RxJava observables: |
155 | | - |
156 | | -```java |
157 | | -import com.apollographql.apollo3.rx3.java.Rx3Apollo; |
158 | | - |
159 | | -// (...) |
160 | | - |
161 | | -// Query |
162 | | -ApolloCall<MyQuery.Data> queryCall = client.query(new MyQuery()); |
163 | | -Single<ApolloResponse<MyQuery.Data>> queryResponse = Rx3Apollo.single(queryCall); |
164 | | -queryResponse.subscribe( /* ... */ ); |
165 | | - |
166 | | -// Mutation |
167 | | -ApolloCall<MyMutation.Data> mutationCall = client.mutation(new MyMutation("my-parameter")); |
168 | | -Single<ApolloResponse<MyMutation.Data>> mutationResponse = Rx3Apollo.single(mutationCall); |
169 | | -mutationResponse.subscribe( /* ... */ ); |
170 | | - |
171 | | -// Subscription |
172 | | -ApolloCall<MySubscription.Data> subscriptionCall = client.subscription(new MySubscription()); |
173 | | -Flowable<ApolloResponse<MySubscription.Data>> subscriptionResponse = Rx3Apollo.flowable(subscriptionCall); |
174 | | -subscriptionResponse.subscribe( /* ... */ ); |
175 | | -``` |
| 5 | +To use Apollo Kotlin in Java projects, please refer to the dedicated Java Support repository [documentation](https://apollographql.github.io/apollo-kotlin-java-support/). |
0 commit comments