chore: Add interfaces for synchronizer/initializer.

Author: kinyoklion

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/Version.java

@@ -4,7 +4,5 @@ abstract class Version {
   private Version() {}
 
   // This constant is updated automatically by our Gradle script during a release, if the project version has changed
-  // x-release-please-start-version
   static final String SDK_VERSION = "7.10.2";
-  // x-release-please-end
 }

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/datasources/FDv2SourceResult.java

@@ -0,0 +1,97 @@
+package com.launchdarkly.sdk.server.datasources;
+import com.launchdarkly.sdk.internal.fdv2.sources.FDv2ChangeSet;
+import com.launchdarkly.sdk.server.interfaces.DataSourceStatusProvider;
+
+/**
+ * This type is currently experimental and not subject to semantic versioning.
+ * <p>
+ * The result type for FDv2 initializers and synchronizers. An FDv2 initializer produces a single result, while
+ * an FDv2 synchronizer produces a stream of results.
+ */
+public class FDv2SourceResult {
+    public enum State {
+        /**
+         * The data source has encountered an interruption and will attempt to reconnect.
+         */
+        INTERRUPTED,
+        /**
+         * The data source has been shut down and will not produce any further results.
+         */
+        SHUTDOWN,
+        /**
+         * The data source has encountered a terminal error and will not produce any further results.
+         */
+        TERMINAL_ERROR,
+        /**
+         * The data source has been instructed to disconnect and will not produce any further results.
+         */
+        GOODBYE,
+    }
+
+    public enum ResultType {
+        /**
+         * The source has emitted a change set. This implies that the source is valid.
+         */
+        CHANGE_SET,
+        /**
+         * The source is emitting a status which indicates a transition from being valid to being in some kind
+         * of error state. The source will emit a CHANGE_SET if it becomes valid again.
+         */
+        STATUS,
+    }
+
+    /**
+     * Represents a change in the status of the source.
+     */
+    public static class Status {
+        private final State state;
+        private final DataSourceStatusProvider.ErrorInfo errorInfo;
+
+        public State getState() {
+            return state;
+        }
+
+        public DataSourceStatusProvider.ErrorInfo getErrorInfo() {
+            return errorInfo;
+        }
+
+        public Status(State state, DataSourceStatusProvider.ErrorInfo errorInfo) {
+            this.state = state;
+            this.errorInfo = errorInfo;
+        }
+    }
+    private final FDv2ChangeSet changeSet;
+    private final Status status;
+
+    private final ResultType resultType;
+
+    private FDv2SourceResult(FDv2ChangeSet changeSet, Status status, ResultType resultType) {
+        this.changeSet = changeSet;
+        this.status = status;
+        this.resultType = resultType;
+    }
+
+    public static FDv2SourceResult interrupted(DataSourceStatusProvider.ErrorInfo errorInfo) {
+        return new FDv2SourceResult(null, new Status(State.INTERRUPTED, errorInfo), ResultType.STATUS);
+    }
+
+    public static FDv2SourceResult shutdown(DataSourceStatusProvider.ErrorInfo errorInfo) {
+        return new FDv2SourceResult(null, new Status(State.SHUTDOWN, errorInfo), ResultType.STATUS);
+    }
+
+     public static FDv2SourceResult changeSet(FDv2ChangeSet changeSet) {
+        return new FDv2SourceResult(changeSet, null, ResultType.CHANGE_SET);
+     }
+
+     public ResultType getResultType() {
+        return resultType;
+     }
+
+     public Status getStatus() {
+        return status;
+     }
+
+     public FDv2ChangeSet getChangeSet() {
+        return changeSet;
+     }
+}

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/datasources/Initializer.java

