Merge branch 'develop' into develop

Author: prdoyle

bosk-annotations/build.gradle

@@ -1,7 +1,7 @@
 
 plugins {
 	id 'bosk.maven-publish'
-	id 'com.github.spotbugs' version '5.1.5'
+	id 'com.github.spotbugs' version '6.1.2'
 }
 
 java {

bosk-annotations/src/main/java/module-info.java

@@ -0,0 +1,3 @@
+module works.bosk.annotations {
+	exports works.bosk.annotations;
+}

bosk-annotations/src/main/java/works/bosk/annotations/DerivedRecord.java

@@ -16,14 +16,14 @@
  *
  * <pre>
  *     public class MyDTO implements StateTreeNode {
- *        {@code @DeserializationPath("a/b/c")}
+ *        &#064;DeserializationPath("a/b/c")
  *        MyObject field;
  *     }
  *
- *     public class MyObject extends ReflectiveEntity&lt;MyObject> {
- *         Reference&lt;MyObject> self;
- *         Optional&lt;MyObject> nested;
- *     }
+ *     public record MyObject(
+ *         &#064;Self Reference&lt;MyObject> self,
+ *         Optional&lt;MyObject> nested
+ *     ) extends Entity {}
  * </pre>
  *
  * If we deserialize an instance <code>x</code> of <code>MyDTO</code>, then

bosk-annotations/src/main/java/works/bosk/annotations/DeserializationPath.java

@@ -2,3 +2,4 @@
 
 This is the subproject for the published `bosk-core` library,
 containing the minimum essential functionality of Bosk.
+Its use is documented in the [User's Guide](../docs/USERS.md).

bosk-bson/README.md

@@ -3,7 +3,7 @@ plugins {
 	id 'bosk.development'
 	id 'bosk.maven-publish'
 	id 'info.solidsoft.pitest' version '1.7.4'
-	id 'com.github.spotbugs' version '5.1.5'
+	id 'com.github.spotbugs' version '6.1.2'
 }
 
 java {

bosk-bson/build.gradle

@@ -0,0 +1,15 @@
+module works.bosk.core {
+	requires org.jetbrains.annotations;
+	requires org.objectweb.asm.util;
+	requires org.pcollections;
+	requires org.slf4j;
+	requires works.bosk.annotations;
+	requires static lombok;
+
+	exports works.bosk;
+	exports works.bosk.drivers;
+	exports works.bosk.exceptions;
+	exports works.bosk.util;
+	exports works.bosk.bytecode to works.bosk.jackson;
+	exports works.bosk.logging to works.bosk.mongo, works.bosk.logback;
+}

bosk-core/README.md

@@ -36,6 +36,7 @@
 import works.bosk.exceptions.ReferenceBindingException;
 import works.bosk.util.Classes;
 
+import static java.lang.Thread.holdsLock;
 import static java.util.Collections.unmodifiableCollection;
 import static java.util.Objects.requireNonNull;
 import static java.util.UUID.randomUUID;
@@ -109,9 +110,9 @@ public class Bosk<R extends StateTreeNode> implements BoskInfo<R> {
 	@SuppressWarnings("this-escape")
 	public Bosk(String name, Type rootType, DefaultRootFunction<R> defaultRootFunction, DriverFactory<R> driverFactory) {
 		this.name = name;
+		this.pathCompiler = PathCompiler.withSourceType(rootType); // Required before rootRef
 		this.localDriver = new LocalDriver(defaultRootFunction);
 		this.rootRef = new RootRef(rootType);
-		this.pathCompiler = PathCompiler.withSourceType(rootType);
 		try {
 			validateType(rootType);
 		} catch (InvalidTypeException e) {
@@ -223,9 +224,9 @@ public <T> void submitConditionalReplacement(Reference<T> target, T newValue, Re
 		}
 
 		@Override
-		public <T> void submitInitialization(Reference<T> target, T newValue) {
+		public <T> void submitConditionalCreation(Reference<T> target, T newValue) {
 			assertCorrectBosk(target);
-			downstream.submitInitialization(target, newValue);
+			downstream.submitConditionalCreation(target, newValue);
 		}
 
 		@Override
@@ -277,11 +278,13 @@ private <T> void assertCorrectBosk(Reference<T> target) {
 	 * When it comes to hooks, this provides three guarantees:
 	 *
 	 * <ol><li>
-	 * All updates submitted to this driver are applied to the Bosk state in order.
+	 * Updates submitted to this driver are applied to the Bosk state in the order they were submitted.
 	 * </li><li>
 	 * Hooks are run sequentially: no hook begins until the previous one finishes.
 	 * </li><li>
-	 * Hooks are run in breadth-first fashion.
+	 * Hooks are run in <em>breadth-first</em> fashion:
+	 * hooks triggered by one update run before any hooks triggered by subsequent updates,
+	 * even if those hooks themselves submit more updates.
 	 * </li></ol>
 	 *
 	 * Satisfying all of these simultaneously is tricky, especially because we can't just put
@@ -320,7 +323,7 @@ public <T> void submitReplacement(Reference<T> target, T newValue) {
 		}
 
 		@Override
-		public <T> void submitInitialization(Reference<T> target, T newValue) {
+		public <T> void submitConditionalCreation(Reference<T> target, T newValue) {
 			synchronized (this) {
 				boolean preconditionsSatisfied;
 				try (@SuppressWarnings("unused") ReadContext executionContext = supersedingReadContext()) {
@@ -404,7 +407,8 @@ void triggerEverywhere(HookRegistration<?> reg) {
 		/**
 		 * @return false if the update was ignored
 		 */
-		private synchronized <T> boolean tryGraftReplacement(Reference<T> target, T newValue) {
+		private <T> boolean tryGraftReplacement(Reference<T> target, T newValue) {
+			assert holdsLock(this);
 			Dereferencer dereferencer = dereferencerFor(target);
 			try {
 				LOGGER.debug("Applying replacement at {}", target);
@@ -428,7 +432,8 @@ private synchronized <T> boolean tryGraftReplacement(Reference<T> target, T newV
 		/**
 		 * @return false if the update was ignored
 		 */
-		private synchronized <T> boolean tryGraftDeletion(Reference<T> target) {
+		private <T> boolean tryGraftDeletion(Reference<T> target) {
+			assert holdsLock(this);
 			Path targetPath = target.path();
 			assert !targetPath.isEmpty();
 			Dereferencer dereferencer = dereferencerFor(target);
@@ -977,6 +982,11 @@ public <TT> Reference<Reference<TT>> thenReference(Class<TT> targetClass, Path p
 			return this.then(Classes.reference(targetClass), path);
 		}
 
+		@Override
+		public <TT extends VariantCase> Reference<TaggedUnion<TT>> thenTaggedUnion(Class<TT> variantCaseClass, Path path) throws InvalidTypeException {
+			return this.then(Classes.taggedUnion(variantCaseClass), path);
+		}
+
 		@Override
 		public BoskDiagnosticContext diagnosticContext() {
 			return diagnosticContext;
@@ -1035,6 +1045,11 @@ public final <TT> Reference<Reference<TT>> thenReference(Class<TT> targetClass,
 			return rootReference().thenReference(targetClass, path.then(segments));
 		}
 
+		@Override
+		public <TT extends VariantCase> Reference<TaggedUnion<TT>> thenTaggedUnion(Class<TT> variantCaseClass, String... segments) throws InvalidTypeException {
+			return rootReference().thenTaggedUnion(variantCaseClass, path.then(segments));
+		}
+
 		@SuppressWarnings("unchecked")
 		@Override
 		public final <TT> Reference<TT> enclosingReference(Class<TT> targetClass) {
@@ -1103,7 +1118,7 @@ public final String toString() {
 	 * A {@link Reference} with no unbound parameters.
 	 */
 	private sealed class DefiniteReference<T> extends ReferenceImpl<T> {
-		@Getter(lazy = true) private final Dereferencer dereferencer = compileVettedPath(path);
+		private final Dereferencer dereferencer = compileVettedPath(path);
 
 		public DefiniteReference(Path path, Type targetType) {
 			super(path, targetType);
@@ -1131,6 +1146,10 @@ public void forEachValue(BiConsumer<T, BindingEnvironment> action, BindingEnviro
 				action.accept(value, existingEnvironment);
 			}
 		}
+
+		public Dereferencer dereferencer() {
+			return this.dereferencer;
+		}
 	}
 
 	/**