SmallMind

Table of Contents

• Modules
• Module Names
• Module Path And Classpath

SmallMind is a comprehensive multi-module Java framework for building enterprise applications. It provides a curated set of integrations, abstractions, and utilities designed to work together coherently across the full stack of a modern Java application — from persistence and messaging to scheduling, web services, and observability.

The project targets Java 25 and is built with Maven. It integrates with widely-adopted libraries and platforms including Spring, Hibernate, Jakarta EE, Jetty, Netty, Kafka, RabbitMQ, MongoDB, and AWS, providing a consistent programming model across all of them.

Licensed under the GNU Affero General Public License v3 and GNU Lesser General Public License v3.

Modules

The following documentation covers each functional area of the framework:

• Ansible — Configuration and provisioning integration

• Artifact — Artifact management and packaging utilities

• Batch — Batch processing support built on Spring Batch

• Bayeux — CometD/Bayeux protocol support for server-sent events and WebSocket messaging

• Claxon — Alerting and notification infrastructure

• Doppelganger — Object cloning and transformation utilities

• File — File handling and storage abstractions

• JavaFX — JavaFX controls, dialogs, a parabox layout bridge, and live metric charts

• Kafka — Apache Kafka producer and consumer integration

• Liquibase — Database schema migration support via Liquibase

• Memcached — Memcached client integration and caching abstractions

• MongoDB — MongoDB driver integration and document mapping

• NutsNBolts — Core utilities, foundations, and shared infrastructure

• Persistence — JPA/Hibernate persistence layer with QueryDSL support

• Phalanx — Distributed coordination and cluster management

• Quorum — Consensus and distributed locking primitives

• Schedule — Job scheduling via Quartz

• Scribe — Logging infrastructure built on SLF4J and Log4j 2

• Sleuth — Distributed tracing and observability

• Spark — Self-executing jar packaging (Singularity) and OS service distributions (Tanukisoft)

• Testbench — Internal test harness: Dockerized service fixtures, preconditions, and build-file tooling used to test SmallMind itself

• Web — Web layer support including REST (Jersey), Jetty, and WebSocket

Module Names

Every SmallMind jar declares a stable Java module name. The name is org.smallmind. followed by the artifact’s directory path in this repository, and it does not change when the jar file is renamed. A modular consumer refers to an artifact by this name, for example requires org.smallmind.nutsnbolts;.

The Kind column says how the name is declared. An explicit jar ships a module descriptor (module-info.class) that lists its exported packages, the modules it requires, and the packages it opens to reflection; see Module Path And Classpath for what that means for a consumer. An automatic jar carries the name only in its Automatic-Module-Name manifest entry and is an automatic module on the module path. Explicit jars keep the manifest entry as well. On the classpath neither form has any effect.

