diff --git a/bosk-core/src/main/java/io/vena/bosk/Bosk.java b/bosk-core/src/main/java/io/vena/bosk/Bosk.java index 09f9f782..1795d959 100644 --- a/bosk-core/src/main/java/io/vena/bosk/Bosk.java +++ b/bosk-core/src/main/java/io/vena/bosk/Bosk.java @@ -933,7 +933,7 @@ public final boolean equals(Object obj) { if (obj == null) { return false; } - if (!(obj instanceof @SuppressWarnings({"rawtypes"})Reference other)) { + if (!(obj instanceof Reference other)) { return false; } diff --git a/bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/Demultiplexer.java b/bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/Demultiplexer.java index ecdd1c85..f213686b 100644 --- a/bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/Demultiplexer.java +++ b/bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/Demultiplexer.java @@ -10,6 +10,9 @@ import static java.util.Objects.requireNonNull; +/** + * De-interlaces change stream events associated with different transactions. + */ class Demultiplexer { private final Map>> transactionsInProgress = new ConcurrentHashMap<>(); diff --git a/bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/FormatMisconfigurationException.java b/bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/FormatMisconfigurationException.java index 38434eff..2840beff 100644 --- a/bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/FormatMisconfigurationException.java +++ b/bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/FormatMisconfigurationException.java @@ -1,5 +1,9 @@ package io.vena.bosk.drivers.mongo; +/** + * Indicates that an error was found in a + * {@link MongoDriverSettings.DatabaseFormat DatabaseFormat} object. + */ public class FormatMisconfigurationException extends IllegalArgumentException { public FormatMisconfigurationException(String s) { super(s); diff --git a/bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/Manifest.java b/bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/Manifest.java index 8a9d03a1..402765e6 100644 --- a/bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/Manifest.java +++ b/bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/Manifest.java @@ -4,11 +4,21 @@ import io.vena.bosk.drivers.mongo.MongoDriverSettings.DatabaseFormat; import java.util.Optional; +/** + * Defines the format of the manifest document, which is stored in the database + * to describe the database contents. + */ public record Manifest( Integer version, Optional sequoia, Optional pando ) implements StateTreeNode { + public Manifest { + if (sequoia.isPresent() == pando.isPresent()) { + throw new IllegalArgumentException("Exactly one format (sequoia or pando) must be specified in manifest"); + } + } + public record EmptyNode() implements StateTreeNode { } public static Manifest forSequoia() { diff --git a/bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/MongoDriver.java b/bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/MongoDriver.java index 6502e349..878fb9fd 100644 --- a/bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/MongoDriver.java +++ b/bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/MongoDriver.java @@ -8,6 +8,17 @@ import io.vena.bosk.drivers.mongo.status.MongoStatus; import java.io.IOException; +/** + * A {@link BoskDriver} that maintains the bosk state in a MongoDB database. + * Multiple bosks, potentially in multiple separate processes, + * can be configured to use the same database, thereby creating a replica set + * with all bosks sharing the same state and receiving updates from each other. + *

+ * + * For convenience, if the database does not exist at the time of initialization, + * this driver will create it and populate it with the state returned by calling + * {@link BoskDriver#initialRoot} on the downstream driver. + */ public sealed interface MongoDriver extends BoskDriver permits MainDriver, FormatDriver { diff --git a/bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/UninitializedCollectionException.java b/bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/UninitializedCollectionException.java index 1a0d413d..b173b1e7 100644 --- a/bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/UninitializedCollectionException.java +++ b/bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/UninitializedCollectionException.java @@ -1,5 +1,15 @@ package io.vena.bosk.drivers.mongo; +/** + * Indicates that the database has been found to be in a state that + * could be considered "uninitialized", in the sense that we are permitted + * to respond by automatically initializing the database. + *

+ * This is not the same as discovering that the database is simply in some unexpected state, + * in which case other exceptions may be thrown and the driver would likely disconnect + * rather than overwrite the database contents. + * Rather, we must have a fairly high degree of certainty that we're ok to start fresh. + */ class UninitializedCollectionException extends Exception { public UninitializedCollectionException() { } diff --git a/bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/UnprocessableEventException.java b/bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/UnprocessableEventException.java index 1f21e408..27e62ef9 100644 --- a/bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/UnprocessableEventException.java +++ b/bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/UnprocessableEventException.java @@ -3,7 +3,7 @@ import com.mongodb.client.model.changestream.OperationType; /** - * Indicate that no {@link FormatDriver} could cope with a particular + * Indicates that no {@link FormatDriver} could cope with a particular * change stream event. The framework responds with a (potentially expensive) * reload operation that avoids attempting to re-process that event; * in other words, using resume tokens would never be appropriate for these. diff --git a/bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/UnrecognizedFormatException.java b/bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/UnrecognizedFormatException.java index 2c1da437..46242160 100644 --- a/bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/UnrecognizedFormatException.java +++ b/bosk-mongo/src/main/java/io/vena/bosk/drivers/mongo/UnrecognizedFormatException.java @@ -1,5 +1,9 @@ package io.vena.bosk.drivers.mongo; +/** + * Indicates that we are unable to interpret the contents of + * the manifest document found in the database. + */ class UnrecognizedFormatException extends Exception { public UnrecognizedFormatException(String message) { super(message);