DocumentBuilder Class Reference

A document builder holds properties controlling how a Saxon document tree should be built, and provides methods to invoke the tree construction. More...

#include <DocumentBuilder.h>

Public Member Functions
	~DocumentBuilder ()
	Destructor method.
void	setLineNumbering (bool option)
	Set whether line and column numbering is to be enabled for documents constructed using this DocumentBuilder.
bool	isLineNumbering ()
	Ask whether line and column numbering is enabled for documents loaded using this DocumentBuilder.
void	setSchemaValidator (SchemaValidator *validator)
	Set the SchemaValidator to be used.
SchemaValidator *	getSchemaValidator ()
	Get the SchemaValidator used to validate documents loaded using this DocumentBuilder.
void	setDTDValidation (bool option)
	Set whether DTD validation should be applied to documents loaded using this DocumentBuilder.
bool	isDTDValidation ()
	Ask whether DTD validation is to be applied to documents loaded using this DocumentBuilder.
void	setBaseUri (const char *uri)
	Set the base URI of a document loaded using this DocumentBuilder.
const char *	getBaseUri ()
	Get the base URI of documents loaded using this DocumentBuilder when no other URI is available.
XdmNode *	parseXmlFromString (const char *content, const char *encoding=nullptr)
	Load an XML document, to create a tree representation of the document in memory.
XdmNode *	parseXmlFromFile (const char *filename)
	Build a document from a supplied XML file.
XdmNode *	parseXmlFromUri (const char *source)
	Build a document from a supplied URI source.
bool	exceptionOccurred ()
	Deprecated.
void	exceptionClear ()
	Deprecated.
const char *	getErrorMessage ()
	Deprecated.
const char *	getErrorCode ()
	Deprecated.
SaxonApiException *	getException ()
	Deprecated.

Friends
class	SaxonProcessor

Detailed Description

A document builder holds properties controlling how a Saxon document tree should be built, and provides methods to invoke the tree construction.

This class has no public constructor. To construct a DocumentBuilder, use the factory method SaxonProcessor.newDocumentBuilder().

All documents used in a single Saxon query, transformation, or validation episode must be built with the same SaxonProcessor. However, there is no requirement that they should use the same DocumentBuilder.

Sharing of a DocumentBuilder across multiple threads is not recommended. However, in the current implementation sharing a DocumentBuilder (once initialized) will only cause problems if a SchemaValidator is used.

Member Function Documentation

exceptionClear()

void DocumentBuilder::exceptionClear

(

)

Deprecated.

Clear any thrown exceptions.

Deprecated

From 12.1 this method is no longer used, since exceptions are now thrown.

exceptionOccurred()

bool DocumentBuilder::exceptionOccurred

(

)

Deprecated.

Checks for pending exceptions without creating a local reference to the exception object

Deprecated

From 12.1 this method is no longer used, since exceptions are now thrown.

Returns

True when there is a pending exception; otherwise false

getBaseUri()

const char * DocumentBuilder::getBaseUri

(

)

Get the base URI of documents loaded using this DocumentBuilder when no other URI is available.

Returns

The base URI to be used, or null if no value has been set. Memory deallocation is handled internally.

getErrorCode()

const char * DocumentBuilder::getErrorCode

(

)

Deprecated.

Get the first error code if there are any errors.

Deprecated

From 12.1 this method is no longer used, since exceptions are now thrown.

Returns

The error code of the exception

getErrorMessage()

const char * DocumentBuilder::getErrorMessage

(

)

Deprecated.

Get the first error message if there are any errors.

Deprecated

From 12.1 this method is no longer used, since exceptions are now thrown.

Returns

The message of the exception

getException()

SaxonApiException * DocumentBuilder::getException

(

)

Deprecated.

Get the SaxonApiException object created when we have an error.

Deprecated

From 12.1 this method is no longer used, since exceptions are now thrown.

Returns

The SaxonApiException object if there is an exception thrown, or nullptr otherwise

getSchemaValidator()

SchemaValidator * DocumentBuilder::getSchemaValidator

(

)

Get the SchemaValidator used to validate documents loaded using this DocumentBuilder.

Returns