Artifact	Module name	Kind	Chapter
smallmind-ansible	org.smallmind.ansible	explicit	Ansible
artifact-maven	org.smallmind.artifact.maven	automatic	Artifact
batch-base	org.smallmind.batch.base	explicit	Batch
batch-spring	org.smallmind.batch.spring	explicit	Batch
oumuamua-server-api	org.smallmind.bayeux.oumuamua.server.api	explicit	Bayeux
oumuamua-server-impl	org.smallmind.bayeux.oumuamua.server.impl	explicit	Bayeux
oumuamua-server-spi	org.smallmind.bayeux.oumuamua.server.spi	explicit	Bayeux
claxon-emitter-aws	org.smallmind.claxon.emitter.aws	explicit	Claxon
claxon-emitter-datadog	org.smallmind.claxon.emitter.datadog	explicit	Claxon
claxon-emitter-jmx	org.smallmind.claxon.emitter.jmx	explicit	Claxon
claxon-emitter-message	org.smallmind.claxon.emitter.message	explicit	Claxon
claxon-emitter-noop	org.smallmind.claxon.emitter.noop	explicit	Claxon
claxon-emitter-prometheus	org.smallmind.claxon.emitter.prometheus	explicit	Claxon
claxon-exotic	org.smallmind.claxon.exotic	explicit	Claxon
claxon-http	org.smallmind.claxon.http	explicit	Claxon
claxon-registry	org.smallmind.claxon.registry	explicit	Claxon
file-ephemeral	org.smallmind.file.ephemeral	explicit	File
file-jailed	org.smallmind.file.jailed	explicit	File
smallmind-javafx-extras	org.smallmind.javafx.extras	explicit	JavaFX
kafka-utility	org.smallmind.kafka.utility	explicit	Kafka
smallmind-license-maven-plugin	org.smallmind.license †	automatic	License
smallmind-liquibase	org.smallmind.liquibase	explicit	Liquibase
memcached-cubby	org.smallmind.memcached.cubby	explicit	Memcached
memcached-utility	org.smallmind.memcached.utility	explicit	Memcached
mongodb-throng	org.smallmind.mongodb.throng	explicit	MongoDB
mongodb-utility	org.smallmind.mongodb.utility	explicit	MongoDB
smallmind-nutsnbolts	org.smallmind.nutsnbolts	explicit	NutsNBolts
smallmind-persistence	org.smallmind.persistence	explicit	Persistence
smallmind-phalanx	org.smallmind.phalanx	explicit	Phalanx
smallmind-quorum	org.smallmind.quorum	explicit	Quorum
schedule-base	org.smallmind.schedule.base	explicit	Schedule
schedule-quartz	org.smallmind.schedule.quartz	explicit	Schedule
scribe-apache	org.smallmind.scribe.apache	explicit	Scribe
scribe-ink-indigenous	org.smallmind.scribe.ink.indigenous	explicit	Scribe
scribe-ink-jdk	org.smallmind.scribe.ink.jdk	explicit	Scribe
scribe-ink-log4j	org.smallmind.scribe.ink.log4j	explicit	Scribe
scribe-pen	org.smallmind.scribe.pen	explicit	Scribe
scribe-slf4j	org.smallmind.scribe.slf4j	explicit	Scribe
sleuth-runner	org.smallmind.sleuth.runner	explicit	Sleuth
surefire-sleuth-provider	org.smallmind.sleuth.maven.surefire †	automatic	Sleuth
spark-singularity-boot	org.smallmind.spark.singularity.boot	explicit	Spark
spark-singularity-maven-plugin	org.smallmind.spark.singularity.mojo †	automatic	Spark
spark-tanukisoft-integration	org.smallmind.spark.tanukisoft.integration	automatic	Spark
spark-tanukisoft-maven-plugin	org.smallmind.spark.tanukisoft.mojo †	automatic	Spark
testbench-condition	org.smallmind.testbench.condition	explicit	Testbench
testbench-docker	org.smallmind.testbench.docker	explicit	Testbench
testbench-foundation	org.smallmind.testbench.foundation	explicit	Testbench
testbench-groundwater	org.smallmind.testbench.groundwater	explicit	Testbench
testbench-logger	org.smallmind.testbench.logger	explicit	Testbench
testbench-style	org.smallmind.testbench.style	explicit	Testbench
schema-validation-maven-plugin	org.smallmind.web.schema †	automatic	Web
web-grizzly	org.smallmind.web.grizzly	explicit	Web
web-http	org.smallmind.web.http	explicit	Web
web-jersey	org.smallmind.web.jersey	explicit	Web
web-jetty	org.smallmind.web.jetty	explicit	Web
web-json-doppelganger	org.smallmind.web.json.doppelganger	explicit	Doppelganger
web-json-query	org.smallmind.web.json.query	explicit	Web
web-json-scaffold	org.smallmind.web.json.scaffold	explicit	Web
web-jwt	org.smallmind.web.jwt	explicit	Web

^† Maven plugins and the Surefire provider carry a name so the jar is identifiable, but Maven and Surefire load them through their own class realms. These names are not intended for a consumer’s requires. They stay automatic permanently.

Module Path And Classpath

The classpath is the configuration SmallMind tests against: every module’s test suite runs with its jars on the classpath, where module descriptors are ignored and nothing in this section applies. The rules below apply when an application puts SmallMind jars on the module path. Each chapter’s installation section lists the module-specific details: which optional dependencies its descriptor names, which modules it re-exports, and which of your packages you must open to it.

All or nothing

A named module cannot read the classpath. If a SmallMind jar is on the module path, the third-party jars it uses (Spring, the Jakarta APIs, and so on) must be on the module path too. Jars without a descriptor become automatic modules there.

Optional dependencies are requires static

Every dependency a SmallMind POM marks <optional>true</optional> appears in the descriptor as requires static. Such a module is needed at compile time but is not resolved at run time just because a SmallMind module names it. If its jar is on the module path and nothing in the application requires it, the module is not in the module graph, and the SmallMind code that uses it fails on first use with NoClassDefFoundError, even though the jar is present. Either requires the module in your own descriptor, which is the normal case because you are using that library directly, or add it with --add-modules. Resolving any automatic module resolves every automatic module on the module path, so in practice this failure hits explicit modules (the Jakarta APIs, Bouncy Castle, ASM, and the like) far more often than automatic ones (Spring, FreeMarker, Shiro, AspectJ).

Re-exported and non-re-exported modules

A SmallMind descriptor uses requires transitive for a mandatory explicit module whose types appear in its public signatures, so your module reads that module without naming it. Optional modules are never re-exported, because javac would then demand them when compiling every consumer, and automatic modules are never re-exported, because their names are not guaranteed stable. When a SmallMind signature exposes a type from either kind, require that module yourself.

Reflection

SmallMind descriptors open their own packages to the frameworks that reflect into them, such as Spring and JAXB. Packages that carry resources loaded by path, such as the Spring XML files documented as classpath:org/smallmind/…​, are opened unconditionally so those paths keep working. When a SmallMind utility reflects over your classes, you open your package to the SmallMind module named in that chapter.

Services

Service implementations are declared both with provides in the descriptor and in a META-INF/services file. The module path reads only the first; the classpath reads only the second.