DEV Community: Robson Kades

Efficient and Effective XML Processing in Java

Robson Kades — Thu, 17 Sep 2026 00:11:32 +0000

Extracting a value from an XML document costs, at its core, two operations: locating the span of bytes where the value lives and converting it to the type you want. Turning 219.80 into a BigDecimal is a scan to the element and a six-byte parse — nanoseconds, allocating next to nothing.

Almost no Java code pays that price. It pays a different one, orders of magnitude larger: the whole document decoded from UTF-8 to UTF-16, every tag name materialized as a String, every element promoted to an object — whether you need it or not. The classic APIs were designed to represent documents, and we use them to extract values. The difference goes unnoticed on one document; in a service handling millions a day — and XML is still the language of e-invoicing, financial messaging and all the legacy SOAP nobody is ever going to migrate — it is your entire CPU profile. That distance is not mandatory, and closing it is what this article is about.

The invisible cost of the “easy way”

DOM materializes the entire document as an object tree — every element, attribute and text node becomes a heap instance. To read three fields out of a 7 KB document, you allocate the full representation of those 7 KB, navigate to the three values, and throw the tree away. Multiply by millions of documents and the garbage collector becomes the main character of your latency graph.

JAXB (and data binding in general) hides the tree behind annotated classes, which is great for ergonomics — but it still materializes everything, and layers reflection and conversions on top. There is a quiet maintenance cost too: a typical e-invoice schema has hundreds of fields; you generate
classes for all of them to use half a dozen.

StAX is the traditional answer for performance: streaming, one event at a time, no tree. The problem is that nobody likes the code it produces. A while (reader.hasNext()) loop with a hand-rolled state switch quickly grows into something hard to read and harder to change — and every element still becomes an allocated event, every tag name still becomes a String, whether you need it or not.

Goal-directed extraction: pay for what you read

That observation — extraction, not parsing — is the premise of Fletch, a library I wrote after facing exactly the scenario above while processing electronic invoices at volume. The idea: you declare what you want, and the engine makes a single pass over the document’s bytes materializing only that. No tree, no reflection, no generated classes, no dependencies.

Installation

Maven

<dependency>
    <groupId>io.github.robsonkades</groupId>
    <artifactId>fletch</artifactId>
    <version>1.2.0</version>
</dependency>

Gradle

implementation("io.github.robsonkades:fletch:1.2.0")

The primary API is a cursor that navigates elements. Given this document:

<order id="1042" urgent="true">
    <customer>
        <name>Ana Souza</name>
        <address><city>Curitiba</city><zip>80000-000</zip></address>
    </customer>
    <item><sku>AB-1</sku><qty>2</qty><price>49.90</price></item>
    <item><sku>CD-2</sku><qty>1</qty><price>120.00</price></item>
    <total>219.80</total>
</order>

extraction is a composition of functions, one per element shape:

record Item(String sku, Integer qty, BigDecimal price) {}
record Order(Long id, List<Item> items, BigDecimal total) {}

static final XmlExtractor<Item> ITEM = i -> new Item(
        i.value("sku", String.class),
        i.value("qty", Integer.class),
        i.value("price", BigDecimal.class));

static final XmlExtractor<Order> ORDER = o -> new Order(
        o.attribute("id", Long.class),
        o.children("item", ITEM),
        o.value("total", BigDecimal.class));

Order order = Xml.extract(xml, doc -> doc.child("order", ORDER));

Notice what is not there: no event loop, no manual state, no classes beyond the records you already wanted. And one detail that matters in daily use: the cursor is order-tolerant. You read fields in the order that makes sense for your record; if the XML delivers them in a different order, the engine copes — reading in document order costs nothing, reading out of order costs a cheap re-scan of a byte range, not event materialization.

For the I want 8 fields out of a 300-field document case there is a second,
declarative style that compiles the paths once into a table and is faster
still:

static final XmlMapping<Order> ORDER = Xml.mapping(Draft::new)
        .attr("/order@id", (d, v) -> d.id = v.asLong())
        .group("/order/item", ItemDraft::new, (d, i) -> d.items.add(i.toItem()))
            .text("sku",   (i, v) -> i.sku = v.asString())
            .text("qty",   (i, v) -> i.qty = v.asInt())
            .text("price", (i, v) -> i.price = v.asDecimal())
            .endGroup()
        .text("/order/total", (d, v) -> d.total = v.asDecimal())
        .build(Draft::toOrder);

Order order = Xml.extract(bytes, ORDER); // thread-safe, reuse freely

The mapping has one property the cursor doesn’t: over a UTF-8 InputStream it truly streams, through a 64 KB sliding window — you can process a batch larger than memory without thinking about it.

Why it’s fast

Nothing here is magic; it is the sum of small, consistent decisions:

