New Java Driver manual (#413)

common-content/modules/ROOT/partials/connect-advanced.adoc

@@ -0,0 +1,59 @@
+# tag::connection-uri[]
+
+== Connection URI
+
+The driver supports connection to URIs of the form
+
+[source]
+----
+<SCHEME>://<HOST>[:<PORT>[?policy=<POLICY-NAME>]]
+----
+
+- `<SCHEME>` is one among `neo4j`, `neo4j+s`, `neo4j+ssc`, `bolt`, `bolt+s`, `bolt+ssc`.
+- `<HOST>` is the host name where the Neo4j server is located.
+- `<PORT>` is optional, and denotes the port the <<Bolt>> protocol is available at.
+- `<POLICY-NAME>` is an optional _server policy_ name. link:{neo4j-docs-base-uri}/docs/operations-manual/current/clustering/clustering-advanced/multi-data-center-routing/[Server policies] need to be set up prior to usage.
+
+[NOTE]
+The driver does not support connection to a nested path, such as `example.com/neo4j/`.
+The server must be reachable from the domain root.
+
+# end::connection-uri[]
+
+
+# tag::connection-protocols[]
+
+== Connection protocols and security
+
+Communication between the driver and the server is mediated by Bolt.
+The scheme of the server URI determines whether the connection is encrypted and, if so, what type of certificates are accepted.
+
+[options="header", cols="20,40,40"]
+|===
+|URL scheme
+|Encryption
+|Comment
+
+|neo4j
+|{cross-mark}
+|Default for local setups
+
+|neo4j+s
+|{check-mark} (only CA-signed certificates)
+|Default for Aura
+
+|neo4j+ssc
+|{check-mark} (CA- and self-signed certificates)
+|
+|===
+
+[TIP]
+The driver receives a _routing table_ from the server upon successful connection, regardless of whether the instance is a proper cluster environment or a single-machine environment.
+The driver's routing behavior works in tandem with link:{neo4j-docs-base-uri}/operations-manual/current/clustering/[Neo4j's clustering] by directing read/write transactions to appropriate cluster members.
+If you want to target a _specific_ machine, use the `bolt`, `bolt+s`, or `bolt+ssc` URI schemes instead.
+
+The connection scheme to use is not your choice, but is rather determined by the server requirements.
+You must know the right server scheme upfront, as no metadata is exposed prior to connection.
+If you are unsure, ask the database administrator.
+
+# end::connection-protocols[]

common-content/modules/ROOT/partials/glossary.adoc

@@ -12,9 +12,9 @@ It listens on port 7687 by default.
 An ACID-compliant DBMS ensures that the data in the database remains accurate and consistent despite failures.
 [[eventual_consistency]]eventual consistency:: A database is eventually consistent if it provides the guarantee that all cluster members will, _at some point in time_, store the latest version of the data.
 [[causal_consistency]]causal consistency:: A database is causally consistent if read and write queries are seen by every member of the cluster in the same order.
-This is stronger than eventual consistency.
+This is stronger than _eventual consistency_.
 [[NULL]]NULL:: The null marker is not a type but a placeholder for absence of value.
-For more information, see link:{neo4j-docs-base-uri}/cypher-manual/current/values-and-types/working-with-null/[Cypher Manual -- Working with `null`].
+For more information, see link:{neo4j-docs-base-uri}/cypher-manual/current/values-and-types/working-with-null/[Cypher -> Working with `null`].
 [[transaction]]transaction:: A transaction is a unit of work that is either _committed_ in its entirety or _rolled back_ on failure.
 An example is a bank transfer: it involves multiple steps, but they must _all_ succeed or be reverted, to avoid money being subtracted from one account but not added to the other.
 [[backpressure]]backpressure:: Backpressure is a force opposing the flow of data. It ensures that the client is not being overwhelmed by data faster than it can handle.

go-manual/modules/ROOT/content-nav.adoc

