DocumentBuilder Class Reference

#include <DocumentBuilder.h>

Public Member Functions
	~DocumentBuilder ()
void	setLineNumbering (bool option)
bool	isLineNumbering ()
void	setSchemaValidator (SchemaValidator *validator)
SchemaValidator *	getSchemaValidator ()
void	setDTDValidation (bool option)
bool	isDTDValidation ()
void	setBaseUri (const char *uri)
const char *	getBaseUri ()
XdmNode *	parseXmlFromString (const char *content, const char *encoding=nullptr)
XdmNode *	parseXmlFromFile (const char *filename)
XdmNode *	parseXmlFromUri (const char *source)
bool	exceptionOccurred ()
void	exceptionClear ()
	Clear any exception thrown.
const char *	getErrorMessage ()
	Get the error message if an error has been reported by JNI.
const char *	getErrorCode ()
	Get the error code if an error has been reported by JNI.
SaxonApiException *	getException ()
	Get the SaxonApiException object created when we have an error.

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 Configuration. 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.

Constructor & Destructor Documentation

~DocumentBuilder()

DocumentBuilder::~DocumentBuilder

(

)

DocumentBuilder Destructor

Member Function Documentation

exceptionOccurred()

bool DocumentBuilder::exceptionOccurred

(

)

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

Returns

bool - true when there is a pending exception; otherwise return 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.

getErrorCode()

const char * DocumentBuilder::getErrorCode

(

)

Get the error code if an error has been reported by JNI.

After the execution of the XPath expression there may be a number of errors reported against it.

Returns

char* - The error code of the exception.

getErrorMessage()

const char * DocumentBuilder::getErrorMessage

(

)

Get the error message if an error has been reported by JNI.

A transformation may have a number of errors reported against it.

Returns

char* - The message of the exception

getException()

SaxonApiException * DocumentBuilder::getException

(

)

Get the SaxonApiException object created when we have an error.

After the execution of the processor if there is an error, then a SaxonApiException is created. NULL returned if there is no error.

Returns

SaxonApiException object of the exception thrown.

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.

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 supplied file

Returns

the XdmNode representing the root of the document tree

Remarks

if any failure occurs retrieving or parsing the document the exception methods will provide more information

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	of the source string argument. If not specified then platform default encoding is used

Returns

An XdmNode. This will be the document node at the root of the tree of the resulting in-memory document.

Remarks

if any failure occurs retrieving or parsing the document the exception methods will provide more information

parseXmlFromUri()

XdmNode * DocumentBuilder::parseXmlFromUri

(

const char *

source

)

Build a document from a supplied URI source

Parameters

source

- URI to the XML source

Returns

An XdmNode. This will be the document node at the root of the tree of the resulting in-memory document.

Remarks

if any failure occurs retrieving or parsing the document the exception methods will provide more information

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

)

Say whether line and column numbering and 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:

• Saxon.C.API/DocumentBuilder.h
• Saxon.C.API/DocumentBuilder.cpp