Encapsulate ASM

.github/dependabot.yml

@@ -0,0 +1,15 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "gradle" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"
+    groups:
+      dependencies:
+        patterns:
+          - "*"

.github/workflows/build-and-test.yml

@@ -20,15 +20,16 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
 
       - uses: actions/setup-java@v4
         with:
-          java-version: '17'
           distribution: temurin
+          # First version is for Bosk to use, and the second is for Gradle
+          java-version: |
+            25
+            17
 
-      - uses: gradle/actions/setup-gradle@v3
+      - uses: gradle/actions/setup-gradle@v4
         with:
           cache-read-only: false # OR: ${{ github.ref != 'refs/heads/develop' }}
 

.github/workflows/release.yml

@@ -16,28 +16,24 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
 
       - uses: actions/setup-java@v4
         with:
-          java-version: '17'
           distribution: temurin
-          server-id: ossrh
-          server-username: ${{ secrets.OSSRH_USERNAME }}
-          server-password: ${{ secrets.OSSRH_TOKEN }}
-          gpg-private-key: ${{ secrets.GPG_PRIVATE_KEY }}
+          # First version is for Bosk to use, and the second is for Gradle
+          java-version: |
+            25
+            17
 
-      - uses: gradle/actions/setup-gradle@v3
+      - uses: gradle/actions/setup-gradle@v4
 
       - name: Run Gradle Publish
         run: |
-          ./gradlew spotlessCheck spotBugsMain test publish \
+          ./gradlew smoke publishToSonatype closeAndReleaseSonatypeStagingRepository \
             -Pversion="${{github.event.release.tag_name}}" \
             --info
         env:
           ORG_GRADLE_PROJECT_ossrhUsername: ${{secrets.OSSRH_USERNAME}}
           ORG_GRADLE_PROJECT_ossrhPassword: ${{secrets.OSSRH_TOKEN}}
           ORG_GRADLE_PROJECT_signingKey: ${{secrets.GPG_PRIVATE_KEY}}
           ORG_GRADLE_PROJECT_signingPassword: ${{secrets.GPG_PASSWORD}}
-

README.md

