Skip to content

Commit 6ddf8fc

Browse files
rashtaoSimran-B
rashtao
and
Simran-B
authored
[DE-714] Java Driver: asynchronous API (#330)
* Java Driver: asynchronous API * Review --------- Co-authored-by: Simran Spiller <[email protected]>
1 parent 85aebcb commit 6ddf8fc

File tree

12 files changed

+297
-48
lines changed

12 files changed

+297
-48
lines changed

‎site/content/3.10/develop/drivers/java/_index.md‎

Lines changed: 48 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ Version 6 is still supported and maintained, but not actively developed anymore.
1818
Upgrading to version 7 is recommended.
1919

2020
The API changes between version 6 and 7 are documented in
21-
[Changes in version 7.0](reference-version-7/changes-in-version-7.md).
21+
[Changes in version 7](reference-version-7/changes-in-version-7.md).
2222

2323
Both versions are compatible with all supported stable versions of ArangoDB server, see
2424
[Product Support End-of-life Announcements](https://www.arangodb.com/eol-notice).
@@ -131,13 +131,54 @@ function `com.arangodb.util.UnicodeUtils.isNormalized(String): boolean`:
131131
boolean isNormalized = UnicodeUtils.isNormalized("𝔸𝕣𝕒𝕟𝕘𝕠𝔻𝔹");
132132
```
133133

134-
### Async API
134+
## Async API
135+
136+
From version 7.2 onward, the driver provides a new asynchronous API.
137+
Unlike in version 6, the asynchronous API is based on the same underlying driver
138+
instance and therefore supports all the communication protocols and configurations
139+
of the synchronous API. The asynchronous API is accessible via `ArangoDB#async()`,
140+
for example:
141+
142+
```java
143+
ArangoDB adb = new ArangoDB.Builder()
144+
// ...
145+
.build();
146+
ArangoDBAsync adbAsync = adb.async();
147+
CompletableFuture<ArangoDBVersion> version = adbAsync.getVersion();
148+
// ...
149+
```
135150

136-
The asynchronous API (formerly under the package `com.arangodb.async`) has been
137-
removed from version 7.0. This has been done because the asynchronous API needs
138-
a substantial refactoring, i.e. supporting the HTTP protocol, fixing the async
139-
client to not block when consuming a cursor, and a better alignment with the
140-
synchronous API. It will be reworked and re-added in a future version 7.x.
151+
Under the hood, both synchronous and asynchronous API use the same internal
152+
communication layer, which has been reworked and re-implemented in an
153+
asynchronous way. The synchronous API blocks and waits for the result, while the
154+
asynchronous one returns a `CompletableFuture<>` representing the pending
155+
operation being performed.
156+
Each asynchronous API method is equivalent to the corresponding synchronous
157+
variant, except for the Cursor API.
158+
159+
### Async Cursor API
160+
161+
The Cursor API (`ArangoCursor` and `ArangoCursorAsync`) is intrinsically different,
162+
because the synchronous Cursor API is based on Java's `java.util.Iterator`, which
163+
is an interface only suitable for synchronous scenarios.
164+
On the other side, the asynchronous Cursor API provides a method
165+
`com.arangodb.ArangoCursorAsync#nextBatch()`, which returns a
166+
`CompletableFuture<ArangoCursorAsync<T>>` and can be used to consume the next
167+
batch of the cursor, for example:
168+
169+
```java
170+
CompletableFuture<ArangoCursorAsync<Integer>> future1 = adbAsync.db()
171+
.query("FOR i IN i..10000", Integer.class);
172+
CompletableFuture<ArangoCursorAsync<Integer>> future2 = future1
173+
.thenCompose(c -> {
174+
List<Integer> batch = c.getResult();
175+
// ...
176+
// consume batch
177+
// ...
178+
return c.nextBatch();
179+
});
180+
// ...
181+
```
141182

142183
## See Also
143184

‎site/content/3.10/develop/drivers/java/reference-version-7/_index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,4 @@ archetype: chapter
88
---
99
- [Driver Setup](driver-setup.md)
1010
- [Serialization](serialization.md)
11-
- [API changes in version 7.0](changes-in-version-7.md)
11+
- [API changes in version 7](changes-in-version-7.md)

‎site/content/3.10/develop/drivers/java/reference-version-7/changes-in-version-7.md‎

Lines changed: 49 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
---
2-
title: Changes in version 7.0
2+
title: Changes in version 7
33
menuTitle: Changes in version 7
44
weight: 15
55
description: >-
6-
Changes in ArangoDB Java Driver version 7.0
6+
Changes in ArangoDB Java Driver version 7
77
archetype: default
88
---
99
## Maven Setup
@@ -312,13 +312,54 @@ Support for custom initialization of cursors
312312
(`ArangoDB._setCursorInitializer(ArangoCursorInitializer cursorInitializer)`)
313313
has been removed.
314314

315-
### Async API
315+
## Async API
316316

317-
The asynchronous API (formerly under the package `com.arangodb.async`) has been
318-
removed from version 7.0. This has been done because the asynchronous API needs
319-
a substantial refactoring, i.e. supporting the HTTP protocol, fixing the async
320-
client to not block when consuming a cursor, and a better alignment with the
321-
synchronous API. It will be reworked and re-added in a future version 7.x.
317+
From version 7.2 onward, the driver provides a new asynchronous API.
318+
Unlike in version 6, the asynchronous API is based on the same underlying driver
319+
instance and therefore supports all the communication protocols and configurations
320+
of the synchronous API. The asynchronous API is accessible via `ArangoDB#async()`,
321+
for example:
322+
323+
```java
324+
ArangoDB adb = new ArangoDB.Builder()
325+
// ...
326+
.build();
327+
ArangoDBAsync adbAsync = adb.async();
328+
CompletableFuture<ArangoDBVersion> version = adbAsync.getVersion();
329+
// ...
330+
```
331+
332+
Under the hood, both synchronous and asynchronous API use the same internal
333+
communication layer, which has been reworked and re-implemented in an
334+
asynchronous way. The synchronous API blocks and waits for the result, while the
335+
asynchronous one returns a `CompletableFuture<>` representing the pending
336+
operation being performed.
337+
Each asynchronous API method is equivalent to the corresponding synchronous
338+
variant, except for the Cursor API.
339+
340+
### Async Cursor API
341+
342+
The Cursor API (`ArangoCursor` and `ArangoCursorAsync`) is intrinsically different,
343+
because the synchronous Cursor API is based on Java's `java.util.Iterator`, which
344+
is an interface only suitable for synchronous scenarios.
345+
On the other side, the asynchronous Cursor API provides a method
346+
`com.arangodb.ArangoCursorAsync#nextBatch()`, which returns a
347+
`CompletableFuture<ArangoCursorAsync<T>>` and can be used to consume the next
348+
batch of the cursor, for example:
349+
350+
```java
351+
CompletableFuture<ArangoCursorAsync<Integer>> future1 = adbAsync.db()
352+
.query("FOR i IN i..10000", Integer.class);
353+
CompletableFuture<ArangoCursorAsync<Integer>> future2 = future1
354+
.thenCompose(c -> {
355+
List<Integer> batch = c.getResult();
356+
// ...
357+
// consume batch
358+
// ...
359+
return c.nextBatch();
360+
});
361+
// ...
362+
```
322363

323364
## API methods changes
324365

‎site/content/3.10/develop/drivers/java/reference-version-7/driver-setup.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,7 @@ Here are examples to integrate configuration properties from different sources:
9090
- `loadBalancingStrategy(LoadBalancingStrategy)`: load balancing strategy, possible values are: `NONE`, `ROUND_ROBIN`, `ONE_RANDOM`, (default: `NONE`)
9191
- `responseQueueTimeSamples(Integer)`: amount of samples kept for queue time metrics, (default: `10`)
9292
- `serde(ArangoSerde)`: serde to serialize and deserialize user-data
93+
- `asyncExecutor(Executor)`: downstream `java.util.concurrent.Executor` that will be used to consume the responses of the async API
9394

9495
### Config File Properties
9596

‎site/content/3.11/develop/drivers/java/_index.md‎

Lines changed: 48 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ Version 6 is still supported and maintained, but not actively developed anymore.
1818
Upgrading to version 7 is recommended.
1919

2020
The API changes between version 6 and 7 are documented in
21-
[Changes in version 7.0](reference-version-7/changes-in-version-7.md).
21+
[Changes in version 7](reference-version-7/changes-in-version-7.md).
2222

2323
Both versions are compatible with all supported stable versions of ArangoDB server, see
2424
[Product Support End-of-life Announcements](https://www.arangodb.com/eol-notice).
@@ -131,13 +131,54 @@ function `com.arangodb.util.UnicodeUtils.isNormalized(String): boolean`:
131131
boolean isNormalized = UnicodeUtils.isNormalized("𝔸𝕣𝕒𝕟𝕘𝕠𝔻𝔹");
132132
```
133133

134-
### Async API
134+
## Async API
135+
136+
From version 7.2 onward, the driver provides a new asynchronous API.
137+
Unlike in version 6, the asynchronous API is based on the same underlying driver
138+
instance and therefore supports all the communication protocols and configurations
139+
of the synchronous API. The asynchronous API is accessible via `ArangoDB#async()`,
140+
for example:
141+
142+
```java
143+
ArangoDB adb = new ArangoDB.Builder()
144+
// ...
145+
.build();
146+
ArangoDBAsync adbAsync = adb.async();
147+
CompletableFuture<ArangoDBVersion> version = adbAsync.getVersion();
148+
// ...
149+
```
135150

136-
The asynchronous API (formerly under the package `com.arangodb.async`) has been
137-
removed from version 7.0. This has been done because the asynchronous API needs
138-
a substantial refactoring, i.e. supporting the HTTP protocol, fixing the async
139-
client to not block when consuming a cursor, and a better alignment with the
140-
synchronous API. It will be reworked and re-added in a future version 7.x.
151+
Under the hood, both synchronous and asynchronous API use the same internal
152+
communication layer, which has been reworked and re-implemented in an
153+
asynchronous way. The synchronous API blocks and waits for the result, while the
154+
asynchronous one returns a `CompletableFuture<>` representing the pending
155+
operation being performed.
156+
Each asynchronous API method is equivalent to the corresponding synchronous
157+
variant, except for the Cursor API.
158+
159+
### Async Cursor API
160+
161+
The Cursor API (`ArangoCursor` and `ArangoCursorAsync`) is intrinsically different,
162+
because the synchronous Cursor API is based on Java's `java.util.Iterator`, which
163+
is an interface only suitable for synchronous scenarios.
164+
On the other side, the asynchronous Cursor API provides a method
165+
`com.arangodb.ArangoCursorAsync#nextBatch()`, which returns a
166+
`CompletableFuture<ArangoCursorAsync<T>>` and can be used to consume the next
167+
batch of the cursor, for example:
168+
169+
```java
170+
CompletableFuture<ArangoCursorAsync<Integer>> future1 = adbAsync.db()
171+
.query("FOR i IN i..10000", Integer.class);
172+
CompletableFuture<ArangoCursorAsync<Integer>> future2 = future1
173+
.thenCompose(c -> {
174+
List<Integer> batch = c.getResult();
175+
// ...
176+
// consume batch
177+
// ...
178+
return c.nextBatch();
179+
});
180+
// ...
181+
```
141182

142183
## See Also
143184

‎site/content/3.11/develop/drivers/java/reference-version-7/_index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,4 @@ archetype: chapter
88
---
99
- [Driver Setup](driver-setup.md)
1010
- [Serialization](serialization.md)
11-
- [API changes in version 7.0](changes-in-version-7.md)
11+
- [API changes in version 7](changes-in-version-7.md)

‎site/content/3.11/develop/drivers/java/reference-version-7/changes-in-version-7.md‎

Lines changed: 49 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
---
2-
title: Changes in version 7.0
2+
title: Changes in version 7
33
menuTitle: Changes in version 7
44
weight: 15
55
description: >-
6-
Changes in ArangoDB Java Driver version 7.0
6+
Changes in ArangoDB Java Driver version 7
77
archetype: default
88
---
99
## Maven Setup
@@ -312,13 +312,54 @@ Support for custom initialization of cursors
312312
(`ArangoDB._setCursorInitializer(ArangoCursorInitializer cursorInitializer)`)
313313
has been removed.
314314

315-
### Async API
315+
## Async API
316316

317-
The asynchronous API (formerly under the package `com.arangodb.async`) has been
318-
removed from version 7.0. This has been done because the asynchronous API needs
319-
a substantial refactoring, i.e. supporting the HTTP protocol, fixing the async
320-
client to not block when consuming a cursor, and a better alignment with the
321-
synchronous API. It will be reworked and re-added in a future version 7.x.
317+
From version 7.2 onward, the driver provides a new asynchronous API.
318+
Unlike in version 6, the asynchronous API is based on the same underlying driver
319+
instance and therefore supports all the communication protocols and configurations
320+
of the synchronous API. The asynchronous API is accessible via `ArangoDB#async()`,
321+
for example:
322+
323+
```java
324+
ArangoDB adb = new ArangoDB.Builder()
325+
// ...
326+
.build();
327+
ArangoDBAsync adbAsync = adb.async();
328+
CompletableFuture<ArangoDBVersion> version = adbAsync.getVersion();
329+
// ...
330+
```
331+
332+
Under the hood, both synchronous and asynchronous API use the same internal
333+
communication layer, which has been reworked and re-implemented in an
334+
asynchronous way. The synchronous API blocks and waits for the result, while the
335+
asynchronous one returns a `CompletableFuture<>` representing the pending
336+
operation being performed.
337+
Each asynchronous API method is equivalent to the corresponding synchronous
338+
variant, except for the Cursor API.
339+
340+
### Async Cursor API
341+
342+
The Cursor API (`ArangoCursor` and `ArangoCursorAsync`) is intrinsically different,
343+
because the synchronous Cursor API is based on Java's `java.util.Iterator`, which
344+
is an interface only suitable for synchronous scenarios.
345+
On the other side, the asynchronous Cursor API provides a method
346+
`com.arangodb.ArangoCursorAsync#nextBatch()`, which returns a
347+
`CompletableFuture<ArangoCursorAsync<T>>` and can be used to consume the next
348+
batch of the cursor, for example:
349+
350+
```java
351+
CompletableFuture<ArangoCursorAsync<Integer>> future1 = adbAsync.db()
352+
.query("FOR i IN i..10000", Integer.class);
353+
CompletableFuture<ArangoCursorAsync<Integer>> future2 = future1
354+
.thenCompose(c -> {
355+
List<Integer> batch = c.getResult();
356+
// ...
357+
// consume batch
358+
// ...
359+
return c.nextBatch();
360+
});
361+
// ...
362+
```
322363

323364
## API methods changes
324365

‎site/content/3.11/develop/drivers/java/reference-version-7/driver-setup.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,7 @@ Here are examples to integrate configuration properties from different sources:
9090
- `loadBalancingStrategy(LoadBalancingStrategy)`: load balancing strategy, possible values are: `NONE`, `ROUND_ROBIN`, `ONE_RANDOM`, (default: `NONE`)
9191
- `responseQueueTimeSamples(Integer)`: amount of samples kept for queue time metrics, (default: `10`)
9292
- `serde(ArangoSerde)`: serde to serialize and deserialize user-data
93+
- `asyncExecutor(Executor)`: downstream `java.util.concurrent.Executor` that will be used to consume the responses of the async API
9394

9495
### Config File Properties
9596

‎site/content/3.12/develop/drivers/java/_index.md‎

Lines changed: 48 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ Version 6 is still supported and maintained, but not actively developed anymore.
1818
Upgrading to version 7 is recommended.
1919

2020
The API changes between version 6 and 7 are documented in
21-
[Changes in version 7.0](reference-version-7/changes-in-version-7.md).
21+
[Changes in version 7](reference-version-7/changes-in-version-7.md).
2222

2323
Both versions are compatible with all supported stable versions of ArangoDB server, see
2424
[Product Support End-of-life Announcements](https://www.arangodb.com/eol-notice).
@@ -131,13 +131,54 @@ function `com.arangodb.util.UnicodeUtils.isNormalized(String): boolean`:
131131
boolean isNormalized = UnicodeUtils.isNormalized("𝔸𝕣𝕒𝕟𝕘𝕠𝔻𝔹");
132132
```
133133

134-
### Async API
134+
## Async API
135+
136+
From version 7.2 onward, the driver provides a new asynchronous API.
137+
Unlike in version 6, the asynchronous API is based on the same underlying driver
138+
instance and therefore supports all the communication protocols and configurations
139+
of the synchronous API. The asynchronous API is accessible via `ArangoDB#async()`,
140+
for example:
141+
142+
```java
143+
ArangoDB adb = new ArangoDB.Builder()
144+
// ...
145+
.build();
146+
ArangoDBAsync adbAsync = adb.async();
147+
CompletableFuture<ArangoDBVersion> version = adbAsync.getVersion();
148+
// ...
149+
```
135150

136-
The asynchronous API (formerly under the package `com.arangodb.async`) has been
137-
removed from version 7.0. This has been done because the asynchronous API needs
138-
a substantial refactoring, i.e. supporting the HTTP protocol, fixing the async
139-
client to not block when consuming a cursor, and a better alignment with the
140-
synchronous API. It will be reworked and re-added in a future version 7.x.
151+
Under the hood, both synchronous and asynchronous API use the same internal
152+
communication layer, which has been reworked and re-implemented in an
153+
asynchronous way. The synchronous API blocks and waits for the result, while the
154+
asynchronous one returns a `CompletableFuture<>` representing the pending
155+
operation being performed.
156+
Each asynchronous API method is equivalent to the corresponding synchronous
157+
variant, except for the Cursor API.
158+
159+
### Async Cursor API
160+
161+
The Cursor API (`ArangoCursor` and `ArangoCursorAsync`) is intrinsically different,
162+
because the synchronous Cursor API is based on Java's `java.util.Iterator`, which
163+
is an interface only suitable for synchronous scenarios.
164+
On the other side, the asynchronous Cursor API provides a method
165+
`com.arangodb.ArangoCursorAsync#nextBatch()`, which returns a
166+
`CompletableFuture<ArangoCursorAsync<T>>` and can be used to consume the next
167+
batch of the cursor, for example:
168+
169+
```java
170+
CompletableFuture<ArangoCursorAsync<Integer>> future1 = adbAsync.db()
171+
.query("FOR i IN i..10000", Integer.class);
172+
CompletableFuture<ArangoCursorAsync<Integer>> future2 = future1
173+
.thenCompose(c -> {
174+
List<Integer> batch = c.getResult();
175+
// ...
176+
// consume batch
177+
// ...
178+
return c.nextBatch();
179+
});
180+
// ...
181+
```
141182

142183
## See Also
143184

‎site/content/3.12/develop/drivers/java/reference-version-7/_index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,4 @@ archetype: chapter
88
---
99
- [Driver Setup](driver-setup.md)
1010
- [Serialization](serialization.md)
11-
- [API changes in version 7.0](changes-in-version-7.md)
11+
- [API changes in version 7](changes-in-version-7.md)

0 commit comments

Comments
 (0)