One pass, one loop. Tokenization, name matching and value decoding run fused, directly over the bytes. There are no intermediate event objects.
Names never become Strings. Elements are compared by a hash computed with 8-byte word loads (SWAR — SIMD within a register), allocating nothing
Subtrees you didn’t ask for are skipped by balance counting at memchr speed, without ever reading the tag names.
Values are spans, not copies. A number is converted straight from the document’s bytes into a long or BigDecimal; text only becomes a String if you ask for one.
Extraction stops when you’re done. If the fields you need sit at the start of the document, the rest is never read.

Adding it up: the engine pays the essential cost of extraction — locating spans and converting them — and almost nothing else.

Numbers

JMH benchmark from the repository, over a real 7 KB electronic invoice (a Brazilian NF-e), varying the number of line items: 1, 50 and 500. Environment: i7–13700K, Temurin/JDK 25. The comparison baseline is a hand-written StAX/Woodstox event loop, as lean as it gets — that is, the best case of the traditional approach, not the typical one.

Throughput in ops/ms (higher is better)

Approach	1 item	50 items	500 items
Fletch mapping	283.7	31.6	3.45
Fletch cursor (document order)	224.5	29.9	3.36
Fletch cursor (out of order)	163.4	18.6	2.02
Woodstox, hand-written event loop	96.4	12.4	1.38

On the small document the mapping delivers ~3× the throughput of the Woodstox loop; on the large one, ~2.5×. Allocation per document: about 1.2 KB for the mapping and 6.5 KB for the cursor, against tens of KB per document for a typical StAX pipeline — at volume, that is the difference between the GC showing up in your p99 or not. DOM and JAXB are not in the table because the repository doesn’t benchmark them; given the nature of those approaches (full materialization plus reflection), the gap only widens.

None of this requires trust: mvn -P benchmarks package -DskipTests and java -jar target/benchmarks.jar reproduce the table on your machine.

When to use something else

Honesty is also a form of efficiency. Fletch is an extraction tool, and there are things it deliberately does not do:

Write or transform XML — it is read-only.
XPath, XSLT, schema validation — out of scope.
Truly namespace-aware processing — elements match by raw tag name (a deliberate performance choice; it covers the common profile of integration documents with a default namespace, but if the same prefix means different things in different documents, you will miss it).
Manipulating the document as a data structure — if you need the tree, use a tree library.

If your case is I receive documents at volume and need typed values out of them — which describes the overwhelming majority of systems still speaking XML — the takeaway is simple: the cost of the traditional way is not a law of physics. It is just an old default.

Fletch is open source (Apache 2.0), zero dependencies, Java 17+: github.com/robsonkades/fletch.

An Outbox for 3 Million Events a Day on Azure SQL: the Engineering Behind It

Robson Kades — Wed, 16 Sep 2026 23:50:00 +0000

The Transactional Outbox pattern fits in a thirty-second diagram: write the event in the same transaction as the business data, and let a worker publish it later. Everyone draws that in the first meeting and goes home happy.

What nobody draws is the second half: that table becomes the hottest structure in your database. It takes an insert, an update and a delete on the same row, several times a second, forever. It's read by a scheduler that never sleeps. And it grows until the day the sum of all its rows no longer fits in the server's memory — and from then on, every worker cycle goes to disk.

This article is the record of performance work on a real outbox: ~3 million events per day, ~45 million rows in steady state, running on Azure SQL Database Business Critical. The goal wasn't just "make it fast": it was to do the same work using fewer resources — less IO, less CPU, less log, less memory. On Azure, resources are the invoice.

One warning up front: the most expensive lesson in this work was about method, not about SQL. It's in section 3, and it involves me rewriting the hot path and being 50× wrong.

1. The baseline design

The worker does three things, in an order that matters:

List<OutboxJpaEntity> claimed = transaction.execute(() -> {
    Window<OutboxJpaEntity> window = outboxRepo
        .findFirst100ByEventTypeAndStatusOrderByIdAsc(currentEvent, PENDING, keyset.get());
    // ... mark the batch as processed
    return window.getContent();
});

// publish OUTSIDE the transaction
publisher.publish(claimed);

Claim — grab up to 100 PENDING events of a given type, locking them so no other instance takes them. Flip — mark those events as processed. Publish — send to Service Bus, outside the transaction.

The claim uses the classic SQL Server combo, expressed in JPA:

@QueryHints(@QueryHint(name = "jakarta.persistence.lock.timeout", value = "-2")) // SKIP_LOCKED
@Lock(LockModeType.PESSIMISTIC_WRITE)
Window<OutboxJpaEntity> findFirst100ByEventTypeAndStatusOrderByIdAsc(
        OutboxEventType eventType, OutboxStatus status, ScrollPosition position);

Hibernate 7's dialect translates that into WITH (UPDLOCK, ROWLOCK, READPAST). UPDLOCK reserves the rows; ROWLOCK keeps granularity at the row level, away from escalation to page or table; READPAST makes a concurrent instance skip whatever is already locked instead of waiting on it. This is what lets you scale horizontally without a table lock, without a blocking SELECT FOR UPDATE, and without inventing a distributed lock in Redis. Two instances running the same worker naturally pick up disjoint batches.

