Introduce a preview feature status (#1400)

injectives · web-flow · commit aa726816633e · 2023-03-30T18:14:02.000+01:00
The preview feature status better defines the status of some of the new features and has a more definitive description.
diff --git 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 <abbr title="Generally Available">GA</abbr> 
+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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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> T execute(Collector<Record, ?, T> recordCollector) {
      * @param <T> the final value type
      * @since 5.5
      */
-    @Experimental
+    @Preview(name = "Driver Level Queries")
     @FunctionalInterface
     interface ResultFinisher<S, T> {
         /**
diff --git 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
@@ -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<String> impersonatedUser() {
      *
      * @return bookmark implementation
      */
-    @Experimental
+    @Preview(name = "Bookmark Manager")
     public Optional<BookmarkManager> 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
@@ -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.
+ * <p>
+ * 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.
+ * <p>
+ * 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.
+ * <p>
+ * 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();
+}
