Explain the internal working of the isComplete() flag on OMElement?

Internally, each container-capable OM node (elements, and the document itself) tracks a boolean, commonly referred to as its "done" state, alongside pointers like its current last-known child or sibling; isComplete() simply reports that boolean back to calling code.

That flag flips from false to true at exactly one moment: when the builder processes the END_ELEMENT StAX event corresponding to that specific element - which can happen either because normal navigation eventually walked all the way through the element's children and reached its closing tag, or because an explicit build() call forced that same traversal to happen immediately rather than incrementally.

The reason this flag needs to exist as a distinct signal, rather than callers just checking whether a child/sibling reference is null, is that under deferred building, a null reference is ambiguous - it can mean "there is genuinely no such child," or it can mean "this child exists in the source document but hasn't been parsed yet." Internal navigation methods use isComplete() (checked on the relevant parent) to disambiguate: if the parent isn't complete and the reference is null, that's a signal to pull more events from the builder rather than concluding the child doesn't exist.

This is also why calling isComplete() itself is a safe, non-mutating check - it only reads the existing flag - whereas calls like getNextOMSibling() can be mutating precisely because they may need to advance the builder first in order to answer the question being asked.