GH-4043: fix(dboe): don't poison shared buffer on block slice

[m3l0n-sq]

GitHub issue resolved #4043

Pull request Description:

Problem

BlockAccessMapped.getByteBuffer slices a block out of the shared per-segment MappedByteBuffer by mutating that buffer's state:

segBuffer.position(segOff);
segBuffer.limit(segOff + blockSize);   // shrinks the SHARED buffer's limit
ByteBuffer dst = segBuffer.slice();
segBuffer.limit(segBuffer.capacity()); // restore -- but NOT in a finally

The restore is not exception-safe. If any throwable escapes between the limit-shrink and the restore — realistically an OutOfMemoryError raised at the slice() allocation under heap pressure — the segment buffer is left with a shrunken limit. From then on, every access to a higher block in that segment fails:

java.lang.IllegalArgumentException: newPosition > limit: (6389760 > 2588672)
    at org.apache.jena.dboe.base.file.BlockAccessMapped.getByteBuffer(BlockAccessMapped.java:155)
    at org.apache.jena.dboe.base.file.BlockAccessMapped.read(BlockAccessMapped.java:93)
    ...
    at org.apache.jena.dboe.trans.bplustree.BPTreeNode.get(BPTreeNode.java:163)

The failure is self-sustaining: the poisoned position(segOff) call throws before reaching the line that would restore the limit. (An access to a block below the stuck limit happens to heal the buffer, but a hot B+Tree node above it keeps failing indefinitely.)

Observed in production as a TDB2 dataset returning HTTP 500 for every query touching one B+Tree index, persisting until JVM restart. The reported limit was not segment-aligned (2588672 = 315 * 8192 + 8192) — exactly a leftover slice limit, not a file-length artifact. This failure presents exactly like on-disk index corruption, but nothing on disk is wrong — which matters, because the standard advice for this signature (dump/reload the database) is unnecessary here; a restart clears it.

The existing in-code comment anticipated the hazard:

// Shouldn't (ha!) happen because the second "limit" resets

Fix

Slice through a cleared duplicate, using the absolute slice(index, length):

ByteBuffer dst = segBuffer.duplicate().clear().slice(segOff, blockSize);

This neither mutates nor depends on the shared buffer's position/limit, so the poisoned state can no longer be created — and reads keep working even if the buffer state were corrupted by other means.

Why not plain slice(index, length) on the shared buffer? Because slice(index, length) validates against the buffer's current limit, not its capacity — it would prevent creating the poison but still fail on an already-poisoned buffer. The cleared duplicate makes the access path fully state-independent.

Semantics of the returned slice are unchanged: position 0, limit and capacity = blockSize, big-endian byte order, view of the same backing region. Cost is one extra view object per block access (the previous code already allocated one view per access).

The catch (IllegalArgumentException ...) diagnostic block is widened to RuntimeException, since the absolute slice reports range violations as IndexOutOfBoundsException.

The identical code exists in TDB1 (org.apache.jena.tdb1.base.file.BlockAccessMapped) and is fixed the same way.

Files changed

• jena-db/jena-dboe-base/src/main/java/org/apache/jena/dboe/base/file/BlockAccessMapped.java
• jena-tdb1/src/main/java/org/apache/jena/tdb1/base/file/BlockAccessMapped.java
• jena-db/jena-dboe-base/src/test/java/org/apache/jena/dboe/base/file/TestBlockAccessMappedSegmentState.java (new)
• jena-db/jena-dboe-base/src/test/java/org/apache/jena/dboe/base/file/TS_File.java (register new test class)

Testing

The trigger (an asynchronous throwable inside a 3-line window) cannot be provoked deterministically in a test, so TestBlockAccessMappedSegmentState injects the state it leaves behind and verifies behavior at that boundary:

• poisonedSegmentLimit_readsStillWork — reflectively shrinks the shared segment buffer's limit (the state an escaped throwable left behind), then reads all higher blocks. Against the previous implementation this reproduces the production exception verbatim: IllegalArgumentException: newPosition > limit: (448 > 64). With the fix, all blocks read back correctly.
• sharedSegmentBufferStateUntouchedByAccess — locks in the invariant that block access never mutates the shared buffer's position/limit. Fails against the previous implementation (which left position at the last-accessed segment offset).
• returnedSlicesAreIndependent — returned slices do not interfere with each other or with the shared buffer.
• blockRoundTripAfterMixedAccess — content round-trip through the new slice path.

Red/green verified: with the fix reverted, the new tests fail with the exact production signature; with the fix applied, they pass.

Full test suites pass with the change:

Module	Tests	Result
jena-dboe-base	160	pass
jena-dboe-transaction	117	pass
jena-dboe-trans-data	232	pass
jena-tdb2	734	pass
jena-tdb1	551	pass (5 pre-existing skips)

Compatibility notes

• ByteBuffer.slice(int, int) requires JDK 13+; fine for the current Java baseline (21). A backport to older branches would need ((ByteBuffer)segBuffer.duplicate().clear()).position(segOff).limit(segOff+blockSize).slice() on a duplicate instead.
• No public API change; getByteBuffer is private and the returned slice is indistinguishable from before.

---

• Tests are included.
• Documentation change and updates are provided for the Apache Jena website
• Commits have been squashed to remove intermediate development commit messages.
• Key commit messages start with the issue number (GH-xxxx)

By submitting this pull request, I acknowledge that I am making a contribution to the Apache Software Foundation under the terms and conditions of the Contributor's Agreement.

---

See the Apache Jena "Contributing" guide.