Pagination is keyset, not offset:

final AtomicReference<KeysetScrollPosition> keyset = new AtomicReference<>(ScrollPosition.keyset());
// ...
if (window.hasNext()) {
    keyset.set((KeysetScrollPosition) window.positionAt(window.size() - 1));
}

With OFFSET 500000, the database reads and throws away half a million rows before handing you the page. With keyset, it seeks on id > last_id and reads exactly 100. The difference isn't stylistic: it's the difference between constant cost and cost that grows with backlog depth. In a queue that occasionally piles up millions of rows, offset is a time bomb.

And there's a cap on rounds per cycle:

} while (isRunning() && maybeMore && --rounds > 0);

MAX_ROUNDS = 20 — at most 2,000 events per cycle. Without it, a large backlog would make the scheduler thread drain the entire queue in a single cycle, holding a pool connection and ignoring the shutdown signal for minutes.

Publishing outside the transaction: the honest decision

Publishing inside the transaction is the classic mistake: your database transaction now lasts as long as a network round-trip to the broker, holding locks the whole time. Under load, that's what takes the system down.

Publishing outside means accepting at-least-once: if the application dies between the claim commit and the publish, those events were marked processed and never went out. It's a small, known window, and the decision was documented rather than hidden:

// Publish OUTSIDE the transaction: on failure, mark the batch as FAIL for
// later reprocessing (at-least-once, except in the crash window between
// the TX1 commit and markFailed).

The alternative — two-phase commit between database and broker — costs more than the problem it solves. The consumer has to be idempotent anyway.

2. Before any code: understand the physics of the table

No query optimization saves a design that doesn't fit in memory. So the first thing measured wasn't time — it was size.

payload was NVARCHAR(2000), stored in-row.
With a ~600-character payload, the row landed around 1.3 KB.
45 million rows × 1.3 KB ≈ 58 GB.
Engine memory on an 8-vCore Business Critical (BC_Gen5_8) is 41.5 GB — and the buffer pool is smaller than that: plan cache, lock memory and the 6.28 GB carved out for In-Memory OLTP come out of the same budget.

The table did not fit in memory. That number alone explains why the worker got slower over time regardless of indexing: past a certain point, reading the queue means reading disk.

Second calculation, on transaction log: over its lifetime, each event produces an insert + the flip update + the purge delete. Log volume lands around 4× the payload per event. On Azure that isn't a curiosity — there's log rate governance, a per-service-objective ceiling on log MB/s. Blow past it and you get LOG_RATE_GOVERNOR waits, and the whole application slows down with CPU to spare.

Two conclusions from that arithmetic, and they drove everything afterwards:

Reducing bytes per row is a compounding win: less buffer pool, less IO, less log, less backup.
Reducing rows touched per cycle beats any amount of plan fine-tuning — and that is, first and foremost, an indexing problem.

3. The most expensive lesson: estimated plans lie

Here's the part that hurts.

The original claim — a SELECT with UPDLOCK/READPAST followed by Hibernate's updates — struck me as naive. "Two statements where one would do." I rewrote it into the pattern every SQL Server outbox article recommends: a single UPDATE ... FROM ... OUTPUT that locks, marks and returns the rows in one shot.

The estimated plan for my version showed a cost of 0.06. It looked obvious.

Then I measured for real, with sys.dm_exec_query_stats:

Version	Actual CPU per claim of 100
My `UPDATE ... OUTPUT`	142.84 ms
Original (SELECT + updates)	~2.9 ms (0.19 ms for the SELECT + 100 × 0.027 ms)

The original is ~50× cheaper in actual CPU. The optimizer estimated mine at 0.06 and it cost 142 ms — off by roughly 2000×.

Why? Two things stacked up:

Halloween Protection. The statement reads status = 0 and writes status = 1 in the same index. SQL Server must guarantee an updated row isn't re-read and updated again — and its protection is an Eager Spool: it materializes the entire set into tempdb before applying a single update. A plain SELECT followed by primary-key updates has no such problem; nothing is being read and written at once.
Concurrent READPAST destroyed the row goal. The optimizer plans TOP 100 assuming it will find 100 rows quickly. With other instances holding rows, READPAST skips large stretches and the operator scans far more than estimated.

The "naive" version already had a clean covered read against the index, batched updates by PK, and — thanks to @DynamicUpdate — an UPDATE touching only the two columns that actually changed.

The rule that stuck: on this path, comparing estimated plans is comparing fiction. Either you have dm_exec_query_stats / STATISTICS IO for both versions, or you don't know which one is faster. I reverted the claim to the original and it has stayed untouched since.

4. The gotchas worth more than any refactor

Before touching architecture, four configuration details paid off more than any rewrite. All of them invisible in the Java code.

4.1 Your driver turns off your filtered index

The hot path index is filtered:

CREATE NONCLUSTERED INDEX IX_outbox_claim
    ON outbox_event (event_type, id)
    INCLUDE (aggregate_id, payload)
    WHERE status = 0;

