From dbb752c4c9aa80ddb8619da6a4498aac527d3909 Mon Sep 17 00:00:00 2001 From: Dmitriy Tverdiakov Date: Thu, 30 Mar 2023 17:43:03 +0100 Subject: [PATCH] Introduce a preview feature status The preview feature status better defines the status of some of the new features and has a more definitive description. --- README.md | 19 +++++++ .../org/neo4j/driver/BookmarkManager.java | 4 +- .../org/neo4j/driver/BookmarkManagers.java | 4 +- .../main/java/org/neo4j/driver/Config.java | 5 +- .../main/java/org/neo4j/driver/Driver.java | 5 +- .../java/org/neo4j/driver/EagerResult.java | 4 +- .../java/org/neo4j/driver/QueryConfig.java | 4 +- .../main/java/org/neo4j/driver/QueryTask.java | 6 +-- .../java/org/neo4j/driver/RoutingControl.java | 4 +- .../java/org/neo4j/driver/SessionConfig.java | 6 +-- .../java/org/neo4j/driver/util/Preview.java | 54 +++++++++++++++++++ 11 files changed, 95 insertions(+), 20 deletions(-) create mode 100644 driver/src/main/java/org/neo4j/driver/util/Preview.java diff --git a/README.md b/README.md index 1a13833b17..1fbbb39084 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,25 @@ As a policy, patch versions will not be released except on rare occasions. Bug f The compatibility with Neo4j Server versions is documented in the [Neo4j Knowledge Base](https://neo4j.com/developer/kb/neo4j-supported-versions/). +## Preview features + +The preview feature is a new feature that is a candidate for a future GA +status. + +It enables users to try the feature out and maintainers to refine and update it. + +The preview features are not considered to be experimental, temporary or unstable. + +However, they may change more rapidly, without following the usual deprecation cycle. + +Most preview features are expected to be granted the GA status unless some unexpected conditions arise. + +Due to the increased flexibility of the preview status, user feedback is encouraged so that it can be considered before +the GA status. + +Every feature gets a dedicated [GitHub Discussion](https://github.com/neo4j/neo4j-java-driver/discussions/categories/preview-features) +where feedback may be shared. + ## Usage This section provides general information for engineers who are building Neo4j-backed applications. diff --git a/driver/src/main/java/org/neo4j/driver/BookmarkManager.java b/driver/src/main/java/org/neo4j/driver/BookmarkManager.java index ee9003e213..5caf492044 100644 --- a/driver/src/main/java/org/neo4j/driver/BookmarkManager.java +++ b/driver/src/main/java/org/neo4j/driver/BookmarkManager.java @@ -20,7 +20,7 @@ import java.io.Serializable; import java.util.Set; -import org.neo4j.driver.util.Experimental; +import org.neo4j.driver.util.Preview; /** * Keeps track of bookmarks and is used by the driver to ensure causal consistency between sessions and query executions. @@ -31,7 +31,7 @@ * * @see org.neo4j.driver.SessionConfig.Builder#withBookmarkManager(BookmarkManager) */ -@Experimental +@Preview(name = "Bookmark Manager") public interface BookmarkManager extends Serializable { /** * Updates bookmarks by deleting the given previous bookmarks and adding the new bookmarks. diff --git a/driver/src/main/java/org/neo4j/driver/BookmarkManagers.java b/driver/src/main/java/org/neo4j/driver/BookmarkManagers.java index c0d4eadd2b..6eedb292bc 100644 --- a/driver/src/main/java/org/neo4j/driver/BookmarkManagers.java +++ b/driver/src/main/java/org/neo4j/driver/BookmarkManagers.java @@ -19,12 +19,12 @@ package org.neo4j.driver; import org.neo4j.driver.internal.Neo4jBookmarkManager; -import org.neo4j.driver.util.Experimental; +import org.neo4j.driver.util.Preview; /** * Setups new instances of {@link BookmarkManager}. */ -@Experimental +@Preview(name = "Bookmark Manager") public final class BookmarkManagers { private BookmarkManagers() {} /** diff --git a/driver/src/main/java/org/neo4j/driver/Config.java b/driver/src/main/java/org/neo4j/driver/Config.java index 7afdadad09..671e699cf1 100644 --- a/driver/src/main/java/org/neo4j/driver/Config.java +++ b/driver/src/main/java/org/neo4j/driver/Config.java @@ -41,6 +41,7 @@ import org.neo4j.driver.net.ServerAddressResolver; import org.neo4j.driver.util.Experimental; import org.neo4j.driver.util.Immutable; +import org.neo4j.driver.util.Preview; /** * A configuration class to config driver properties. @@ -187,7 +188,7 @@ private Config(ConfigBuilder builder) { * @return bookmark manager, must not be {@code null} * @since 5.5 */ - @Experimental + @Preview(name = "Driver Level Queries") public BookmarkManager queryTaskBookmarkManager() { return queryBookmarkManager; } @@ -393,7 +394,7 @@ private ConfigBuilder() {} * @return this builder * @since 5.5 */ - @Experimental + @Preview(name = "Driver Level Queries") public ConfigBuilder withQueryTaskBookmarkManager(BookmarkManager bookmarkManager) { Objects.requireNonNull(bookmarkManager, "bookmarkManager must not be null"); this.queryBookmarkManager = bookmarkManager; diff --git a/driver/src/main/java/org/neo4j/driver/Driver.java b/driver/src/main/java/org/neo4j/driver/Driver.java index a46d96778f..ddd278a7bf 100644 --- a/driver/src/main/java/org/neo4j/driver/Driver.java +++ b/driver/src/main/java/org/neo4j/driver/Driver.java @@ -25,6 +25,7 @@ import org.neo4j.driver.reactive.RxSession; import org.neo4j.driver.types.TypeSystem; import org.neo4j.driver.util.Experimental; +import org.neo4j.driver.util.Preview; /** * Accessor for a specific Neo4j graph database. @@ -71,7 +72,7 @@ public interface Driver extends AutoCloseable { * @return new query task instance * @since 5.5 */ - @Experimental + @Preview(name = "Driver Level Queries") QueryTask queryTask(String query); /** @@ -80,7 +81,7 @@ public interface Driver extends AutoCloseable { * @return bookmark manager, must not be {@code null} * @since 5.6 */ - @Experimental + @Preview(name = "Driver Level Queries") BookmarkManager queryTaskBookmarkManager(); /** diff --git a/driver/src/main/java/org/neo4j/driver/EagerResult.java b/driver/src/main/java/org/neo4j/driver/EagerResult.java index 006c67684f..c21ac6f328 100644 --- a/driver/src/main/java/org/neo4j/driver/EagerResult.java +++ b/driver/src/main/java/org/neo4j/driver/EagerResult.java @@ -20,13 +20,13 @@ import java.util.List; import org.neo4j.driver.summary.ResultSummary; -import org.neo4j.driver.util.Experimental; +import org.neo4j.driver.util.Preview; /** * An in-memory result of executing a Cypher query that has been consumed in full. * @since 5.5 */ -@Experimental +@Preview(name = "Driver Level Queries") public interface EagerResult { /** * Returns the keys of the records this result contains. diff --git a/driver/src/main/java/org/neo4j/driver/QueryConfig.java b/driver/src/main/java/org/neo4j/driver/QueryConfig.java index f02c6ec82c..6c40c395f9 100644 --- a/driver/src/main/java/org/neo4j/driver/QueryConfig.java +++ b/driver/src/main/java/org/neo4j/driver/QueryConfig.java @@ -24,13 +24,13 @@ import java.io.Serializable; import java.util.Objects; import java.util.Optional; -import org.neo4j.driver.util.Experimental; +import org.neo4j.driver.util.Preview; /** * Query configuration used by {@link Driver#queryTask(String)} and its variants. * @since 5.5 */ -@Experimental +@Preview(name = "Driver Level Queries") public final class QueryConfig implements Serializable { @Serial private static final long serialVersionUID = -2632780731598141754L; diff --git a/driver/src/main/java/org/neo4j/driver/QueryTask.java b/driver/src/main/java/org/neo4j/driver/QueryTask.java index 20d29bbfbb..2c395a6a8c 100644 --- a/driver/src/main/java/org/neo4j/driver/QueryTask.java +++ b/driver/src/main/java/org/neo4j/driver/QueryTask.java @@ -26,7 +26,7 @@ import java.util.stream.Collectors; import org.neo4j.driver.internal.EagerResultValue; import org.neo4j.driver.summary.ResultSummary; -import org.neo4j.driver.util.Experimental; +import org.neo4j.driver.util.Preview; /** * A task that executes a query in a managed transaction with automatic retries on retryable errors. @@ -97,7 +97,7 @@ * * @since 5.5 */ -@Experimental +@Preview(name = "Driver Level Queries") public interface QueryTask { /** * Sets query parameters. @@ -167,7 +167,7 @@ default T execute(Collector recordCollector) { * @param the final value type * @since 5.5 */ - @Experimental + @Preview(name = "Driver Level Queries") @FunctionalInterface interface ResultFinisher { /** diff --git a/driver/src/main/java/org/neo4j/driver/RoutingControl.java b/driver/src/main/java/org/neo4j/driver/RoutingControl.java index e1927cf726..b203bc06b4 100644 --- a/driver/src/main/java/org/neo4j/driver/RoutingControl.java +++ b/driver/src/main/java/org/neo4j/driver/RoutingControl.java @@ -18,13 +18,13 @@ */ package org.neo4j.driver; -import org.neo4j.driver.util.Experimental; +import org.neo4j.driver.util.Preview; /** * Defines routing mode for query. * @since 5.5 */ -@Experimental +@Preview(name = "Driver Level Queries") public enum RoutingControl { /** * Routes to the leader of the cluster. diff --git a/driver/src/main/java/org/neo4j/driver/SessionConfig.java b/driver/src/main/java/org/neo4j/driver/SessionConfig.java index aad02a68a4..c77c552bac 100644 --- a/driver/src/main/java/org/neo4j/driver/SessionConfig.java +++ b/driver/src/main/java/org/neo4j/driver/SessionConfig.java @@ -30,7 +30,7 @@ import org.neo4j.driver.exceptions.UnsupportedFeatureException; import org.neo4j.driver.reactive.ReactiveSession; import org.neo4j.driver.reactive.RxSession; -import org.neo4j.driver.util.Experimental; +import org.neo4j.driver.util.Preview; import org.reactivestreams.Subscription; /** @@ -162,7 +162,7 @@ public Optional impersonatedUser() { * * @return bookmark implementation */ - @Experimental + @Preview(name = "Bookmark Manager") public Optional bookmarkManager() { return Optional.ofNullable(bookmarkManager); } @@ -377,7 +377,7 @@ public Builder withImpersonatedUser(String impersonatedUser) { * @param bookmarkManager bookmark manager implementation. Providing {@code null} effectively disables bookmark manager. * @return this builder. */ - @Experimental + @Preview(name = "Bookmark Manager") public Builder withBookmarkManager(BookmarkManager bookmarkManager) { this.bookmarkManager = bookmarkManager; return this; diff --git a/driver/src/main/java/org/neo4j/driver/util/Preview.java b/driver/src/main/java/org/neo4j/driver/util/Preview.java new file mode 100644 index 0000000000..8ac9e07e2c --- /dev/null +++ b/driver/src/main/java/org/neo4j/driver/util/Preview.java @@ -0,0 +1,54 @@ +/* + * Copyright (c) "Neo4j" + * Neo4j Sweden AB [http://neo4j.com] + * + * This file is part of Neo4j. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.neo4j.driver.util; + +import java.lang.annotation.Documented; +import java.lang.annotation.ElementType; +import java.lang.annotation.Inherited; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * A marker annotation indicating that the annotated target belongs to a preview feature. + *

+ * The preview feature is a new feature that is a candidate for a future GA status. It enables users to try the feature + * out and maintainers to refine and update it. + *

+ * The preview features are not considered to be experimental, temporary or unstable. However, they may change more + * rapidly without the deprecation cycle. Most preview features are expected to be granted the GA status unless some + * unexpected conditions arise. + *

+ * Due to the increased flexibility of the preview status, user feedback is encouraged so that it can be considered + * before the GA status. See the driver's README for details on how to provide the feedback. + * + * @since 5.7 + */ +@Inherited +@Retention(RetentionPolicy.RUNTIME) +@Documented +@Target({ElementType.TYPE, ElementType.METHOD}) +public @interface Preview { + /** + * The feature name or a reference. + * + * @return the feature name or a reference + */ + String name(); +}