From 9726c26fb29cba665c956cb9936074158956f4b7 Mon Sep 17 00:00:00 2001 From: Michele Rastelli Date: Thu, 23 Nov 2023 11:59:40 +0100 Subject: [PATCH 1/2] Java Driver: data definitions classes serialization disclaimer --- .../3.10/develop/drivers/java/_index.md | 44 ++++++++++++------- .../3.11/develop/drivers/java/_index.md | 44 ++++++++++++------- .../3.12/develop/drivers/java/_index.md | 10 +++++ 3 files changed, 64 insertions(+), 34 deletions(-) diff --git a/site/content/3.10/develop/drivers/java/_index.md b/site/content/3.10/develop/drivers/java/_index.md index 1522ff36c3..ce9ae57eee 100644 --- a/site/content/3.10/develop/drivers/java/_index.md +++ b/site/content/3.10/develop/drivers/java/_index.md @@ -49,11 +49,11 @@ To add the driver to your project with Gradle, add the following code to your ```groovy repositories { - mavenCentral() + mavenCentral() } dependencies { - implementation 'com.arangodb:arangodb-java-driver:7.x.x' + implementation 'com.arangodb:arangodb-java-driver:7.x.x' } ``` @@ -143,17 +143,17 @@ for example: ```java ArangoDB adb = new ArangoDB.Builder() - // ... - .build(); -ArangoDBAsync adbAsync = adb.async(); -CompletableFuture version = adbAsync.getVersion(); + // ... + .build(); + ArangoDBAsync adbAsync = adb.async(); + CompletableFuture version = adbAsync.getVersion(); // ... ``` Under the hood, both synchronous and asynchronous API use the same internal communication layer, which has been reworked and re-implemented in an asynchronous way. The synchronous API blocks and waits for the result, while the -asynchronous one returns a `CompletableFuture<>` representing the pending +asynchronous one returns a `CompletableFuture<>` representing the pending operation being performed. Each asynchronous API method is equivalent to the corresponding synchronous variant, except for the Cursor API. @@ -161,23 +161,33 @@ variant, except for the Cursor API. ### Async Cursor API The Cursor API (`ArangoCursor` and `ArangoCursorAsync`) is intrinsically different, -because the synchronous Cursor API is based on Java's `java.util.Iterator`, which +because the synchronous Cursor API is based on Java's `java.util.Iterator`, which is an interface only suitable for synchronous scenarios. -On the other side, the asynchronous Cursor API provides a method -`com.arangodb.ArangoCursorAsync#nextBatch()`, which returns a -`CompletableFuture>` and can be used to consume the next +On the other side, the asynchronous Cursor API provides a method +`com.arangodb.ArangoCursorAsync#nextBatch()`, which returns a +`CompletableFuture>` and can be used to consume the next batch of the cursor, for example: ```java CompletableFuture> future1 = adbAsync.db() .query("FOR i IN i..10000", Integer.class); -CompletableFuture> future2 = future1 + CompletableFuture> future2 = future1 .thenCompose(c -> { - List batch = c.getResult(); - // ... - // consume batch - // ... - return c.nextBatch(); + List batch = c.getResult(); + // ... + // consume batch + // ... + return c.nextBatch(); }); // ... ``` + +## Data Definitions Classes + +Classes used to exchange data definitions, in particular classes in packages +`com.arangodb.entity.**` and `com.arangodb.model.**`, are meant to be serialized +and deserialized internally by the driver. + +The behavior to serialize and deserialize these classes is considered an internal +implementation detail and as such it might change without prior notice, while +keeping API compatibility with regard to public members of these classes. diff --git a/site/content/3.11/develop/drivers/java/_index.md b/site/content/3.11/develop/drivers/java/_index.md index 1522ff36c3..ce9ae57eee 100644 --- a/site/content/3.11/develop/drivers/java/_index.md +++ b/site/content/3.11/develop/drivers/java/_index.md @@ -49,11 +49,11 @@ To add the driver to your project with Gradle, add the following code to your ```groovy repositories { - mavenCentral() + mavenCentral() } dependencies { - implementation 'com.arangodb:arangodb-java-driver:7.x.x' + implementation 'com.arangodb:arangodb-java-driver:7.x.x' } ``` @@ -143,17 +143,17 @@ for example: ```java ArangoDB adb = new ArangoDB.Builder() - // ... - .build(); -ArangoDBAsync adbAsync = adb.async(); -CompletableFuture version = adbAsync.getVersion(); + // ... + .build(); + ArangoDBAsync adbAsync = adb.async(); + CompletableFuture version = adbAsync.getVersion(); // ... ``` Under the hood, both synchronous and asynchronous API use the same internal communication layer, which has been reworked and re-implemented in an asynchronous way. The synchronous API blocks and waits for the result, while the -asynchronous one returns a `CompletableFuture<>` representing the pending +asynchronous one returns a `CompletableFuture<>` representing the pending operation being performed. Each asynchronous API method is equivalent to the corresponding synchronous variant, except for the Cursor API. @@ -161,23 +161,33 @@ variant, except for the Cursor API. ### Async Cursor API The Cursor API (`ArangoCursor` and `ArangoCursorAsync`) is intrinsically different, -because the synchronous Cursor API is based on Java's `java.util.Iterator`, which +because the synchronous Cursor API is based on Java's `java.util.Iterator`, which is an interface only suitable for synchronous scenarios. -On the other side, the asynchronous Cursor API provides a method -`com.arangodb.ArangoCursorAsync#nextBatch()`, which returns a -`CompletableFuture>` and can be used to consume the next +On the other side, the asynchronous Cursor API provides a method +`com.arangodb.ArangoCursorAsync#nextBatch()`, which returns a +`CompletableFuture>` and can be used to consume the next batch of the cursor, for example: ```java CompletableFuture> future1 = adbAsync.db() .query("FOR i IN i..10000", Integer.class); -CompletableFuture> future2 = future1 + CompletableFuture> future2 = future1 .thenCompose(c -> { - List batch = c.getResult(); - // ... - // consume batch - // ... - return c.nextBatch(); + List batch = c.getResult(); + // ... + // consume batch + // ... + return c.nextBatch(); }); // ... ``` + +## Data Definitions Classes + +Classes used to exchange data definitions, in particular classes in packages +`com.arangodb.entity.**` and `com.arangodb.model.**`, are meant to be serialized +and deserialized internally by the driver. + +The behavior to serialize and deserialize these classes is considered an internal +implementation detail and as such it might change without prior notice, while +keeping API compatibility with regard to public members of these classes. diff --git a/site/content/3.12/develop/drivers/java/_index.md b/site/content/3.12/develop/drivers/java/_index.md index 1522ff36c3..9c8f140622 100644 --- a/site/content/3.12/develop/drivers/java/_index.md +++ b/site/content/3.12/develop/drivers/java/_index.md @@ -181,3 +181,13 @@ CompletableFuture> future2 = future1 }); // ... ``` + +## Data Definitions Classes + +Classes used to exchange data definitions, in particular classes in packages +`com.arangodb.entity.**` and `com.arangodb.model.**`, are meant to be serialized +and deserialized internally by the driver. + +The behavior to serialize and deserialize these classes is considered an internal +implementation detail and as such it might change without prior notice, while +keeping API compatibility with regard to public members of these classes. From 85942ef699cb5a3cbd5cd356ff507f5f99ef99d2 Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Tue, 28 Nov 2023 12:14:15 +0100 Subject: [PATCH 2/2] Review --- site/content/3.10/develop/drivers/java/_index.md | 12 ++++++------ site/content/3.11/develop/drivers/java/_index.md | 12 ++++++------ site/content/3.12/develop/drivers/java/_index.md | 8 ++++---- 3 files changed, 16 insertions(+), 16 deletions(-) diff --git a/site/content/3.10/develop/drivers/java/_index.md b/site/content/3.10/develop/drivers/java/_index.md index ce9ae57eee..9cc49aae9a 100644 --- a/site/content/3.10/develop/drivers/java/_index.md +++ b/site/content/3.10/develop/drivers/java/_index.md @@ -182,12 +182,12 @@ CompletableFuture> future1 = adbAsync.db() // ... ``` -## Data Definitions Classes +## Data Definition Classes -Classes used to exchange data definitions, in particular classes in packages -`com.arangodb.entity.**` and `com.arangodb.model.**`, are meant to be serialized +Classes used to exchange data definitions, in particular classes in the packages +`com.arangodb.entity.**` and `com.arangodb.model.**`, are meant to be serialized and deserialized internally by the driver. -The behavior to serialize and deserialize these classes is considered an internal -implementation detail and as such it might change without prior notice, while -keeping API compatibility with regard to public members of these classes. +The behavior to serialize and deserialize these classes is considered an internal +implementation detail, and as such, it might change without prior notice. +The API with regard to the public members of these classes is kept compatible. diff --git a/site/content/3.11/develop/drivers/java/_index.md b/site/content/3.11/develop/drivers/java/_index.md index ce9ae57eee..9cc49aae9a 100644 --- a/site/content/3.11/develop/drivers/java/_index.md +++ b/site/content/3.11/develop/drivers/java/_index.md @@ -182,12 +182,12 @@ CompletableFuture> future1 = adbAsync.db() // ... ``` -## Data Definitions Classes +## Data Definition Classes -Classes used to exchange data definitions, in particular classes in packages -`com.arangodb.entity.**` and `com.arangodb.model.**`, are meant to be serialized +Classes used to exchange data definitions, in particular classes in the packages +`com.arangodb.entity.**` and `com.arangodb.model.**`, are meant to be serialized and deserialized internally by the driver. -The behavior to serialize and deserialize these classes is considered an internal -implementation detail and as such it might change without prior notice, while -keeping API compatibility with regard to public members of these classes. +The behavior to serialize and deserialize these classes is considered an internal +implementation detail, and as such, it might change without prior notice. +The API with regard to the public members of these classes is kept compatible. diff --git a/site/content/3.12/develop/drivers/java/_index.md b/site/content/3.12/develop/drivers/java/_index.md index 9c8f140622..d414789269 100644 --- a/site/content/3.12/develop/drivers/java/_index.md +++ b/site/content/3.12/develop/drivers/java/_index.md @@ -182,12 +182,12 @@ CompletableFuture> future2 = future1 // ... ``` -## Data Definitions Classes +## Data Definition Classes -Classes used to exchange data definitions, in particular classes in packages +Classes used to exchange data definitions, in particular classes in the packages `com.arangodb.entity.**` and `com.arangodb.model.**`, are meant to be serialized and deserialized internally by the driver. The behavior to serialize and deserialize these classes is considered an internal -implementation detail and as such it might change without prior notice, while -keeping API compatibility with regard to public members of these classes. +implementation detail, and as such, it might change without prior notice. +The API with regard to the public members of these classes is kept compatible.