It's tiny by construction — it holds only the PENDING backlog, which gets published within seconds. It's the perfect index for the claim.

And it simply wasn't being used. The claim turned into a Clustered Index Scan over millions of rows.

The entire fix was one line of YAML:

hikari:
  connection-init-sql: SET ARITHABORT ON

And here precision matters, because the easy explanation — the one I reached for first — is wrong.

The easy explanation goes: "mssql-jdbc connects with ARITHABORT OFF, and with ARITHABORT OFF the optimizer refuses filtered indexes." The CREATE INDEX docs do list ARITHABORT ON among the SET options required for a filtered index, and state that with the wrong options "the query optimizer doesn't consider the index in the execution plan for any Transact-SQL statements."

Except the SET ARITHABORT docs say something that dismantles that: ANSI_WARNINGS ON implicitly sets ARITHABORT ON at database compatibility level 90 or higher — and the JDBC driver connects with ANSI_DEFAULTS ON, which includes ANSI_WARNINGS ON. In the docs' own words: "When ANSI_WARNINGS is ON (the default), the setting of ARITHABORT has no functional effect." On a modern database, then, the filtered index was probably not being refused by that rule.

What the docs do state unambiguously is this, and it's enough to explain the symptom:

"The default ARITHABORT setting for SQL Server Management Studio (SSMS) is ON, while a client connection in an application defaults to ARITHABORT OFF. Even if there's no functional difference as long as ANSI_WARNINGS is ON, the ARITHABORT setting is still a cache key. Therefore, SSMS and an application both using their respective defaults, have different cache entries, and might get different query plans (...) the same query might execute slower in the application than in SSMS."

Which is exactly the symptom observed: seek in SSMS, scan in the application, same query. Two plan cache entries, two compilations, two fates — and the application's drew the bad one.

The practical lesson survives intact, and it's still the cheapest one here: match your application's ARITHABORT to SSMS's, or you're debugging a plan that isn't the one running in production. Just don't pin it on the wrong mechanism — as I did.

To find out which case is yours, the evidence is in the plan cache:

-- compare the plans of BOTH entries for the same query
SELECT ph.query_plan, cp.plan_handle, cp.usecounts,
       ph.query_plan.value('(//StmtSimple/@StatementOptmLevel)[1]', 'varchar(50)') AS optm
FROM sys.dm_exec_cached_plans cp
CROSS APPLY sys.dm_exec_query_plan(cp.plan_handle) ph
CROSS APPLY sys.dm_exec_sql_text(cp.plan_handle) st
WHERE st.text LIKE '%outbox_event%';

Two entries for the same query text means it's the cache key. A single entry that still ignores the filtered index means it really is the SET options rule — and then it's worth checking the database's compatibility level.

4.2 A filtered index won't match a parameter

The second trap on the same index: for the optimizer to prove the WHERE status = 0 filter covers the query, it needs to see the literal 0 in the predicate. When Hibernate parameterizes it (status = @P2), the plan would have to be valid for any value of @P2 — including 1 and 2, which aren't in the index. Result: the filtered index is discarded.

In other words: any query that needs this index has to carry the literal, which in practice means a native query — not a Spring Data derived method. Wherever that shows up, the comment travels with it:

-- status = 0 is a LITERAL on purpose: parameterized, the optimizer won't match
-- the filtered index WHERE status = 0 (same trap as the claim).
IF EXISTS (SELECT 1 FROM dbo.outbox_event WITH (READPAST)
           WHERE event_type = @event_type AND status = 0)

The same goes for the flips: they use literals (1 for PROCESSED, 2 for FAIL) in native queries, with the enum ordinal documented right next to them.

4.3 The NVARCHAR that was never Unicode

The connection string already carried:

sendStringParametersAsUnicode=false

That's well-established good practice on SQL Server (without it, an NVARCHAR parameter compared against a VARCHAR column causes an implicit conversion and kills the seek). But it implies something: the driver was already sending payloads as VARCHAR. The Unicode promised by the NVARCHAR(2000) column never made it through from the application side — we were paying 2 bytes per character for a guarantee that didn't exist.

Migrating to VARCHAR(2000) cuts roughly half the row bytes and half the log bytes. Given log ≈ 4× payload, that's a direct win against log rate governance.