@@ -23,6 +23,6 @@
 
 * *GraphAcademy courses*
 
-* link:https://graphacademy.neo4j.com/courses/modeling-fundamentals/?ref=docs-python[Graph Data Modeling Fundamentals]
-* link:https://graphacademy.neo4j.com/courses/cypher-intermediate-queries/?ref=docs-python[Intermediate Cypher Queries]
+* link:https://graphacademy.neo4j.com/courses/modeling-fundamentals/?ref=docs-go[Graph Data Modeling Fundamentals]
+* link:https://graphacademy.neo4j.com/courses/cypher-intermediate-queries/?ref=docs-go[Intermediate Cypher Queries]
 * link:https://graphacademy.neo4j.com/courses/app-go/?ref=docs-go[Building Neo4j Applications with Go]

go-manual/modules/ROOT/pages/connect-advanced.adoc

@@ -1,56 +1,9 @@
 = Advanced connection information
 
-== Connection URI
+include::{common-partial}/connect-advanced.adoc[tag=connection-uri]
 
-The driver supports connection to URIs of the form
+include::{common-partial}/connect-advanced.adoc[tag=connection-protocols]
 
-[source]
-----
-<SCHEME>://<HOST>[:<PORT>[?policy=<POLICY-NAME>]]
-----
-
-- `<SCHEME>` is one among `neo4j`, `neo4j+s`, `neo4j+ssc`, `bolt`, `bolt+s`, `bolt+ssc`.
-- `<HOST>` is the host name where the Neo4j server is located.
-- `<PORT>` is optional, and denotes the port the <<Bolt>> protocol is available at.
-- `<POLICY-NAME>` is an optional _server policy_ name. link:{neo4j-docs-base-uri}/operations-manual/current/clustering/clustering-advanced/multi-data-center-routing/[Server policies] need to be set up prior to usage.
-
-[NOTE]
-Notice that *the driver does not support connection to a nested path*, such as `example.com/neo4j/`.
-The server must be reachable from the domain root.
-
-
-== Connection protocols and security
-
-Communication between the driver and the server is mediated by <<Bolt>>.
-The scheme of the server URI determines whether the connection is encrypted and, if so, what type of certificates are accepted.
-
-[options="header", cols="20,40,40"]
-|===
-|URL scheme
-|Encryption
-|Comment
-
-|neo4j
-|{cross-mark}
-|Default for local setups
-
-|neo4j+s
-|{check-mark} (only CA-signed certificates)
-|Default for Aura
-
-|neo4j+ssc
-|{check-mark} (CA- and self-signed certificates)
-|
-|===
-
-[TIP]
-The driver receives a _routing table_ from the server upon successful connection, regardless of whether the instance is a proper cluster environment or a single-machine environment.
-The driver's routing behavior works in tandem with link:{neo4j-docs-base-uri}/operations-manual/current/clustering/[Neo4j's clustering] by directing read/write transactions to appropriate cluster members.
-If you want to target a _specific_ machine, use the `bolt`, `bolt+s`, or `bolt+ssc` URI schemes instead.
-
-The connection scheme to use is not your choice, but is rather determined by the server requirements.
-You must know the right server scheme upfront, as no metadata is exposed prior to connection.
-If you are unsure, ask the database administrator.
 
 == Authentication methods
 

java-manual/antora.yml

@@ -6,8 +6,6 @@ nav:
 - modules/ROOT/content-nav.adoc
 asciidoc:
   attributes:
-    java-driver-version: '5.12.0' # the version of the api docs published at https://neo4j.com/docs/api/java-driver/
-    java-driver-apidoc-release: '5.0' # the github branch or release that contains examples included in docs
-    java-examples: https://raw.githubusercontent.com/neo4j/neo4j-java-driver/{java-driver-apidoc-release}/examples/src/main/java/org/neo4j/docs/driver
+    java-driver-version: '5.17.0' # the version of the package published at https://central.sonatype.com/artifact/org.neo4j.driver/neo4j-java-driver
     common-partial: 5@common-content:ROOT:partial$
     common-image: 5@common-content:ROOT:image$

