Move Stable API to Unstable (#3016)

* Move Stable and Maintained to Unstable

* Mark relational APIs as experimental

* Fix javadoc and remove MAINTAINED

* Add fdb-extensions to relational-api

* More gradle fixes

* Restore final

Author: arnaud-lacurie

docs/Versioning.md

@@ -75,15 +75,12 @@ Classes and methods annotations using `@API` determine when they can be changed
 
 * `STABLE` will not change until the major version is incremented. At that time, they may also change status to something less stable.
 
-* `MAINTAINED` will not change until the minor version is incremented. At that time, only the status changes to `UNSTABLE` or `DEPRECATED`. This indicates that in the *next* minor version they will change / be removed.
-
 * `UNSTABLE` can change in a minor release without other advance notice.
 
 * `DEPRECATED` can be removed in a minor release without other advance notice.
 
 * `EXPERIMENTAL` can change / be removed in any build without notice.
 
-
 ## Creating a Patch Branch
 
 * Patch branches should be named `fdb-record-layer-a.b.c` after the build from which they are created.

fdb-extensions/src/main/java/com/apple/foundationdb/FDBError.java

@@ -30,7 +30,7 @@
  * FDB error codes (from https://apple.github.io/foundationdb/api-error-codes.html) and handy methods to
  * interpret them.
  */
-@API(API.Status.MAINTAINED)
+@API(API.Status.UNSTABLE)
 public enum FDBError {
     SUCCESS(0),
     OPERATION_FAILED(1000),

fdb-extensions/src/main/java/com/apple/foundationdb/annotation/API.java

@@ -79,20 +79,10 @@ enum Status {
 
         /**
          * Used by APIs that may change in the next minor release without prior notice. In contrast to those marked
-         * {@code EXPERIMENTAL}, this API shall not be changed or be removed until the next minor release. In contrast
-         * to {@code MAINTAINED} code, there may not be advance notification (such as deprecation) before the API is
-         * changed or removed. May become less stable in the next minor release.
+         * {@code EXPERIMENTAL}, this API shall not be changed or be removed until the next minor release.
          */
         UNSTABLE,
 
-        /**
-         * Used for APIs that shall not be changed or removed in the next minor release. May become less stable in
-         * the next minor release. Generally, if this API is to be changed or removed, the status changes first to
-         * a lower stability (such as {@code UNSTABLE} or {@code DEPRECATED}) in the next minor release. This status
-         * change serves as a notification of the potential upcoming change.
-         */
-        MAINTAINED,
-
         /**
          * Used for APIs that shall not be changed in a backwards-incompatible way or removed until the next major release.
          * May become less stable in the next major release.

fdb-extensions/src/main/java/com/apple/foundationdb/annotation/SpotBugsSuppressWarnings.java

@@ -25,7 +25,7 @@
  *
  * Avoids introducing another transitive dependency.
  */
-@API(API.Status.STABLE)
+@API(API.Status.UNSTABLE)
 public @interface SpotBugsSuppressWarnings {
     String[] value();
     String justification() default "";

fdb-extensions/src/main/java/com/apple/foundationdb/async/AsyncPeekIterator.java

@@ -41,7 +41,7 @@
  *
  * @param <T> type of elements returned by the scan
  */
-@API(API.Status.STABLE)
+@API(API.Status.UNSTABLE)
 public interface AsyncPeekIterator<T> extends AsyncIterator<T> {
     /**
      * Get the next item of the scan without advancing it.

fdb-extensions/src/main/java/com/apple/foundationdb/async/MoreAsyncUtil.java

@@ -796,7 +796,7 @@ public static <U, T> CompletableFuture<U> reduce(@Nonnull Executor executor,
      * @param future the future to check for normal completion
      * @return whether the future has completed without exception
      */
-    @API(API.Status.MAINTAINED)
+    @API(API.Status.UNSTABLE)
     public static boolean isCompletedNormally(@Nonnull CompletableFuture<?> future) {
         return future.isDone() && !future.isCompletedExceptionally();
     }
@@ -831,7 +831,7 @@ public static ScheduledExecutorService getDefaultScheduledExecutor() {
      * @return a future that will be ready after the given delay
      * @see #delayedFuture(long, TimeUnit, ScheduledExecutorService)
      */
-    @API(API.Status.MAINTAINED)
+    @API(API.Status.UNSTABLE)
     @Nonnull
     public static CompletableFuture<Void> delayedFuture(long delay, @Nonnull TimeUnit unit) {
         return delayedFuture(delay, unit, getDefaultScheduledExecutor());
@@ -850,7 +850,7 @@ public static CompletableFuture<Void> delayedFuture(long delay, @Nonnull TimeUni
      * @param scheduledExecutor executor service used to complete the returned future and run any same-thread callbacks
      * @return a {@link CompletableFuture} that will fire after the given delay
      */
-    @API(API.Status.MAINTAINED)
+    @API(API.Status.UNSTABLE)
     @Nonnull
     public static CompletableFuture<Void> delayedFuture(long delay, @Nonnull TimeUnit unit, @Nonnull ScheduledExecutorService scheduledExecutor) {
         if (delay <= 0) {
@@ -895,7 +895,7 @@ public static <T> CompletableFuture<T> getWithDeadline(long deadlineTimeMillis,
      * Close the given iterator, or at least cancel it.
      * @param iterator iterator to close
      */
-    @API(API.Status.MAINTAINED)
+    @API(API.Status.UNSTABLE)
     public static void closeIterator(@Nonnull Iterator<?> iterator) {
         if (iterator instanceof CloseableAsyncIterator) {
             ((CloseableAsyncIterator<?>)iterator).close();

fdb-extensions/src/main/java/com/apple/foundationdb/async/RangeSet.java

@@ -50,7 +50,7 @@
  * append only set that can be used to keep track of the progress that that job is making.
  * </p>
  */
-@API(API.Status.MAINTAINED)
+@API(API.Status.UNSTABLE)
 public class RangeSet {
     @Nonnull private Subspace subspace;
     @Nonnull private static final byte[] FIRST_KEY = { (byte)0x00 };

fdb-extensions/src/main/java/com/apple/foundationdb/async/RankedSet.java

@@ -75,7 +75,7 @@
  * and the value is the number of elements between this key and the previous key at the same level, encoded as a little-endian long.
  * </p>
  */
-@API(API.Status.MAINTAINED)
+@API(API.Status.UNSTABLE)
 public class RankedSet {
     /**
      * Hash using the JDK's default byte array hash.

fdb-extensions/src/main/java/com/apple/foundationdb/tuple/ByteArrayUtil2.java

@@ -77,7 +77,7 @@ public static String toHexString(@Nullable byte[] bytes) {
      * @return a hex representation of {@code bytes}
      * @see ByteArrayUtil#printable(byte[])
      */
-    @API(API.Status.MAINTAINED)
+    @API(API.Status.UNSTABLE)
     @Nullable
     public static String loggable(@Nullable byte[] bytes) {
         if (bytes == null) {
@@ -111,7 +111,7 @@ public static String loggable(@Nullable byte[] bytes) {
      *     returned by {@link ByteArrayUtil#printable(byte[])}
      * @return a byte array parsed from {@code loggedBytes}
      */
-    @API(API.Status.MAINTAINED)
+    @API(API.Status.UNSTABLE)
     @Nullable
     public static byte[] unprint(@Nullable String loggedBytes) {
         if (loggedBytes == null) {

fdb-extensions/src/main/java/com/apple/foundationdb/tuple/TupleHelpers.java

@@ -61,7 +61,7 @@ public static Tuple subTuple(@Nonnull Tuple src, int start, int end) {
      *         a value less than {@code 0} if {@code t1} would sort before {@code t2}
      *         a value greater than {@code 0} if {@code t1} would sort after {@code t2}
      */
-    @API(API.Status.MAINTAINED)
+    @API(API.Status.UNSTABLE)
     public static int compare(@Nonnull Tuple t1, @Nonnull Tuple t2) {
         final int t1Len = t1.size();
         final int t2Len = t2.size();

fdb-extensions/src/main/java/com/apple/foundationdb/util/LoggableException.java

@@ -31,7 +31,7 @@
  * be logged in a way that better supports searching later.
  */
 @SuppressWarnings("serial")
-@API(API.Status.MAINTAINED)
+@API(API.Status.UNSTABLE)
 public class LoggableException extends RuntimeException implements LoggableKeysAndValues<LoggableException> {
     @Nonnull private final LoggableKeysAndValuesImpl loggableKeysAndValuesImpl = new LoggableKeysAndValuesImpl();
 

fdb-extensions/src/main/java/com/apple/foundationdb/util/LoggableKeysAndValuesImpl.java

@@ -32,7 +32,7 @@
  * Provides a default implementation of {@link LoggableKeysAndValues}.
  */
 @SuppressWarnings("serial")
-@API(API.Status.MAINTAINED)
+@API(API.Status.UNSTABLE)
 public class LoggableKeysAndValuesImpl implements LoggableKeysAndValues<LoggableKeysAndValuesImpl> {
     private static final Object[] EMPTY_LOG_INFO = new Object[0];
     @Nullable private Map<String, Object> logInfo;

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/Bindings.java

@@ -38,7 +38,7 @@
  * A binding map can also have a parent from which values are taken if they are absent in the child.
  * </p>
  */
-@API(API.Status.MAINTAINED)
+@API(API.Status.UNSTABLE)
 public class Bindings {
 
     /**

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/EndpointType.java

@@ -32,7 +32,7 @@
  * There is also a special type for the range of values where a string element of a {@code Tuple} begins with a given string.
  * </p>
  */
-@API(API.Status.MAINTAINED)
+@API(API.Status.UNSTABLE)
 public enum EndpointType {
     TREE_START,
     TREE_END,

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/EvaluationContext.java

@@ -37,7 +37,7 @@
  * @see com.apple.foundationdb.record.query.expressions.QueryComponent#eval
  * @see com.apple.foundationdb.record.query.plan.plans.RecordQueryPlan#execute
  */
-@API(API.Status.MAINTAINED)
+@API(API.Status.UNSTABLE)
 public class EvaluationContext {
     @Nonnull
     private final Bindings bindings;

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/EvaluationContextBuilder.java

@@ -33,7 +33,7 @@
  * context.childBuilder().setBinding("x", x).build()
  * </code></pre>
  */
-@API(API.Status.MAINTAINED)
+@API(API.Status.UNSTABLE)
 public class EvaluationContextBuilder {
     @Nonnull
     protected final Bindings.Builder bindings;

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/ExecuteProperties.java

@@ -37,7 +37,7 @@
  * <li>limit on number of key-value pairs scanned</li>
  * </ul>
  */
-@API(API.Status.MAINTAINED)
+@API(API.Status.UNSTABLE)
 public class ExecuteProperties {
     /**
      * A constant representing that no time limit is set.

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/ExecuteState.java

@@ -33,7 +33,7 @@
  * In general, the state object should be constructed by as part of a "root" <code>ExecuteProperties</code> rather than
  * directly by the client.
  */
-@API(API.Status.MAINTAINED)
+@API(API.Status.UNSTABLE)
 public class ExecuteState {
 
     /**

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/FunctionNames.java

@@ -25,7 +25,7 @@
 /**
  * Names of core-supported query functions.
  */
-@API(API.Status.MAINTAINED)
+@API(API.Status.UNSTABLE)
 public class FunctionNames {
 
     /* Aggregate functions */

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/IndexEntry.java

@@ -36,7 +36,7 @@
  * Further, if the key and value were produced by applying an index key expression to a record, this will carry
  * around additional information about the nulls contained in the expression.
  */
-@API(API.Status.MAINTAINED)
+@API(API.Status.UNSTABLE)
 public class IndexEntry {
     private static final NullStandin[] NO_NULLS = new NullStandin[0];
 

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/IndexScanType.java

@@ -34,7 +34,7 @@
  *
  * @see com.apple.foundationdb.record.provider.foundationdb.IndexMaintainer#scan
  */
-@API(API.Status.MAINTAINED)
+@API(API.Status.UNSTABLE)
 public class IndexScanType implements PlanHashable, PlanSerializable {
     @Nonnull
     public static final IndexScanType BY_VALUE = new IndexScanType("BY_VALUE");

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/IndexState.java

@@ -29,7 +29,7 @@
  * These states might differ between record stores that have
  * otherwise identical meta-data.
  */
-@API(API.Status.MAINTAINED)
+@API(API.Status.UNSTABLE)
 public enum IndexState {
     /**
      * This is the default state for an index. It is

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/IsolationLevel.java

@@ -27,13 +27,13 @@
  *
  * @see ExecuteProperties#getIsolationLevel
  */
-@API(API.Status.MAINTAINED)
+@API(API.Status.UNSTABLE)
 public enum IsolationLevel {
 
-    @API(API.Status.STABLE)
+    @API(API.Status.UNSTABLE)
     SNAPSHOT(true),
 
-    @API(API.Status.STABLE)
+    @API(API.Status.UNSTABLE)
     SERIALIZABLE(false)
     ;
 

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/KeyRange.java

@@ -28,7 +28,7 @@
 /**
  * A range within a subspace specified by two byte value endpoints.
  */
-@API(API.Status.MAINTAINED)
+@API(API.Status.UNSTABLE)
 public class KeyRange {
     @Nonnull
     private final byte[] lowKey;

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/LoggableTimeoutException.java

@@ -35,7 +35,7 @@
  * to provide context-specific details that can be logged in a way that better supports troubleshooting later.
  */
 @SuppressWarnings("serial")
-@API(API.Status.MAINTAINED)
+@API(API.Status.UNSTABLE)
 public class LoggableTimeoutException extends TimeoutException implements LoggableKeysAndValues<LoggableTimeoutException> {
     @Nonnull
     private final LoggableKeysAndValuesImpl loggableKeysAndValuesImpl = new LoggableKeysAndValuesImpl();

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/PipelineOperation.java

@@ -32,7 +32,7 @@
  * @see com.apple.foundationdb.record.provider.foundationdb.FDBRecordStoreBase.PipelineSizer
  * @see RecordCursor#mapPipelined
  */
-@API(API.Status.MAINTAINED)
+@API(API.Status.UNSTABLE)
 public class PipelineOperation {
     @Nonnull
     public static final PipelineOperation INDEX_TO_RECORD = new PipelineOperation("INDEX_TO_RECORD");

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/RecordCoreArgumentException.java

@@ -27,7 +27,7 @@
 /**
  * Functional equivalent of <code>IllegalArgumentException</code>.
  */
-@API(API.Status.STABLE)
+@API(API.Status.UNSTABLE)
 public class RecordCoreArgumentException extends RecordCoreException {
     private static final long serialVersionUID = 1;
 

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/RecordCoreException.java

@@ -29,7 +29,7 @@
 /**
  * An exception thrown by the core of the Record Layer.
  */
-@API(API.Status.STABLE)
+@API(API.Status.UNSTABLE)
 @SuppressWarnings("serial")
 public class RecordCoreException extends LoggableException {
     public RecordCoreException(@Nonnull String msg, @Nullable Object ... keyValues) {

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/RecordCoreInterruptedException.java

@@ -30,7 +30,7 @@
  * NOTE: When catching an {@code InterruptedException} and rethrowing as this wrapping exception, Java best practice
  * is to call {@code Thread.currentThread().interrupt()} so that the interrupt is not lost.
  */
-@API(API.Status.STABLE)
+@API(API.Status.UNSTABLE)
 public class RecordCoreInterruptedException extends RecordCoreException {
     private static final long serialVersionUID = 1;
 

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/RecordCoreRetriableTransactionException.java

@@ -28,7 +28,7 @@
 /**
  * An exception from transaction processing that ought to be retried.
  */
-@API(API.Status.STABLE)
+@API(API.Status.UNSTABLE)
 @SuppressWarnings("serial")
 public class RecordCoreRetriableTransactionException extends RecordCoreStorageException {
     public RecordCoreRetriableTransactionException(@Nonnull String msg) {

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/RecordCoreStorageException.java

@@ -28,7 +28,7 @@
 /**
  * Exceptions due to problems with the state of or connection to a particular record store.
  */
-@API(API.Status.STABLE)
+@API(API.Status.UNSTABLE)
 @SuppressWarnings("serial")
 public class RecordCoreStorageException extends RecordCoreException {
     public RecordCoreStorageException(@Nonnull String msg) {

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/RecordCursor.java

@@ -100,7 +100,7 @@
  *
  * @param <T> the type of elements of the cursor
  */
-@API(API.Status.STABLE)
+@API(API.Status.UNSTABLE)
 public interface RecordCursor<T> extends AutoCloseable {
     /**
      * The reason that {@link RecordCursorResult#hasNext()} returned <code>false</code>.
@@ -254,7 +254,7 @@ default RecordCursorResult<T> getNext() {
      * @return a view of this cursor as an {@link RecordCursorIterator}
      */
     @Nonnull
-    @API(API.Status.STABLE)
+    @API(API.Status.UNSTABLE)
     default RecordCursorIterator<T> asIterator() {
         return new RecordCursorIterator<>(this);
     }

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/RecordCursorContinuation.java

@@ -51,7 +51,7 @@
  * {@link com.apple.foundationdb.record.provider.foundationdb.KeyValueCursor}'s continuation.
  * </p>
  */
-@API(API.Status.STABLE)
+@API(API.Status.UNSTABLE)
 public interface RecordCursorContinuation {
     /**
      * Serialize this continuation to a byte array. This method must always return the same array contents (but not

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/RecordCursorIterator.java

@@ -39,7 +39,7 @@
  *
  * @param <T> the type of elements of the cursor
  */
-@API(API.Status.STABLE)
+@API(API.Status.UNSTABLE)
 public class RecordCursorIterator<T> implements AsyncIterator<T>, AutoCloseable {
     @Nonnull
     private final RecordCursor<T> cursor;

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/RecordCursorResult.java

@@ -60,7 +60,7 @@
  *
  * @param <T> the type of result produced when the result includes a value
  */
-@API(API.Status.STABLE)
+@API(API.Status.UNSTABLE)
 public class RecordCursorResult<T> {
 
     @Nonnull

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/RecordFunction.java

@@ -30,7 +30,7 @@
  * A function to be applied to a record as part of query execution.
  * @param <T> the result type of the function
  */
-@API(API.Status.STABLE)
+@API(API.Status.UNSTABLE)
 public abstract class RecordFunction<T> implements PlanHashable, QueryHashable {
 
     @Nonnull