With one non-negotiable caveat: NVARCHAR → VARCHAR can corrupt data silently (characters outside the collation's code page become ?). So the script carries a mandatory pre-check before the ALTER:

SELECT MAX(LEN(payload)) AS max_len,
       SUM(CASE WHEN payload <> CONVERT(NVARCHAR(2000), CONVERT(VARCHAR(2000), payload))
                THEN 1 ELSE 0 END) AS lossy_rows
FROM dbo.outbox_event;

It must return lossy_rows = 0. In the test environment (16.5M rows): max_len = 28, lossy_rows = 0. Only then the ALTER — which is size-of-data, rewrites every row, and requires dropping and recreating any index containing the column.

4.4 Time zone in the `Instant` bind

An Instant mapped to datetime2 is bound in the JVM's time zone, not UTC. Which means the same code writes different values depending on which container it runs in — and a purge comparing processed_at < @cutoff starts deleting the wrong window.

"[hibernate.jdbc.time_zone]": UTC

One line that trades an environmental dependency for a guarantee.

5. Indexes and page geometry

With the driver fixed, the index started being used. At which point the subject becomes how pages behave under writes.

FILLFACTOR: 85 was waste

The original maintenance script rebuilt indexes with FILLFACTOR = 85 — leaving 15% of every page empty to absorb row growth and avoid page splits.

Except here, the row doesn't grow. RCSI and ADR are always on in Azure SQL Database — RCSI is the default on every new database, and ADR can't even be turned off. Row versioning adds a 14-byte version tag per row (a 6-byte transaction sequence number + an 8-byte row identifier), and the documentation is specific about when: on a database that already had RCSI enabled, those 14 bytes go in at insert time, not on first modification.

Which means: on Azure, the row is born with its version tag. The flip doesn't grow it by a single byte. That 15% of free space was reserved for growth that never happens.

15% of empty space across 45 million rows ≈ 9 GB of nothing occupying buffer pool, being read in every scan, copied in every checkpoint and every backup. FILLFACTOR = 98 is plenty:

ALTER INDEX ... REBUILD WITH (FILLFACTOR = 98, OPTIMIZE_FOR_SEQUENTIAL_KEY = ON, ONLINE = ON);

OPTIMIZE_FOR_SEQUENTIAL_KEY

The key comes from an ascending sequence, so every insert lands on the same page — the last one. Under burst, dozens of threads contend for that page's latch and form a PAGELATCH_EX convoy: the bottleneck isn't IO or CPU, it's a queue waiting on an in-memory structure. OPTIMIZE_FOR_SEQUENTIAL_KEY = ON exists precisely for this — it orders entry into that latch instead of letting the convoy form.

Why the wide covering index was expensive on the flip

There was a covering index with status as the leading column:

CREATE NONCLUSTERED INDEX IX_Outbox_Status_Event_Type_Covering
    ON dbo.outbox_event (status, event_type, id)
    INCLUDE (aggregate_id, aggregate_type, payload, created_at, processed_at, retry_count)

Great for reading. But when status is a key column and the flip changes status from 0 to 1, the index entry changes position — and SQL Server implements that as a delete + insert of the whole entry. The whole entry here includes the payload. So: every published event rewrote ~1.3 KB of index, on top of the base table row.

The filtered index serves the same access without that cost: because status = 0 lives in the WHERE and not in the key, the flip removes the entry instead of relocating it — and the index stays small, holding only the backlog.

Sequence IDs, not IDENTITY

@GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "outbox_event_seq")
@SequenceGenerator(name = "outbox_event_seq", sequenceName = "outbox_event_seq", allocationSize = 50)

CREATE SEQUENCE outbox_event_seq AS BIGINT START WITH 10000001 INCREMENT BY 50 CACHE 100;

With IDENTITY, Hibernate cannot batch inserts — it needs the generated id back for every row, which forces a round-trip per insert. With a sequence, allocationSize = 50 and the pooled-lo optimizer, the application reserves 50 ids at once and inserts 50 rows in a single JDBC batch.

The detail that breaks in production if you get it wrong: INCREMENT BY in the database must match allocationSize in Java. Diverge, and they collide.

6. The Java side: concurrency and clean shutdown

The work here is almost entirely IO — the JVM spends its time waiting on the database. Measurement confirmed it: at 35–350 events/s, allocation sits in the hundreds of KB/s. GC tuning had no win to offer. So the Java effort went elsewhere: don't hold threads, and don't lose batches on shutdown.

Virtual threads in the scheduler. The worker blocks on IO the entire time — the canonical use case:

@Bean("fastScheduler")
public ThreadPoolTaskScheduler fastScheduler() {
    ThreadPoolTaskScheduler scheduler = new ThreadPoolTaskScheduler();
    scheduler.setVirtualThreads(true);
    // virtual threads are daemon: without this wait the JVM exits mid-batch
    scheduler.setAwaitTerminationSeconds(30);
    scheduler.setWaitForTasksToCompleteOnShutdown(true);
    // ...
}

The comment points at the real trap: virtual threads are daemon threads. Without awaitTermination, the JVM exits without waiting for them and the in-flight batch dies with the process — at the worst possible moment, between claim and publish.

SmartLifecycle to actually shut down:

// volatile: start() runs on the main thread, stop() on the
// SpringApplicationShutdownHook, and the executeJob() loop reads the flag
// on the fastScheduler threads.
private volatile boolean isRunning = false;

Three different threads touch that flag, and it's volatile that guarantees the loop actually sees the stop signal. The loop checks it on every round (while (isRunning() && ...)), so a shutdown interrupts between batches — never in the middle of one.

Small pool, short timeout:

maximum-pool-size: 20
connection-timeout: 250
minimum-idle: 0

