Explain the internal working of the StAX-based builder in Axiom?

Internally, StAXOMBuilder keeps a small state machine tracking the current node under construction and a reference to the underlying XMLStreamReader.

Each call to the builder's next() method advances the reader by one event and inspects its type (START_ELEMENT, CHARACTERS, END_ELEMENT, COMMENT, and so on), then appends the corresponding OM node - a new OMElement, an OMText, whatever fits - to whichever element is currently "open" as the active parent.

Navigation calls on the tree itself are what actually drive this process forward: when code calls something like getNextOMSibling() and finds that the sibling reference is still null while the parent isn't yet marked complete, that method calls back into the builder's next() in a loop until either the sibling materializes or the parent's closing tag is reached.

The builder tracks per-element "done" state (surfaced publicly as isComplete()) so that navigation code can distinguish "this child doesn't exist" from "this child hasn't been parsed yet" - a null pointer alone can't tell those two cases apart, which is why the completeness flag exists as a separate signal.

// simplified sketch of the pattern inside getNextOMSibling()
if (this.nextSibling == null && !parent.isComplete()) {
    builder.next(); // pull more events until sibling appears or parent closes
}
return this.nextSibling;

Once the underlying XMLStreamReader has been fully consumed or explicitly closed, further calls into next() either return no further meaningful events or raise an exception, depending on how far navigation had already progressed - which is the root cause behind the "already consumed" style errors developers occasionally hit.