Build a document tree, using options set on this Configuration and on the supplied source object. Options set on the source object override options set in the Configuration. The Source object must be one of the kinds of source recognized by Saxon, or a source that can be resolved using the registered SourceResolver.
@param source the Source to be used. This may be an {@link AugmentedSource}, allowing options to be specified for the way in which this document will be built.
A new tree will be built, using either the Tiny Tree or the Linked Tree implementation, except under the following circumstances:
- The supplied object is a DocumentInfo. In this case a new tree will be built only if validation or whitespace stripping has been requested in the Configuration; otherwise the DocumentInfo will be returned unchanged.
- The supplied object is an AugmentedSource wrapping a DocumentInfo. In this case a new tree will be built if wrap=no has been specified, if validation has been requested, or if whitespace stripping has been requested, either in the AugmentedSource or in the Configuration.
- The supplied object is a DOMSource. In this case a new tree will be built if validation or whitespace stripping has been requested in the Configuration, or if the DOM Node is not a Document Node; in other cases the Document node of the DOMSource will be wrapped in a Saxon {@link org.pdf4j.saxon.dom.DocumentWrapper}, except in the case where the DOM Document node is a {@link org.pdf4j.saxon.dom.DocumentOverNodeInfo}, in which case the DocumentInfo that it wraps is returned.
- The supplied object is an AugmentedSource wrapping a DOMSource. In this case a new tree will be built if wrap=no has been specified, if validation has been requested, or if whitespace stripping has been requested, either in the AugmentedSource or in the Configuration.
The choice between a tiny tree and a linked tree is determined first be the properties of the AugmentedSource if that's what is supplied; otherwise by the properties of this Configuration.
@return the document node of the constructed or wrapped document
@throws XPathException if any errors occur during document parsing or validation. Detailederrors occurring during schema validation will be written to the ErrorListener associated with the AugmentedSource, if supplied, or with the Configuration otherwise.
@since 8.9. Modified in 9.0 to avoid copying a supplied document where this is notnecessary.