A large pool is a popular trap: more connections mean more context for the database to manage and more internal contention, not more throughput. And connection-timeout: 250 is a deliberate fail-fast choice — if there's no connection within 250 ms the system is saturated, and queuing threads to wait just moves the queue inside the application.

Well-aligned batching:

"[hibernate.jdbc.batch_size]": 50
"[hibernate.jdbc.fetch_size]": 50
"[hibernate.id.optimizer.pooled.preferred]": pooled-lo
"[hibernate.connection.provider_disables_autocommit]": true
"[hibernate.order_updates]": true
open-in-view: false

provider_disables_autocommit: true stops Hibernate from opening the database transaction too early — the pooled connection already arrives with autocommit off, and without this flag Hibernate spends a redundant round-trip per transaction. open-in-view: false because keeping a persistence session open while the response renders is holding a connection for free.

The publisher respects the broker's limit. A small detail that prevents a production error: on the Service Bus Standard tier the ceiling is 256 KB, both per message and per batch — and it isn't configurable. (On Premium the batch goes to 1 MB, and a single message can reach 100 MB over AMQP; if you change tier, this constant changes.) The publisher packs up to that ceiling and fails fast, with a clear message, on any single event that can't fit:

if (size > MAX_BATCH_BYTES) {
    throw new IllegalArgumentException(
            "Message " + event.getId() + " exceeds the batch limit of " + MAX_BATCH_BYTES + " bytes");
}

7. How to measure (because without this, none of the above is true)

The tooling that backed every decision in this article:

Actual CPU per query — the source of truth, the one that proved I was 50× wrong:

SELECT TOP 100
    (qs.total_worker_time * 1.0 / qs.execution_count) / 1000.0 AS Avg_CPU_ms,
    qs.execution_count, qp.query_plan, st.text
FROM sys.dm_exec_query_stats AS qs
CROSS APPLY sys.dm_exec_sql_text(qs.sql_handle) AS st
CROSS APPLY sys.dm_exec_query_plan(qs.plan_handle) AS qp
WHERE st.text LIKE '%outbox%'
ORDER BY qs.execution_count DESC;

Indexes nobody uses — every unused index is pure write cost on a table that does nothing but write:

SELECT OBJECT_NAME(s.object_id) AS TableName, i.name AS IndexName,
       s.user_seeks, s.user_scans, s.user_lookups, s.user_updates
FROM sys.dm_db_index_usage_stats AS s
INNER JOIN sys.indexes AS i ON i.object_id = s.object_id AND i.index_id = s.index_id
ORDER BY (s.user_seeks + s.user_scans + s.user_lookups) DESC;

Fragmentation and real size via sys.dm_db_index_physical_stats — that's where the 9 GB wasted by FILLFACTOR 85 came from.

Wait evidence — sys.dm_db_wait_stats, sys.dm_db_resource_stats and Query Store, all database-scoped on Azure SQL. That's where LOG_RATE_GOVERNOR and PAGELATCH_EX show up by name.

8. What stuck

In order of real impact — and note how little of it is "better code":

SET ARITHABORT ON in the pool init. One line of YAML: it aligns the application with SSMS and kills the parallel plan cache entry where the bad plan lived.
NVARCHAR → VARCHAR. Half the row and log bytes, for a Unicode guarantee the driver was no longer delivering. With a mandatory data-loss pre-check.
FILLFACTOR 98 + OPTIMIZE_FOR_SEQUENTIAL_KEY. ~9 GB of emptiness reclaimed and the last-page latch convoy tamed.
A filtered index, with the literal in the query. An index holding only the PENDING backlog, and queries written so the optimizer can actually use it.
Keyset instead of offset in the claim's pagination: constant cost instead of cost that grows with backlog depth.

And the lesson that outranks all of them: I rewrote the hot path before measuring, and I was 50× wrong. The estimated plan said 0.06; reality charged 142 ms. The "obvious" pattern the articles recommend — a single-statement UPDATE ... OUTPUT — was the worse of the two in this specific context, because of a Halloween Protection the diagram never shows.

Comparing estimated plans is comparing fiction. dm_exec_query_stats, STATISTICS IO, or we know nothing.

Stack: Java 25, Spring Boot 4.1, Hibernate 7, mssql-jdbc, Azure SQL Database Business Critical.

UUIDv7: The Idea Behind a High-Throughput Java Generator

Robson Kades — Wed, 16 Sep 2026 23:44:42 +0000

uuidv7 is a Java library for generating UUID version 7 identifiers, with time ordering, local monotonic sequences, and batch generation support. It runs on Java 17 or later, depends only on the JDK, and offers output as UUID objects, strings, and binary arrays.

The problem appears in applications that assign an identifier to every event, message, or record. Reading the clock, obtaining randomness, and creating an object are small operations repeated throughout the data flow. Centralizing the sequence would also make concurrent producers compete for the same state.

