QQQ 4.0

QQQ 4.0 release and migration

QQQ 4.0 release. Final 4.0.0 is available. See QQQ 4.0 for release scope and migration guidance.

4.0 release status

QQQ 4.0.0 is available, with source tagged v4.0.0. Use an exact published version and verify availability in Maven Central.

Release contents

Component	4.0 release version or scope
QQQ core	4.0.0; 18 coordinates: two POMs and 16 JAR modules
BOM	com.kingsrook.qqq:qqq-bom-pom
QBit build parent	com.kingsrook:qbit-build-parent:2.0.0; imports core 4.0.0
Material Dashboard	0.41.0, independently versioned
Sample and starter	Source applications for the matching QQQ version
QBit templates	Application, data, and extension scaffolds

Existing production QBits, qctl, and frontend replacement work are outside this release train. A catalog entry is not proof of 4.0 compatibility. Check each dependency's release notes, POM, and tests.

Local app quickstart

The app-source quickstart uses the signed quickstart-4.0.0 source tag with published QQQ 4.0.0 and the prebuilt Next dashboard 0.1.0. It clones editable Java sample code, compiles that application with Maven Wrapper and seeds local H2 data. Run the launcher in Bash on macOS, Linux or Windows WSL, not native PowerShell. It requires a Java 21 JDK, Git, curl, unzip and a running Docker daemon; it does not require installing Maven or Node.js or setting up a database/account. Next is the default for this quickstart and remains a compatible preview with widget parity limits. The separate framework-contributor path retains Material Dashboard 0.41.0. Multi-component process steps that pair a primary record list with a form summary currently omit the accompanying summary (#645).

The measured cold-start run reached the seeded Next page in 43.6 seconds, including the bootstrap, source, wrapper, dependencies, image downloads and build on the stated fresh Linux VM. The 90-second target starts after prerequisites are installed; it is not a guarantee for every machine or connection.

Breaking changes

• Javalin packages move from com.kingsrook.qqq.backend.javalin to com.kingsrook.qqq.middleware.javalin.
• PicoCLI packages move from com.kingsrook.qqq.frontend.picocli to com.kingsrook.qqq.middleware.picocli.
• Deprecated APIs are removed; update overrides and method calls to their replacement signatures.
• API-shape cleanups affect context handling, filters, field conversions, backend variants, metadata customizers, route providers, builders, and related utilities.

Use the tagged 4.0 migration guide together with the changelog.

Migration highlights

The following highlights describe the 4.0.0 release. Consult the tagged source manual for the complete per-API contract and provider limitations.

Javalin registration

QQQ 4.0 uses Java 21, Javalin 7.2.3 and Jetty 12.1.13. Register routes and before/after/error handlers during configuration. Move provider registration from acceptJavalinService(Javalin) to acceptJavalinConfig(JavalinConfig), using config.routes. Replace direct config.router.apiBuilder(...) calls with config.routes.apiBuilder(...); EndpointGroup keeps its package and signature.

For a server-level registration callback, replace a route-registering withJavalinConfigurationCustomizer call with:

server.withJavalinConfigCustomizer(config ->
   config.routes.get("/custom/status", ctx -> ctx.result("ready")));

The older service customizer and acceptJavalinService remain observation hooks; they cannot register Javalin 7 handlers. Preserve authentication and path scopes when moving handlers. Default process-backed routes now supply method as a String such as "GET"; use input.getValueString("method"), not a HandlerType cast. Keep both Jetty core and EE10 dependencies aligned through the release's dependency management.

Data and application behavior

• Review joined READ permissions and USER-personalized metadata in the interactive record APIs. Exposing a relationship does not grant record access; hidden fields and password masking still apply. The root table name is reserved and cannot also be a join alias; use distinct aliases for self joins.
• Preserve association omission versus empty replacement. Check child operation grants and returned errors. Recursive writes do not imply automatic batch rollback or distributed atomicity.
• USER_ID defaults apply on INSERT/UPDATE, including omitted sparse-update values; reads preserve stored blanks. RDBMS DATE/TIME preserve calendar/wall-clock values, while zone-less DATE_TIME storage uses UTC. Existing timestamp data is not rewritten automatically.
• Metadata directories must contain valid metadata files only; loading errors fail startup. Use the sample acceptance profile for its browser and packaged-launcher checks.
• Custom backends must review native write lookup and association discovery contracts. MongoDB write lookups require native ObjectId identities; this does not establish full native String-key CRUD. Query, Count and Aggregate retain provider-specific operators, result types and lifecycle limits.

Reporting and process defaults

Application API process calls and built-in saved-report generation retain their SYSTEM defaults. Permission to run a developer-defined named report can authorize its server-defined sources without granting raw-table READ. Setting ReportInput to USER alone does not uniformly propagate source-access checks into nested count/query inputs; applications can configure query policy with DataSourceQueryInputCustomizer. API asynchronous result ownership is bound independently of process input source.

Automatic report-source propagation, additional source-permission/privacy checks, and application API process provenance changes are deferred in #448 and #451. Saved-report storage/email fields retain their existing editability; the proposed restriction is deferred in #453. Applications remain responsible for the permissions and configuration they expose.

Additional rendering-ownership and schedule-management policies (#446, #452), cross-instance API process-cache identity (#449) and scheduled caller-session restoration (#450) remain deferred. These deferred changes are not included in 4.0.

Saved-report storage and failures

The correction for #458 finishes and closes the generated temporary file before opening the archive destination. It then copies the completed file through the existing StorageAction.createOutputStream API. Custom storage backends need no new method. A generation failure therefore leaves the prior archive untouched; a later copy or destination-close failure can still change it. Atomic replacement is not guaranteed.

The proposed atomic storeFile storage API (#459), history-validation and primary-error changes (#460), and preserving COMPLETE after delivery failure (#461) are deferred. A caught delivery failure can mark the render FAILED when its history update succeeds, even if archive bytes were already stored. Cancellation requests do not guarantee that generation or delivery stops; additional report/export cancellation boundaries are deferred in #479. Inspect storage before retrying; a failed status does not prove that no file was stored.

These highlights do not imply all-provider parity or complete sample feature coverage. The 48 source-coverage groups and separate train.bom coverage group (#627) are deferred beyond 4.0 under #534; the feature ledger continues to report those gaps separately from release acceptance.

Upgrade workflow

Create an upgrade branch, import the correct BOM, keep the dashboard version explicit, and inspect mvn dependency:tree for mixed framework versions. Run mvn clean verify, then test your packaged application against the intended database and authentication provider. Verify critical processes, API clients, reports, scheduler work, and denied access in staging.

Validate the exact release with your application before production adoption. Keep an exact artifact version and a recoverable application/data rollback plan. Changing only a POM version cannot reverse schema or data changes.

Licensing

Read the LICENSE, NOTICE, and source headers for the exact artifacts and component versions you use. The website does not override those terms or grant a uniform license to every QBit. See Licensing.

Source review

The tagged source and manual, migration guide, and matching release-member READMEs are the authoritative implementation references. Source tags and Maven artifacts identify separate parts of the release; use their exact versions.

Build locally · Release flow · Compatibility