Class Builder
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.3.9
- Author:
- Elliotte Rusty Harold
-
Constructor Summary
ConstructorsConstructorDescriptionBuilder()Creates aBuilderthat uses the default node factory and chooses among any available SAX2 parsers.Builder(boolean validate) Creates aBuilderbased on an optionally validating parser.Builder(boolean validate, NodeFactory factory) Creates aBuilderbased on an optionally validating parser that builds node objects with the supplied factory.Builder(NodeFactory factory) Creates aBuilderthat uses the specifiedNodeFactoryto create node objects.Creates aBuilderthat uses the specified SAXXMLReader.Creates a optionally validatingBuilderbased on the specified parser object.Builder(XMLReader parser, boolean validate, NodeFactory factory) Creates an optionally validatingBuilderthat reads data from the specified parser object and constructs new nodes using the specified factory object. -
Method Summary
Modifier and TypeMethodDescriptionReads the document from a file.build(InputStream in) Reads the document from an input stream.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).Reads the document from a reader.Reads the document from a character stream while specifying a base URI.Parses the document at the specified URL.Reads the document from the contents of a string.Returns this builder'sNodeFactory.
-
Constructor Details
-
Builder
public Builder()Creates a
Builderthat 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.driversystem 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
Builderbased on an optionally validating parser. If thevalidateargument is true, then a validity error while parsing will cause a fatal error; that is, it will throw aValidityException.- 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
Builderbased on an optionally validating parser that builds node objects with the supplied factory. If thevalidateargument is true, then a validity error while parsing will cause a fatal error; that is, it will throw aValidityException.- Parameters:
validate- true if the parser should validate the document while parsingfactory- theNodeFactorythat creates the node objects for thisBuilder- Throws:
XMLException- if no satisfactory parser is installed in the local class path
-
Builder
Creates a
Builderthat uses the specified SAXXMLReader. Custom SAX features and properties such as schema validation can be set on thisXMLReaderbefore passing it to this method.- Parameters:
parser- the SAX2XMLReaderthat parses the document- Throws:
XMLException- ifparserdoes not support the features XOM requires
-
Builder
Creates a
Builderthat uses the specifiedNodeFactoryto create node objects.- Parameters:
factory- theNodeFactorythat creates the node objects for thisBuilder- Throws:
XMLException- if no satisfactory parser is installed in the local class path
-
Builder
Creates a optionally validating
Builderbased on the specified parser object. Custom SAX features and properties such as schema validation can be set on thisXMLReaderbefore 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 SAX2XMLReaderthat parses the documentvalidate- true if the parser should validate the document while parsing
-
Builder
Creates an optionally validating
Builderthat 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 thisXMLReaderbefore passing it to this method.If the
validateargument is true, then a validity error while parsing will throw aParsingException.- Parameters:
parser- the SAX2XMLReaderthat parses the documentvalidate- true if the parser should validate the document while parsingfactory- theNodeFactorythis builder uses to create objects in the tree- Throws:
XMLException- ifparserdoes not support the features XOM requires
-
-
Method Details
-
build
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,
fileURLs 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 thebuildmethod that takes ajava.io.Fileobject 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.ParsingException- if a well-formedness error is detectedIOException- if an I/O error such as a broken socket prevents the document from being fully read
-
build
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 validateParsingException- if a well-formedness error is detectedIOException- if an I/O error such as a broken socket prevents the document from being fully readNullPointerException- ifinis null
-
build
public Document build(InputStream in, String baseURI) throws ParsingException, ValidityException, IOException 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 readbaseURI- an absolute URI for this document; may be null- Returns:
- the parsed
Document - Throws:
ValidityException- if a validity error is detected; only thrown if the builder has been instructed to validateParsingException- if a well-formedness error is detectedIOException- if an I/O error such as a broken socket prevents the document from being fully read
-
build
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 detectedIOException- if an I/O error such as a bad disk prevents the file from being read
-
build
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 detectedIOException- if an I/O error such as a bad disk prevents the document from being fully read
-
build
public Document build(Reader in, String baseURI) throws ParsingException, ValidityException, IOException Reads the document from a character stream while specifying a base URI.
- Parameters:
in- the reader from which the document is readbaseURI- the base URI for this document; may be null- 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 detectedIOException- if an I/O error such as a bad disk prevents the document from being completely read
-
build
public Document build(String document, String baseURI) throws ParsingException, ValidityException, IOException Reads the document from the contents of a string.
- Parameters:
document- the string that contains the XML documentbaseURI- the base URI for this document; may be null- 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 detectedIOException- if an I/O error such as a bad disk prevents the document's external DTD subset from being read
-
getNodeFactory
Returns this builder's
NodeFactory. It returns null if a factory was not supplied when the builder was created.- Returns:
- the node factory that was specified in the constructor
-