@@ -1,102 +1,55 @@
-![Release status](https://github.com/venasolutions/bosk/actions/workflows/release.yml/badge.svg)
-[![Maven Central](https://img.shields.io/maven-central/v/io.vena/bosk-core)](https://mvnrepository.com/artifact/io.vena/bosk-core)
+![Release status](https://github.com/boskworks/bosk/actions/workflows/release.yml/badge.svg)
+[![Maven Central](https://img.shields.io/maven-central/v/works.bosk/bosk-core)](https://central.sonatype.com/namespace/works.bosk)
 
 # Bosk
 
-![Three inquisitive cartoon trees with eyes](/art/bosk-evergreen-icon.png)
+![Three inquisitive cartoon trees with eyes](/art/bosk-3trees-wide-small.png)
 
-Bosk is a state management library for developing distributed application control-plane logic.
-It's a bit like server-side Redux for Java, but without the boilerplate code.
-(No selectors, no action objects, no reducers.)
+Bosk is a Java library for state management in distributed systems.
+It eases the journey from a simple standalone application to a high-availability clustered replica set
+by supporting reactive, idempotent, deterministic control logic design patterns,
+using an immutable in-memory state tree for ultra-fast reads (~50ns).
 
-Bosk eases the transition from a standalone application to a clustered high-availability replica set,
-by supporting a programming style that minimizes the surprises encountered during the transition.
-Bosk encourages reactive event-triggered closed-loop control logic
-based on a user-defined immutable state tree structure,
-and favours idempotency and determinism.
+First, you start with just the `bosk-core` library, writing your application's control plane logic using Bosk.
+The the built-in integrations with things like Jackson and Spring Boot help you get your application up and running.
 
-State is kept in memory, making reads extremely fast (on the order of 50ns).
-
-Replication is achieved by activating an optional [MongoDB module](bosk-mongo), meaning the hard work of
-change propagation, ordering, durability, consistency, atomicity, and observability,
+Then, when the time comes to turn your standalone application into a high-availability replica set,
+you can bring in the optional [MongoDB library](bosk-mongo).
+The hard work of change propagation, ordering, durability, consistency, atomicity, and observability,
 as well as fault tolerance, and emergency manual state inspection and modification,
 is all delegated to MongoDB: a well-known, reliable, battle-hardened codebase.
-You don't need to trust Bosk to get all these details right:
+You don't even need to trust Bosk to get all these details right:
 all we do is send updates to MongoDB, and maintain the in-memory replica by following the MongoDB change stream.
 
+If you'd rather use SQL instead of MongoDB, there's a [SQL library](bosk-sql) too.
+
 ## Documentation
 - [User's Guide](docs/USERS.md)
 
 ## Getting Started
 
-### Build settings
-
-First, be sure you're compiling Java with the `-parameters` argument.
-
-In Gradle:
-
-```
-dependencies {
-	compileJava {
-		options.compilerArgs << '-parameters'
-	}
-
-	compileTestJava {
-		options.compilerArgs << '-parameters'
-	}
-}
-```
-
-In Maven:
-
-```
-<plugin>
-		<groupId>org.apache.maven.plugins</groupId>
-		<artifactId>maven-compiler-plugin</artifactId>
-		<configuration>
-				<compilerArgs>
-						<arg>-parameters</arg>
-				</compilerArgs>
-		</configuration>
-</plugin>
-```
-
-### Standalone example
-
 The [bosk-core](bosk-core) library is enough to create a `Bosk` object and start writing your application.
 
-The library works particularly well with Java records.
-You can define your state tree's root node as follows:
+You can define your state tree's root node as a java Record, like this:
 
 ```
-import io.vena.bosk.StateTreeNode;
-import io.vena.bosk.Identifier;
+import works.bosk.StateTreeNode;
+import works.bosk.Identifier;
 
 public record ExampleState (
 	// Add fields here as you need them
 	String name
 ) implements StateTreeNode {}
 ```
 
-You can also use classes, especially if you're using Lombok:
-
-```
-@Value
-@Accessors(fluent = true)
-public class ExampleState implements StateTreeNode {
-	// Add fields here as you need them
-	String name;
-}
-```
-
 Now declare your singleton `Bosk` class to house and manage your application state:
 
 ```
-import io.vena.bosk.Bosk;
-import io.vena.bosk.DriverFactory;
-import io.vena.bosk.Reference;
-import io.vena.bosk.annotations.ReferencePath;
-import io.vena.bosk.exceptions.InvalidTypeException;
+import works.bosk.Bosk;
+import works.bosk.DriverFactory;
+import works.bosk.Reference;
+import annotations.works.bosk.ReferencePath;
+import exceptions.works.bosk.InvalidTypeException;
 
 @Singleton // You can use your framework's dependency injection for this
 public class ExampleBosk extends Bosk<ExampleState> {
@@ -121,15 +74,15 @@ public class ExampleBosk extends Bosk<ExampleState> {
 
 	// Start off simple
 	private static DriverFactory<ExampleState> driverFactory() {
-		return Bosk::simpleDriver;
+		return Bosk.simpleDriver();
 	}
 }
 ```
 
 You create an instance of `ExampleBosk` at initialization time,
 typically using your application framework's dependency injection system.
 
-To read state, acquire a `ReadContext`:
+To read state, acquire a `ReadContext`, providing access to a lightweight immutable snapshot of your state tree:
 
 ```
 try (var __ = bosk.readContext()) {
@@ -141,13 +94,16 @@ A read context is intended to be coarse-grained, for example covering an entire
 giving you "snapshot-at-start" semantics and protecting you from race conditions.
 It is an antipattern to use many small read contexts during the course of a single operation.
 
-To modify state, use the `BoskDriver` interface:
+If you're using Spring Boot 3, you can bring in `bosk-spring-boot`
+and set the `bosk.web.maintenance-path` property to get an immediate HTTP REST API to view and edit your state tree.
+
+To modify state programmatically, use the `BoskDriver` interface:
 
 ```
 bosk.driver().submitReplacement(bosk.refs.name(), "everybody");
 ```
 
-During your application's initialization, register a hook to perform an action whenever state changes:
+During your application's initialization, you can register a callback hook to perform an action whenever state changes:
 
 ```
 bosk.registerHook("Name update", bosk.refs.name(), ref -> {
@@ -164,15 +120,15 @@ Use the same version number for all packages.
 
 When you're ready to turn your standalone app into a replica set,
 add [bosk-mongo](bosk-mongo) as a dependency
-and change your Bosk `driverFactory` method to substitute `MongoDriver` in place of `Bosk::simpleDriver`:
+and change your Bosk `driverFactory` method to substitute `MongoDriver` in place of `Bosk.simpleDriver()`:
 
 ```
 import com.mongodb.MongoClientSettings;
 import com.mongodb.ReadConcern;
 import com.mongodb.WriteConcern;
-import io.vena.bosk.drivers.mongo.BsonPlugin;
-import io.vena.bosk.drivers.mongo.MongoDriver;
-import io.vena.bosk.drivers.mongo.MongoDriverSettings;
+import mongo.drivers.works.bosk.BsonSerializer;
+import mongo.drivers.works.bosk.MongoDriver;
+import mongo.drivers.works.bosk.MongoDriverSettings;
 
 ...
 	private static DriverFactory<ExampleState> driverFactory() {
@@ -185,20 +141,20 @@ import io.vena.bosk.drivers.mongo.MongoDriverSettings;
 
 		// For advanced usage, you'll want to inject this object,
 		// but for getting started, we can just create one here.
-		BsonPlugin bsonPlugin = new BsonPlugin();
+		BsonSerializer bsonSerializer = new BsonSerializer();
 
 		return MongoDriver.factory(
 			clientSettings,
 			driverSettings,
-			bsonPlugin);
+			bsonSerializer);
 	}
 ```
 
 To run this, you'll need a MongoDB replica set.
 You can run a single-node replica set using the following `Dockerfile`:
 
 ```
-FROM mongo:4.4
+FROM mongo:7.0
 RUN echo "rs.initiate()" > /docker-entrypoint-initdb.d/rs-initiate.js
 CMD [ "mongod", "--replSet", "rsLonesome", "--port", "27017", "--bind_ip_all" ]
 ```
@@ -215,30 +171,17 @@ provide integrations with other technologies.
 
 The subprojects are listed in [settings.gradle](settings.gradle), and each has its own `README.md` describing what it is.
 
-### Compiler flags
-
-Ensure `javac` is supplied the `-parameters` flag.
-
-This is required because,
-for each class you use to describe your Bosk state, the "system of record" for its structure is its constructor.
-For example, you might define a class with a constructor like this:
-
-```
-public Member(Identifier id, String name) {...}
-```
-
-Based on this, Bosk now knows the names and types of all the "properties" of your object.
-For this to work smoothly, the parameter names must be present in the compiled bytecode.
+### Versioning
 
-### Gradle setup
+In the long run, we'll use the usual semantic versioning.
 
-Each project has its own `build.gradle`.
-Common settings across projects are in custom plugins under the [buildSrc directory](buildSrc/src/main/groovy).
+For 0.x.y releases, all bets are off, and no backward compatibility is guaranteed.
 
-### Versioning
+Releases with four numbers, like a.b.c.d, are "tail" releases containing
+important fixes to old releases.
 
-In the long run, we'll use the usual semantic versioning.
+### Logo
 
-For the 0.x.y releases, treat x as a major release number.
+Logo was derived from this public-domain image: https://openclipart.org/detail/44023/small-trees-bushes
 
-For the 0.0.x releases, all bets are off, and no backward compatibility is guaranteed.
+Modified by Grady Johnson.

bosk-annotations/build.gradle

@@ -1,15 +1 @@
-
-plugins {
-	id 'bosk.development'
-	id 'bosk.maven-publish'
-	id 'com.github.spotbugs' version '5.1.5'
-}
-
-java {
-	sourceCompatibility = '17'
-	targetCompatibility = '17'
-}
-
-repositories {
-	mavenCentral()
-}
+dependencies{}

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

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