The solution's central idea is to keep the sequence close to its producer and share work that can be performed once per batch. The library combines local states, a bounded set of states for virtual threads, and range reservation before writing. This organization explains both its APIs and its performance results.

1. A Sequence That Keeps Increasing

As defined in RFC 9562, Section 5.7, UUIDv7 places a 48-bit Unix timestamp, in milliseconds, in the most significant part of the identifier. Besides the version and variant fields, it has 74 bits in rand_a and rand_b, referred to here as the payload. These fields can combine random values and counters to keep the sequence increasing.

In this generator, the fast sequence can be represented as U = (T, A, B): logical timestamp, 12-bit field, and 62-bit counter. Since version and variant are constant, comparison considers T first, then A, and finally B, treating the values as unsigned integers:

If the observed time is greater than T, the generator adopts it: T' > T. The new UUID is greater than its predecessor regardless of the initial values of A and B.
If the observed time is less than or equal to T and the counter still has room, T' = T, A' = A, and B' = B + 1.
If a counter already at its limit must be incremented, the generator advances T and generates new initial values for A and B. If the timestamp is also at its limit, it throws an exception.

These transitions preserve U' > U for UUIDs generated from the same state, provided that one thread owns it or access is synchronized. The timestamp can remain ahead of the observed clock during rollback; it represents the time used by the generator.

Monotonicity is guaranteed per generator state. This lets producers advance independently, without a global sequencer. Uniqueness across states and processes remains probabilistic; the UUID timestamp does not establish causality between events.

2. State for Each Execution Model

The static API selects state according to the execution model:

Model	State ownership	Cost and usage condition
Platform thread	`ThreadLocal` reused by the thread	No shared lock for fast-sequence updates
`UUIDv7Generator`	Instance controlled by the application	Requires confinement or external synchronization of all accesses
Virtual thread (Java 21+)	Shared state in a stripe	`ReentrantLock` serializes access to that stripe

The fast path uses a shared atomic sequence when creating states. Afterward, each state advances locally. Coordination is associated with initialization rather than every UUID emitted by a platform thread.

For virtual threads, the component maintains separate sets of fast and secure stripes. Each set has the smallest power of two greater than or equal to 4 × availableProcessors(): with 24 processors reported to the JVM, that is 128 stripes. Selection mixes the virtual thread's identifier, preserving its association even when it changes carrier threads.

This organization reuses states and SecureRandom instances across short-lived tasks. Threads assigned to the same stripe share generator state and can compete for its lock.

For applications that already organize work in event loops or partition workers, UUIDv7Generator provides an explicit instance. The application controls its lifecycle and maintains the same sequence across single-value calls and batches.

3. Generating a Batch Starts with a Reservation

Single-value generation assembles two long values directly and returns a UUID. For a nonempty batch, the generator reads the clock once, reserves a sequence, and writes into the caller's array.

The reservation method uses lastUnixTsMs for the logical timestamp, randB for the counter, and RAND_B_MASK for its 62-bit limit:

boolean tryReserve(int count, long unixTsMs) {
    if (unixTsMs <= lastUnixTsMs && RAND_B_MASK - randB < count) {
        return false;
    }
    advance(unixTsMs);
    randB += count - 1L;
    return true;
}

The internal method receives count > 0. advance() establishes the first value; the addition moves state to the last reserved value. If the counter was at 100, reserving four values at the same timestamp assigns [101, 104] and leaves state at 104.

The counter's initial value has its two upper bits cleared: B₀ ≤ 2^60 − 1. Since Bmax = 2^62 − 1, at least 3 × 2^60 positions remain available. This accommodates any internal reservation with a positive int size immediately after counter initialization.

In stripes, the lock protects reservation and capture of the initial two halves. Normal buffer writing happens after releasing it:

A: reserve [101, 104] under lock → release → write its buffer
B: reserve [105, 108] under lock → release → write its buffer

Updating state under the lock definitively assigns the interval. B can finish before A, but the ranges are disjoint. The next reservation can advance while the previous batch is still being written.

State updates cost O(1) per batch on the normal path; writing remains O(n). A conceptual model is C_UUID(n) ≈ C_fixed/n + C_write, where fixed cost includes the clock, state selection, reservation, and applicable synchronization. The benchmark does not measure these components individually.

If the observed time does not exceed T and the counter does not have room for the batch, the method returns false without changing state. Filling then generates one UUID at a time; for virtual threads, the stripe lock remains held until completion. If the timestamp can no longer advance either, the call can fail after writing part of the batch; values already used are not reused.

The destination belongs to the caller: long[] uses two elements per UUID and byte[] uses 16 bytes in big-endian order. Reusing these arrays avoids per-identifier objects. The application controls buffer consumption and publication to other threads.

4. Randomness According to Purpose

The fast mode uses a non-cryptographic pseudorandom generator to set the initial values of A and B when the logical timestamp advances. Subsequent calls increment the counter. UUIDs generated from the same state at the same timestamp therefore have related values because they share the same starting point.

For the APIs backed by SecureRandom, each state maintains a 512-byte buffer. Both methods consume values from that same buffer:

API	Policy	Buffer consumption
`secureMonotonicUUID()`	`SecureRandom` supplies initial values and increments; each increment ranges from 1 to 1,024	2 bytes per increment that fits in the counter; 16 to set new initial values
`secureUnorderedUUID()`	Fresh random values in all 74 payload bits for each UUID, with no ordering guarantee	16 bytes per UUID

secureRandomUUID() is an alias of secureMonotonicUUID() and shares its sequence. When an increment requires advancing the timestamp and restarting the counter, the buffer supplies bytes for both operations.

The two APIs serve different needs: keeping the sequence increasing or generating the entire payload again. In the monotonic API backed by SecureRandom, the next UUID from the same state, at the same timestamp and without restarting the counter, has at most 1,024 possible values. This sequence is therefore not intended for secret tokens.

5. The Result of Batch Generation

The September 5, 2026 measurements used JMH 1.37, Temurin OpenJDK 25.0.4.1+1-LTS, Windows 11 Pro, and an Intel Core i7-13700K. The protocol used two forks, five warmup and five measurement iterations of one second each, a fixed 1 GiB heap, and -prof gc. The cached clock was disabled.

Single-thread results:

Output	Million UUIDs/s	Allocation, B/UUID
`randomUUID()` / object	260.1 ± 3.9	32.00
`fill(long[])` / batch of 256	4,449.3 ± 29.8	≈ 0
`fill(byte[])` / batch of 256	4,030.3 ± 33.4	≈ 0
`secureMonotonicUUID()` / object	118.4 ± 6.0	32.78
`secureUnorderedUUID()` / object	27.3 ± 0.4	38.25

The ± values are the half-widths of the 99.9% confidence intervals reported by JMH. Near-zero allocation refers to generation after warmup into previously allocated, reused arrays.

The long[] batch achieved approximately 17.1 times the per-identifier throughput of the single-value API. This result combines sharing costs across the batch with changing the output format: the batch writes into a reused array containing 4 KiB of data, while the single-value API delivers objects to JMH. The 32 B/UUID measured for that API implies about 8.32 GB/s of allocation at that rate.

With @OperationsPerInvocation(256), JMH counts 256 identifiers per call. The 0.225 ns/UUID derived from throughput is an amortized cost: the batch cost divided by its 256 values. Per batch, the value is approximately 57.5 ns. Single-call latency requires a separate measurement.

With eight platform threads, the fast API reached an aggregate 1.018 billion ± 31.5 million UUIDs/s: approximately 3.91 times single-thread throughput. Throughput increased, with sublinear scaling on this machine.

In another experiment, each invocation submitted 64 virtual-thread tasks, with one thousand UUIDs per task, and waited for their completion. Generation into byte[] reached 1.414 million ± 0.095 million tasks/s, equivalent to about 1.414 billion UUIDs/s. This measurement includes submission, scheduling, value consumption, waiting, and a new array per task; its unit is the complete task.

The numbers describe these environments and consumption patterns. Batch generation shows its advantage when the consumer uses the binary output; object conversion, persistence, and networking add costs absent from the array-filling measurement.

6. Installation with Maven

With Maven and JDK 17 or later, run the following command from the uuidv7 source directory to compile the component, run its tests, and install version 1.3.0 into the local Maven repository:

mvn install "-Dgpg.skip=true"

The -Dgpg.skip=true option disables GPG artifact signing for this local installation.

Then add the dependency inside <dependencies> in the application's pom.xml:

<dependency>
    <groupId>io.github.robsonkades</groupId>
    <artifactId>uuidv7</artifactId>
    <version>1.3.0</version>
</dependency>

7. From the Component to the Data Flow

The API supports starting with single-value generation and using batches where processing already groups records:

import io.github.robsonkades.uuidv7.UUIDv7;
import io.github.robsonkades.uuidv7.UUIDv7Generator;

public class UUIDv7Example {
    public static void main(String[] args) {
        var id = UUIDv7.randomUUID();

        byte[] batch = new byte[16 * 256];
        UUIDv7.fill(batch, 0, 256);
        // Consume all 256 identifiers before reusing the buffer.

        var generator = UUIDv7Generator.create(); // Use from one thread.
        var nextId = generator.next();
    }
}

A service can use randomUUID() when creating an entity. A pipeline already producing binary blocks can fill its buffer with fill(). A worker with confined state can keep its own UUIDv7Generator instance. All three paths express the same state ownership idea, with representations suited to each consumer.

Given the same initial state and the same clock reading for every element, reservation produces the same sequence as generating one UUID at a time. The tests compare both batch formats with the single-value sequence across 45 combinations of counter, clock, and size. They also check the next output and exercise eight threads sharing a stripe near rollover.

The core idea of uuidv7 is to organize generation around the producer and the destination of the data. Local states allow independent sequences; stripes reuse resources across virtual threads; reservations divide fixed cost across many identifiers. The batch API makes this combination accessible without requiring an intermediate object for every generated value.