@@ -0,0 +1,57 @@
+package com.launchdarkly.sdk.server.datasources;
+
+import java.util.concurrent.CompletableFuture;
+
+/**
+ * This type is currently experimental and not subject to semantic versioning.
+ * <p>
+ * Interface for an asynchronous data source initializer.
+ * <p>
+ * An initializer will run and produce a single result. If the initializer is successful, then it should emit a result
+ * containing a change set. If the initializer fails, then it should emit a status result describing the error.
+ * <p>
+ *           [START]
+ *              │
+ *              ▼
+ *        ┌─────────────┐
+ *        │   RUNNING   │──┐
+ *        └─────────────┘  │
+ *          │   │   │   │  │
+ *          │   │   │   │  └──► SHUTDOWN ───► [END]
+ *          │   │   │   │
+ *          │   │   │   └─────► INTERRUPTED ───► [END]
+ *          │   │   │
+ *          │   │   └─────────► CHANGESET ───► [END]
+ *          │   │
+ *          │   └─────────────► TERMINAL_ERROR ───► [END]
+ *          │
+ *          └─────────────────► GOODBYE ───► [END]
+ *
+ * <code>
+ * stateDiagram-v2
+ *     [*] --> RUNNING
+ *     RUNNING --> SHUTDOWN
+ *     RUNNING --> INTERRUPTED
+ *     RUNNING --> CHANGESET
+ *     RUNNING --> TERMINAL_ERROR
+ *     RUNNING --> GOODBYE
+ *     SHUTDOWN --> [*]
+ *     INTERRUPTED --> [*]
+ *     CHANGESET --> [*]
+ *     TERMINAL_ERROR --> [*]
+ *     GOODBYE --> [*]
+ * </code>
+ */
+public interface Initializer {
+    /**
+     * Run the initializer to completion.
+     * @return The result of the initializer.
+     */
+    CompletableFuture<FDv2SourceResult> run();
+
+    /**
+     * Shutdown the initializer. The initializer should emit a status event with a SHUTDOWN state as soon as possible.
+     * If the initializer has already completed, or is in the process of completing, this method should have no effect.
+     */
+    void shutdown();
+}

lib/sdk/server/src/main/java/com/launchdarkly/sdk/server/datasources/Synchronizer.java

@@ -0,0 +1,63 @@
+package com.launchdarkly.sdk.server.datasources;
+
+import java.util.concurrent.CompletableFuture;
+
+/**
+ * This type is currently experimental and not subject to semantic versioning.
+ * <p>
+ * Interface for an asynchronous data source synchronizer.
+ * <p>
+ * A synchronizer will run and produce a stream of results. When it experiences a temporary failure, it will emit a
+ * status event indicating that it is INTERRUPTED, while it attempts to resolve its failure. When it receives data,
+ * it should emit a result containing a change set. When the data source is shut down gracefully, it should emit a
+ * status event indicating that it is SHUTDOWN.
+ * <p>
+ *           [START]
+ *              │
+ *              ▼
+ *        ┌─────────────┐
+ *     ┌─►│   RUNNING   │──┐
+ *     │  └─────────────┘  │
+ *     │   │   │   │   │   │
+ *     │   │   │   │   │   └──► SHUTDOWN ───► [END]
+ *     │   │   │   │   │
+ *     │   │   │   │   └──────► TERMINAL_ERROR ───► [END]
+ *     │   │   │   │
+ *     │   │   │   └──────────► GOODBYE ───► [END]
+ *     │   │   │
+ *     │   │   └──────────────► CHANGE_SET ───┐
+ *     │   │                                  │
+ *     │   └──────────────────► INTERRUPTED ──┤
+ *     │                                      │
+ *     └──────────────────────────────────────┘
+ * <p>
+ * <code>
+ * stateDiagram-v2
+ *     [*] --> RUNNING
+ *     RUNNING --> SHUTDOWN
+ *     SHUTDOWN --> [*]
+ *     RUNNING --> TERMINAL_ERROR
+ *     TERMINAL_ERROR --> [*]
+ *     RUNNING --> GOODBYE
+ *     GOODBYE --> [*]
+ *     RUNNING --> CHANGE_SET
+ *     CHANGE_SET --> RUNNING
+ *     RUNNING --> INTERRUPTED
+ *     INTERRUPTED --> RUNNING
+ * </code>
+ */
+interface Synchronizer {
+    /**
+     * Get the next result from the stream.
+     * @return a future that will complete when the next result is available
+     */
+    CompletableFuture<FDv2SourceResult> next();
+
+    /**
+     * Shutdown the synchronizer. The synchronizer should emit a status event with a SHUTDOWN state as soon as possible
+     * and then stop producing further results. If the synchronizer involves a resource, such as a network connection,
+     * then those resources should be released.
+     * If the synchronizer has already completed, or is in the process of completing, this method should have no effect.
+     */
+    void shutdown();
+}