java-manual/modules/ROOT/content-nav.adoc

@@ -1,10 +1,30 @@
-* xref:index.adoc[]
-* xref:get-started.adoc[]
-* xref:client-applications.adoc[]
-* xref:cypher-workflow.adoc[]
-* xref:session-api.adoc[]
-// ** xref:session-api/simple.adoc[Simple sessions]
-// ** xref:session-api/asynchronous.adoc[Asynchronous sessions]
-// ** xref:session-api/reactive.adoc[Reactive sessions]
-// ** xref:session-api/configuration.adoc[Session configuration]
-* xref:terminology.adoc[]
+* xref:index.adoc[Quickstart]
+
+* *Basic workflow*
+
+* xref:install.adoc[Installation]
+* xref:connect.adoc[Connect to the database]
+* xref:query-simple.adoc[Query the database]
+
+* *Advanced usage*
+
+* xref:transactions.adoc[Run your own transactions]
+* xref:result-summary.adoc[Explore the query execution summary]
+* xref:async.adoc[Run asynchronous queries]
+* xref:bookmarks.adoc[Coordinate parallel transactions]
+* xref:query-advanced.adoc[Further query mechanisms]
+* xref:reactive.adoc[Control results flow with reactive streams]
+* xref:performance.adoc[Performance recommendations]
+
+* *Reference*
+
+* xref:connect-advanced.adoc[Advanced connection information]
+* xref:data-types.adoc[Data types and mapping to Cypher types]
+* link:https://neo4j.com/docs/api/java-driver/current/[API documentation, window=_blank]
+* xref:related-projects.adoc[Related projects]
+
+* *GraphAcademy courses*
+
+* link:https://graphacademy.neo4j.com/courses/modeling-fundamentals/?ref=docs-java[Graph Data Modeling Fundamentals]
+* link:https://graphacademy.neo4j.com/courses/cypher-intermediate-queries/?ref=docs-java[Intermediate Cypher Queries]
+* link:https://graphacademy.neo4j.com/courses/app-java/?ref=docs-java[Building Neo4j Applications with Java]

java-manual/modules/ROOT/pages/async.adoc

