What happens internally when you call build() on an incomplete OMElement?

Calling build() forces the element's underlying builder into a loop that keeps calling its internal next() method - pulling and materializing further StAX events - until that specific element's subtree reaches its END_ELEMENT event, at which point isComplete() flips to true for that element (and, transitively, for everything beneath it).

Unlike ordinary navigation, which only pulls as many events as a specific method call needs (a single sibling, say), build() is a deliberate, explicit request to fully realize the entire subtree right now, regardless of how much of the underlying stream that requires consuming.

Once this completes, the element and all of its descendants exist as ordinary, independent OM objects - they no longer have any dependency on the original XMLStreamReader remaining open or unconsumed, which is precisely why build() is the standard move before doing anything that assumes stream-independence: detaching the element to store it elsewhere, handing it to another thread, or navigating it long after the original parsing context has gone out of scope.

The obvious tradeoff is memory and CPU: calling build() on a genuinely large subtree gives up the deferred-building benefit for that portion of the document, which is exactly why it's used selectively - on the specific piece that's actually needed independently - rather than reflexively on an entire large message.