The SchemaValidator if one has been set; otherwise null. The caller is responsible for memory deallocation.

isDTDValidation()

bool DocumentBuilder::isDTDValidation

(

)

Ask whether DTD validation is to be applied to documents loaded using this DocumentBuilder.

Returns

True if DTD validation is to be applied

isLineNumbering()

bool DocumentBuilder::isLineNumbering

(

)

Ask whether line and column numbering is enabled for documents loaded using this DocumentBuilder.

By default, line and column numbering is disabled.

Line numbering is not available for all kinds of source: in particular, it is not available when loading from an existing DOM Document.

Returns

True if line numbering is enabled

parseXmlFromFile()

XdmNode * DocumentBuilder::parseXmlFromFile

(

const char *

filename

)

Build a document from a supplied XML file.

Parameters

filename

- the file name for the source document

Returns

The XdmNode representing the root of the document tree

Exceptions

SaxonApiException

if there is a failure in the parsing of the XML document

parseXmlFromString()

XdmNode * DocumentBuilder::parseXmlFromString	(	const char *	content,
		const char *	encoding = nullptr )

Load an XML document, to create a tree representation of the document in memory.

Parameters

content	- the XML document as a serialized string
encoding	- the encoding of the source document string. If not specified then the platform default encoding is used.

Returns

The document node at the root of the tree of the resulting in-memory document, as an XdmNode. The caller is responsible for memory deallocation.

Exceptions

SaxonApiException

if there is a failure in the parsing of the XML document

parseXmlFromUri()

XdmNode * DocumentBuilder::parseXmlFromUri

(

const char *

source

)

Build a document from a supplied URI source.

Parameters

source

- URI for the XML source document

Returns

The document node at the root of the tree of the resulting in-memory document, as an XdmNode.

Exceptions

SaxonApiException

if there is a failure in the parsing of the XML document

setBaseUri()

void DocumentBuilder::setBaseUri

(

const char *

uri

)

Set the base URI of a document loaded using this DocumentBuilder.

This is used for resolving any relative URIs appearing within the document, for example in references to DTDs and external entities.

This information is required when the document is loaded from a source that does not provide an intrinsic URI, notably when loading from a Stream or a DOMSource. The value is ignored when loading from a source that does have an intrinsic base URI.

Parameters

uri	- the base URI of documents loaded using this DocumentBuilder. This must be an absolute URI.

setDTDValidation()

void DocumentBuilder::setDTDValidation

(

bool

option

)

Set whether DTD validation should be applied to documents loaded using this DocumentBuilder.

By default, no DTD validation takes place.

Parameters

option

- true if DTD validation is to be applied to the document

setLineNumbering()

void DocumentBuilder::setLineNumbering

(

bool

option

)

Set whether line and column numbering is to be enabled for documents constructed using this DocumentBuilder.

This has the effect that the line and column number in the original source document is maintained in the constructed tree, for each element node (and only for elements). The line and column number in question are generally the position at which the closing ">" of the element start tag appears.

By default, line and column numbers are not maintained.

Errors relating to document parsing and validation will generally contain line numbers whether or not this option is set, because such errors are detected during document construction.

Line numbering is not available for all kinds of source: for example, it is not available when loading from an existing DOM Document.

Parameters

option

- true if line numbers are to be maintained, false otherwise.

setSchemaValidator()

void DocumentBuilder::setSchemaValidator

(

SchemaValidator *

validator

)

Set the SchemaValidator to be used.

This determines whether schema validation is applied to an input document and whether type annotations in a supplied document are retained. If no SchemaValidator is supplied, then schema validation does not take place.

This option requires the schema-aware version of the Saxon product (Saxon-EE).

Since a SchemaValidator is serially reusable but not thread-safe, using this method is not appropriate when the DocumentBuilder is shared between threads.

Parameters

validator

- the SchemaValidator to be used

---

The documentation for this class was generated from the following files:

• /Users/debbie/Work/refactor/saxon12/libsaxonc/src/include/saxonc/DocumentBuilder.h
• /Users/debbie/Work/refactor/saxon12/libsaxonc/src/lib/DocumentBuilder.cpp