@@ -0,0 +1,91 @@
+= Run non-blocking asynchronous queries
+:page-toclevels: 0
+
+The examples in xref:query-simple.adoc[Query the database] and xref:transactions.adoc[Run your own transactions] use the driver in its synchronous form.
+This means that, when running a query against the database, your application waits for the server to retrieve all the results and transmit them to the driver.
+This is not a problem for most use cases, but for queries that have a long processing time or a large result set, asynchronous handling may speed up your application.
+
+== Asynchronous managed transactions
+
+You run an asynchronous transaction through an link:https://neo4j.com/docs/api/java-driver/current/org.neo4j.driver/org/neo4j/driver/async/AsyncSession.html[`AsyncSession`].
+The flow is similar to that of xref:transactions.adoc[regular transactions], except that async transaction functions return a link:https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/concurrent/CompletionStage.html[`CompletionStage`] object (which may be further converted into link:https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/concurrent/CompletableFuture.html[`CompletableFuture`]).
+
+
+[source, java]
+----
+package demo;
+
+import java.util.Map;
+import java.util.concurrent.CompletionStage;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.ExecutionException;
+
+import org.neo4j.driver.async.AsyncSession;
+import org.neo4j.driver.AuthTokens;
+import org.neo4j.driver.Driver;
+import org.neo4j.driver.GraphDatabase;
+import org.neo4j.driver.summary.ResultSummary;
+import org.neo4j.driver.SessionConfig;
+
+public class App {
+
+    public static void main(String... args) throws ExecutionException, InterruptedException {
+        final String dbUri = "<URI for Neo4j database>";
+        final String dbUser = "<Username>";
+        final String dbPassword = "<Password>";
+
+        try (var driver = GraphDatabase.driver(dbUri, AuthTokens.basic(dbUser, dbPassword))) {  // <1>
+            driver.verifyConnectivity();
+
+            var summary = printAllPeople(driver);
+            // Block as long as necessary (for demonstration purposes)
+            System.out.println(summary.get());  // <8>
+        }
+    }
+
+    public static CompletableFuture<ResultSummary> printAllPeople(Driver driver) {
+        var session = driver.session(AsyncSession.class, SessionConfig.builder().withDatabase("neo4j").build());  // <2>
+
+        var query = """
+        UNWIND ['Alice', 'Bob', 'Sofia', 'Charles'] AS name
+        MERGE (p:Person {name: name}) RETURN p.name
+        """;
+        var summary = session.executeWriteAsync(tx -> tx.runAsync(query)  // <3>
+                .thenCompose(resCursor -> resCursor.forEachAsync(record -> {  // <4>
+                    System.out.println(record.get(0).asString());
+                })))
+            .whenComplete((result, error) -> {  // <5>
+                session.closeAsync();
+            })
+            .toCompletableFuture();  // <6>
+
+        return summary;  // <7>
+    }
+}
+----
+
+<1> Driver creation is the same in the synchronous and asynchronous versions.
+<2> An asynchronous session is created by providing `AsyncSession.class` as first parameter to link:https://neo4j.com/docs/api/java-driver/current/org.neo4j.driver/org/neo4j/driver/Driver.html#session(java.lang.Class,org.neo4j.driver.SessionConfig)[`Driver.session()`], which returns an link:https://neo4j.com/docs/api/java-driver/current/org.neo4j.driver/org/neo4j/driver/async/AsyncSession.html[`AsyncSession`] object.
+<3> As for regular transactions, `.executeWriteAsync()` (and `executeReadAsync()`) take a transaction function callback.
+Inside the transaction function, run queries with link:https://neo4j.com/docs/api/java-driver/current/org.neo4j.driver/org/neo4j/driver/async/AsyncQueryRunner.html#runAsync(org.neo4j.driver.Query)[`.runAsync()`].
+Each query run returns a link:https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/concurrent/CompletionStage.html[`CompletionStage`].
+<4> Optionally use methods on `CompletionStage` to process the result in the asynchronous runner.
+The query's result set is available as an link:https://neo4j.com/docs/api/java-driver/current/org.neo4j.driver/org/neo4j/driver/internal/cursor/AsyncResultCursor.html[`AsyncResultCursor`], which implements a similar set of methods for processing the result to those of synchronous transactions (see xref:transactions.adoc#process-result[Transactions -> Process query results]). +
+Inner object types are the same as the synchronous case (i.e. `Record`, `ResultSummary`).
+<5> Optionally run operations once the query has completed, such as closing the driver session.
+<6> link:https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/concurrent/CompletableFuture.html[`CompletableFuture`] is a convenient type to return back to the caller.
+<7> Contrary to synchronous transactions, `.executeWriteAsync()` and `executeReadAsync()` return the xref:result-summary.adoc[result summary] only.
+**Result processing and handling must be done inside the asynchronous runner.**
+<8> link:https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/concurrent/CompletableFuture.html#get()[`.get()`] waits as long as necessary for the future to complete, and then returns its result.
+
+[CAUTION]
+The methods `.executeReadAsync()` and `.executeWriteAsync()` have replaced `.readTransactionAsync()` and `.writeTransactionAsync()`, which are deprecated in version 5.x and will be removed in version 6.0.
+
+
+ifndef::backend-pdf[]
+[discrete.glossary]
+== Glossary
+
+include::{common-partial}/glossary.adoc[]
+include::../partials/glossary.adoc[]
+endif::[]