Skip to content

Commit 361e779

Browse files
authored
Introduce managed query execution on Driver level (#1330)
* Introduce managed query execution on Driver level This is a new basic high-level API for executing idempotent queries. * Update Config option name
1 parent c5f5fde commit 361e779

24 files changed

+1397
-144
lines changed

driver/clirr-ignored-differences.xml

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -409,4 +409,16 @@
409409
<method>org.neo4j.driver.BaseSession session(java.lang.Class, org.neo4j.driver.SessionConfig)</method>
410410
</difference>
411411

412+
<difference>
413+
<className>org/neo4j/driver/Driver</className>
414+
<differenceType>7012</differenceType>
415+
<method>org.neo4j.driver.QueryTask queryTask(java.lang.String)</method>
416+
</difference>
417+
418+
<difference>
419+
<className>org/neo4j/driver/Driver</className>
420+
<differenceType>7012</differenceType>
421+
<method>org.neo4j.driver.BookmarkManager queryBookmarkManager()</method>
422+
</difference>
423+
412424
</differences>

driver/src/main/java/org/neo4j/driver/Config.java

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,8 @@ public final class Config implements Serializable {
7575

7676
private static final Config EMPTY = builder().build();
7777

78+
private final BookmarkManager queryBookmarkManager;
79+
7880
/**
7981
* User defined logging
8082
*/
@@ -102,6 +104,7 @@ public final class Config implements Serializable {
102104
private final MetricsAdapter metricsAdapter;
103105

104106
private Config(ConfigBuilder builder) {
107+
this.queryBookmarkManager = builder.queryBookmarkManager;
105108
this.logging = builder.logging;
106109
this.logLeakedSessions = builder.logLeakedSessions;
107110

@@ -123,6 +126,21 @@ private Config(ConfigBuilder builder) {
123126
this.metricsAdapter = builder.metricsAdapter;
124127
}
125128

129+
/**
130+
* A {@link BookmarkManager} implementation for the driver to use on
131+
* {@link Driver#queryTask(String)} method and its variants by default.
132+
* <p>
133+
* Please note that sessions will not use this automatically, but it is possible to enable it explicitly
134+
* using {@link SessionConfig.Builder#withBookmarkManager(BookmarkManager)}.
135+
*
136+
* @return bookmark manager, must not be {@code null}
137+
* @since 5.5
138+
*/
139+
@Experimental
140+
public BookmarkManager queryTaskBookmarkManager() {
141+
return queryBookmarkManager;
142+
}
143+
126144
/**
127145
* Logging provider
128146
*
@@ -262,6 +280,8 @@ public String userAgent() {
262280
* Used to build new config instances
263281
*/
264282
public static final class ConfigBuilder {
283+
private BookmarkManager queryBookmarkManager =
284+
BookmarkManagers.defaultManager(BookmarkManagerConfig.builder().build());
265285
private Logging logging = DEV_NULL_LOGGING;
266286
private boolean logLeakedSessions;
267287
private int maxConnectionPoolSize = PoolSettings.DEFAULT_MAX_CONNECTION_POOL_SIZE;
@@ -281,6 +301,24 @@ public static final class ConfigBuilder {
281301

282302
private ConfigBuilder() {}
283303

304+
/**
305+
* Sets a {@link BookmarkManager} implementation for the driver to use on
306+
* {@link Driver#queryTask(String)} method and its variants by default.
307+
* <p>
308+
* Please note that sessions will not use this automatically, but it is possible to enable it explicitly
309+
* using {@link SessionConfig.Builder#withBookmarkManager(BookmarkManager)}.
310+
*
311+
* @param bookmarkManager bookmark manager, must not be {@code null}
312+
* @return this builder
313+
* @since 5.5
314+
*/
315+
@Experimental
316+
public ConfigBuilder withQueryTaskBookmarkManager(BookmarkManager bookmarkManager) {
317+
Objects.requireNonNull(bookmarkManager, "bookmarkManager must not be null");
318+
this.queryBookmarkManager = bookmarkManager;
319+
return this;
320+
}
321+
284322
/**
285323
* Provide a logging implementation for the driver to use. Java logging framework {@link java.util.logging} with {@link Level#INFO} is used by default.
286324
* Callers are expected to either implement {@link Logging} interface or provide one of the existing implementations available from static factory

driver/src/main/java/org/neo4j/driver/Driver.java

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,26 @@
6363
* @since 1.0 (Modified and Added {@link AsyncSession} and {@link RxSession} since 2.0)
6464
*/
6565
public interface Driver extends AutoCloseable {
66+
/**
67+
* Creates a new {@link QueryTask} instance that executes an idempotent query in a managed transaction with
68+
* automatic retries on retryable errors.
69+
*
70+
* @param query query string
71+
* @return new query task instance
72+
* @since 5.5
73+
*/
74+
@Experimental
75+
QueryTask queryTask(String query);
76+
77+
/**
78+
* Returns an instance of {@link BookmarkManager} used by {@link QueryTask} instances by default.
79+
*
80+
* @return bookmark manager, must not be {@code null}
81+
* @since 5.5
82+
*/
83+
@Experimental
84+
BookmarkManager queryBookmarkManager();
85+
6686
/**
6787
* Return a flag to indicate whether or not encryption is used for this driver.
6888
*
@@ -84,6 +104,7 @@ default Session session() {
84104
/**
85105
* Instantiate a new {@link Session} with a specified {@link SessionConfig session configuration}.
86106
* Use {@link SessionConfig#forDatabase(String)} to obtain a general purpose session configuration for the specified database.
107+
*
87108
* @param sessionConfig specifies session configurations for this session.
88109
* @return a new {@link Session} object.
89110
* @see SessionConfig
@@ -257,6 +278,7 @@ default AsyncSession asyncSession(SessionConfig sessionConfig) {
257278
/**
258279
* Returns the driver metrics if metrics reporting is enabled via {@link Config.ConfigBuilder#withDriverMetrics()}.
259280
* Otherwise, a {@link ClientException} will be thrown.
281+
*
260282
* @return the driver metrics if enabled.
261283
* @throws ClientException if the driver metrics reporting is not enabled.
262284
*/
@@ -281,7 +303,7 @@ default AsyncSession asyncSession(SessionConfig sessionConfig) {
281303
/**
282304
* This verifies if the driver can connect to a remote server or a cluster
283305
* by establishing a network connection with the remote and possibly exchanging a few data before closing the connection.
284-
*
306+
* <p>
285307
* It throws exception if fails to connect. Use the exception to further understand the cause of the connectivity problem.
286308
* Note: Even if this method throws an exception, the driver still need to be closed via {@link #close()} to free up all resources.
287309
*/
@@ -290,7 +312,7 @@ default AsyncSession asyncSession(SessionConfig sessionConfig) {
290312
/**
291313
* This verifies if the driver can connect to a remote server or cluster
292314
* by establishing a network connection with the remote and possibly exchanging a few data before closing the connection.
293-
*
315+
* <p>
294316
* This operation is asynchronous and returns a {@link CompletionStage}. This stage is completed with
295317
* {@code null} when the driver connects to the remote server or cluster successfully.
296318
* It is completed exceptionally if the driver failed to connect the remote server or cluster.
@@ -303,12 +325,14 @@ default AsyncSession asyncSession(SessionConfig sessionConfig) {
303325

304326
/**
305327
* Returns true if the server or cluster the driver connects to supports multi-databases, otherwise false.
328+
*
306329
* @return true if the server or cluster the driver connects to supports multi-databases, otherwise false.
307330
*/
308331
boolean supportsMultiDb();
309332

310333
/**
311334
* Asynchronous check if the server or cluster the driver connects to supports multi-databases.
335+
*
312336
* @return a {@link CompletionStage completion stage} that returns true if the server or cluster
313337
* the driver connects to supports multi-databases, otherwise false.
314338
*/
Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
/*
2+
* Copyright (c) "Neo4j"
3+
* Neo4j Sweden AB [http://neo4j.com]
4+
*
5+
* This file is part of Neo4j.
6+
*
7+
* Licensed under the Apache License, Version 2.0 (the "License");
8+
* you may not use this file except in compliance with the License.
9+
* You may obtain a copy of the License at
10+
*
11+
* http://www.apache.org/licenses/LICENSE-2.0
12+
*
13+
* Unless required by applicable law or agreed to in writing, software
14+
* distributed under the License is distributed on an "AS IS" BASIS,
15+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
* See the License for the specific language governing permissions and
17+
* limitations under the License.
18+
*/
19+
package org.neo4j.driver;
20+
21+
import java.util.List;
22+
import org.neo4j.driver.summary.ResultSummary;
23+
import org.neo4j.driver.util.Experimental;
24+
25+
/**
26+
* An in-memory result of executing a Cypher query that has been consumed in full.
27+
* @since 5.5
28+
*/
29+
@Experimental
30+
public interface EagerResult {
31+
/**
32+
* Returns the keys of the records this result contains.
33+
*
34+
* @return list of keys
35+
*/
36+
List<String> keys();
37+
38+
/**
39+
* Returns the list of records this result contains.
40+
*
41+
* @return list of records
42+
*/
43+
List<Record> records();
44+
45+
/**
46+
* Returns the result summary.
47+
*
48+
* @return result summary
49+
*/
50+
ResultSummary summary();
51+
}

0 commit comments

Comments
 (0)