nu.xom
Class Builder

Object
nu.xom.Builder

public class Builder

extends Object

This class is responsible for creating XOM Document
objects from a URL, file, string, or input stream by reading
an XML document. A SAX parser is used to read the
document and report any well-formedness errors.

Version:

1.2.6

Author:

Elliotte Rusty Harold

Constructor Summary

Builder()
Creates a Builder that uses the default node
factory and chooses among any available SAX2 parsers.

Builder(boolean validate)
Creates a Builder based on an optionally validating
parser.

Builder(boolean validate,
NodeFactory factory)
Creates a Builder based on an optionally
validating parser that builds node objects with the supplied
factory.

Builder

Creates a Builder that uses the default node
factory and chooses among any available SAX2 parsers.
In order of preference, it looks for:

Xerces 2.x (a.k.a. IBM XML parser for Java)

GNU Ælfred

Crimson

Piccolo

Oracle

XP

Saxon's Ælfred

dom4j's Ælfred

The platform default specified by the
org.xml.sax.driver system property

Parsers must implicitly or explicitly support the
http://xml.org/sax/features/external-general-entities
and
http://xml.org/sax/features/external-parameter-entities
features XOM requires. Parsers that don't are rejected
automatically.

Throws:

XMLException - if no satisfactory parser is
installed in the local class path

Builder

public Builder(boolean validate)

Creates a Builder based on an optionally validating
parser. If the validate argument
is true, then a validity error while
parsing will cause a fatal error; that is,
it will throw a ValidityException.

Parameters:

validate - true if the parser should
validate the document while parsing

Throws:

XMLException - if no satisfactory parser
is installed in the local class path

Builder

Creates a Builder based on an optionally
validating parser that builds node objects with the supplied
factory. If the validate argument is true, then
a validity error while parsing will cause a fatal error; that
is, it will throw a ValidityException.

Parameters:

validate - true if the parser should
validate the document while parsing

factory - the NodeFactory that creates
the node objects for this Builder

Throws:

XMLException - if no satisfactory parser
is installed in the local class path

Builder

public Builder(org.xml.sax.XMLReader parser)

Creates a Builder that uses
the specified SAX XMLReader.
Custom SAX features and properties such as
schema validation can be set on this XMLReader
before passing it to this method.

Builder

Creates a Builder that uses
the specified NodeFactory to create
node objects.

Parameters:

factory - the NodeFactory that creates
the node objects for this Builder

Throws:

XMLException - if no satisfactory parser is
installed in the local class path

Builder

public Builder(org.xml.sax.XMLReader parser,
boolean validate)

Creates a optionally validating Builder based
on the specified parser object. Custom SAX features and
properties such as schema validation can be set on this
XMLReader before passing it to this method.

If the validate argument is true, then a validity error
while parsing will cause a fatal error; that is, it
will throw a ParsingException

Parameters:

parser - the SAX2 XMLReader that parses
the document

validate - true if the parser should validate
the document while parsing

Builder

Creates an optionally validating Builder that reads
data from the specified parser object and constructs new nodes
using the specified factory object. Custom SAX features and
properties such as schema validation can be set on this
XMLReader before passing it to this method.

If the validate argument is true, then a validity
error while parsing will throw a ParsingException.

Parameters:

parser - the SAX2 XMLReader that parses
the document

validate - true if the parser should validate the
document while parsing

factory - the NodeFactory
this builder uses to create objects in the tree

build

Note that relative URLs generally do not work here, as
there's no base to resolve them against. This includes
relative URLs that point into the file system, though this
is somewhat platform dependent. Furthermore, file
URLs often only work when they adhere exactly to RFC 2396
syntax. URLs that work in Internet Explorer often fail when
used in Java. If you're reading XML from a file, more reliable
results are obtained by using the build method
that takes a java.io.File object as an argument.

Parameters:

systemID - an absolute URL from which the document is read.
The URL's scheme must be one supported by the Java VM.

Returns:

the parsed Document

Throws:

ValidityException - if a validity error is detected. This
is only thrown if the builder has been instructed to validate.