Let a Customer Edit an Order Without Losing the Save Boundary
A customer opens an order with two lines. They change the Blue cup quantity from 2 to 5 and click Save. The connection drops before the response arrives.
Should the client save again? What if another user edited the order while the page was open? What if the customer removes a line from the submitted JSON?
Our protected order-editing guide
walks through these cases using a downloadable Java/SQLite example. It starts
with the open and submit operations, then shows what the application must do
behind them. The example uses the source preview of the optional
SecureDocumentReferenceModule.
Open a business document
Here, a document means an editable view of business data. The order has a business ID, an item list and a protected token; there is no Word or PDF file.
After the application installs the module and registers its order document service, an open endpoint calls:
ContextualDocument opened = ctx.openDocument(new OpenRequest(
"Order", "ORDER-1001", "edit-order-items", Duration.ofMinutes(15)));
The client receives the body and its opaque token. The body contains readable
product names, SKUs and quantities, with row aliases such as item:0. The token
protects the server's mapping from those aliases to the issued rows, versions
and allowed edits. Copying Alice's document into Bob's session does not make it
Bob's document.
Submit the change, then keep the returned document
The client changes quantity to 5, retains both rows and their read-only fields, and sends the body with its original token and a new command ID. The submit endpoint constructs:
AcceptedDocument accepted = ctx.acceptDocument(new AcceptRequest(
"Order", "edit-order-items",
new SubmittedDocument(businessId, documentToken, commandId, editedBody)));
The application service checks current permission, the issued surface and current versions, then commits the order, line changes and command receipt in one SQL transaction. The guide includes that complete service; installing the crypto module alone does not supply business persistence or editable-field rules.
A successful save returns accepted.document(), the next editable body and
token. The UI uses that returned document for its next edit.
Handle a lost response and a stale page differently
If the response is lost, retry the same submitted request with the same command ID, token and body. While the token remains valid and current permission allows it, the example returns the first committed result without another write. Changing the payload under the same command ID is a command conflict.
If a different command submits the older document after the order changed, the example rejects it as a version conflict. Reload the current document and reconcile the user's change. A fresh command ID does not make an old snapshot current.
Permission remains current too: after the demo revokes Alice's edit permission, she cannot open another document or replay the saved command.
Make deletion an explicit edit
To remove a line, the client uses the latest document, removes that row from
items, and puts its issued alias in removedRefs. The example permits that
operation because its protected relation is complete and allows removal.
Omitting a row without that declaration is rejected. This matters when a page renders only part of a graph or a client accidentally drops an array element: missing JSON is not enough to infer an intentional deletion.
Put the transaction in the example, not just the explanation
The executable deliberately aborts a child update after the root update has started. It checks that the root revision, quantity and receipt all remain unchanged. Removing the injected failure lets the exact request succeed.
That is the reason to keep the domain service visible in the guide: a protected token can authenticate a snapshot, but the application must still connect validation, persistence and the command receipt to one real transaction.
Start with the runnable guide for the three downloads, setup command, request bodies and expected output. Its execution record identifies the tested source. It is a JDBC source-preview example, not a generated Q/E or public-package release claim. Broader runtime availability stays in the dated status page.
