qbit-collaboration/docs/CORE-DEPENDENCY.md

Core dependency: after-rollback callbacks

Collaboration's retained-upload and cleanup paths compensate external object storage only after a transaction's rollback is confirmed. They need two methods on com.kingsrook.qqq.backend.core.actions.QBackendTransaction. These are included in QQQ Core 4.1.0-RC.22, which this module imports through the BOM; Core 4.1.0-RC.21 does not declare them.

Required API (reviewed implementation: b6fb2382, third-party-src/qqq-core)

qqq-backend-core, class QBackendTransaction:

public boolean supportsRollbackCallbacks()                  // default: false
public void addAfterRollbackCallback(Runnable callback)      // throws UnsupportedOperationException unless supportsRollbackCallbacks(); Objects.requireNonNull(callback)
protected void runAfterRollbackCallbacks()                   // run once, in order, then clear; exceptions (incl. LinkageError) logged and swallowed

Pending rollback callbacks are preserved when a required operation marks the transaction rollback-only, and run only after confirmed JDBC rollback. A failed physical commit clears them because its outcome is uncertain. Successful commit discards them.

qqq-backend-module-rdbms, class RDBMSTransaction:

@Override public boolean supportsRollbackCallbacks()                 // true
@Override public void addAfterRollbackCallback(Runnable callback)    // super.add...; then rolledBackSinceCommit = false
// rollback()/close(): after connection.rollback() succeeds -> rolledBackSinceCommit = true; runAfterRollbackCallbacks()
// close() rolls back (and so runs callbacks) unless a rollback already happened since the last commit / callback registration

Callers in this module

• attachments/AttachmentsService.storeUpload: refuses an ambient transaction where !supportsRollbackCallbacks(); registers storage compensation.
• attachments/AttachmentCleanupQueue.beginUpload: registers the same cleanup on both addAfterRollbackCallback and addAfterCommitCallback.

Core tests to carry with the change

• Base class: supportsRollbackCallbacks() is false; addAfterRollbackCallback throws UnsupportedOperationException.
• RDBMS: callback runs after rollback(); does not run after commit(); runs when a transaction with a registered callback is closed without commit; a callback registered after an earlier rollback still runs on close; a throwing callback does not stop later callbacks.
• Integration (already in this module, needs the core): attachments/AttachmentTransactionsPostgresTest (needs Docker) incl. interruptedUploadSurvivesLostRollbackCallback.