nu.xom
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.2b1
Constructor Summary | |
---|---|
Builder()
Creates a | |
Builder(boolean validate)
Creates a | |
Builder(boolean validate, NodeFactory factory)
Creates a | |
Builder(XMLReader parser)
Creates a | |
Builder(NodeFactory factory)
Creates a | |
Builder(XMLReader parser, boolean validate)
Creates a optionally validating | |
Builder(XMLReader parser, boolean validate, NodeFactory factory)
Creates an optionally validating |
Method Summary | |
---|---|
Document | build(String systemID) Parses the document at the specified URL. |
Document | build(InputStream in) Reads the document from an input stream. |
Document | build(InputStream in, String baseURI) Reads the document from an input stream while specifying a base URI (which need not be the stream's actual URI). |
Document | build(File in) Reads the document from a file. |
Document | build(Reader in) Reads the document from a reader. |
Document | build(Reader in, String baseURI) Reads the document from a character stream while specifying a base URI. |
Document | build(String document, String baseURI) Reads the document from the contents of a string. |
NodeFactory | getNodeFactory()
Returns this builder's |
Creates a Builder
that uses the default node
factory and chooses among any available SAX2 parsers.
In order of preference, it looks for:
org.xml.sax.driver
system propertyParsers 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
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
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
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.
Parameters: parser the SAX2 XMLReader
that
parses the document
Throws: XMLException if parser
does not support the
features XOM requires
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
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
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
Throws: XMLException if parser
does not support
the features XOM requires
Parses the document at the specified URL.
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 the URL (generally absolute) 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. ParsingException if a well-formedness error is detected IOException if an I/O error such as a broken socket prevents the document from being fully read
Reads the document from an input stream.
Parameters: in the input stream from which the document is read
Returns: the parsed Document
Throws: ValidityException if a validity error is detected;
only thrown if the builder has been instructed to validate ParsingException if a well-formedness error is detected IOException if an I/O error such as a broken
socket prevents the document from being fully read NullPointerException if in
is null
Reads the document from an input stream while specifying a base URI (which need not be the stream's actual URI).
Parameters: in the input stream from which the document is read baseURI the base URI for this document
Returns: the parsed Document
Throws: ValidityException if a validity error is detected; only thrown if the builder has been instructed to validate ParsingException if a well-formedness error is detected IOException if an I/O error such as a broken socket prevents the document from being fully read
Reads the document from a file. The base URI of the document is set to the location of the file.
Parameters: in the file from which the document is read
Returns: the parsed Document
Throws: ValidityException if a validity error is detected. This is only thrown if the builder has been instructed to validate. ParsingException if a well-formedness error is detected IOException if an I/O error such as a bad disk prevents the file from being read
Reads the document from a reader.
Parameters: in the reader from which the document is read
Returns: the parsed Document
Throws: ValidityException if a validity error is detected. This is only thrown if the builder has been instructed to validate. ParsingException if a well-formedness error is detected IOException if an I/O error such as a bad disk prevents the document from being fully read
Reads the document from a character stream while specifying a base URI.
Parameters: in the reader from which the document is read baseURI the base URI for this document
Returns: the parsed Document
Throws: ValidityException if a validity error is detected. This is only thrown if the builder has been instructed to validate. ParsingException if a well-formedness error is detected IOException if an I/O error such as a bad disk prevents the document from being completely read
Reads the document from the contents of a string.
Parameters: document the string that contains the XML document. baseURI the base URI for this document
Returns: the parsed Document
Throws: ValidityException if a validity error is detected. This is only thrown if the builder has been instructed to validate. ParsingException if a well-formedness error is detected IOException if an I/O error such as a bad disk prevents the document's external DTD subset from being read
Returns this builder's NodeFactory
. It may return
null if a factory was not supplied when the builder was created.
Returns: the node factory that was specified in the constructor