nu.xom
Class Builder

java.lang.Object
  extended bynu.xom.Builder

public class Builder
extends java.lang.Object

The Builder 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.0a1
Author:
Elliotte Rusty Harold

Constructor Summary
Builder()
           Creates a Builder that uses the default node factory and chooses among any available SAX2 parsers in the following order:
Builder(boolean validate)
           Creates a Builder based on a fully validating parser.
Builder(boolean validate, NodeFactory factory)
           Creates a Builder based on a fully validating parser that builds node objects with the supplied factory.
Builder(NodeFactory factory)
           Creates a Builder that uses the specified NodeFactory to create node objects.
Builder(org.xml.sax.XMLReader parser)
           Creates a Builder based on the specified SAX parser XMLReader.
Builder(org.xml.sax.XMLReader parser, boolean validate)
           Creates a Builder based on the specified parser object.
Builder(org.xml.sax.XMLReader parser, boolean validate, NodeFactory factory)
           Creates a Builder that reads data from the specified parser object and constructs new nodes using the specified factory object.
 
Method Summary
 Document build(java.io.File in)
           Reads the document from a file.
 Document build(java.io.InputStream in)
           Reads the document from an input stream.
 Document build(java.io.InputStream in, java.lang.String baseURI)
           Reads the document from an input stream while allowing a base URI to be specified.
 Document build(java.io.Reader in)
           Reads the document from a reader.
 Document build(java.io.Reader in, java.lang.String baseURI)
           Reads the document from an input stream while allowing a base URI to be specified.
 Document build(java.lang.String systemID)
           Parses the document at the specified URL.
 Document build(java.lang.String document, java.lang.String baseURI)
           Reads the document from the contents of a String.
 NodeFactory getNodeFactory()
           If a custom NodeFactory was passed to the constructor, then this method returns a reference to it.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Builder

public Builder()

Creates a Builder that uses the default node factory and chooses among any available SAX2 parsers in the following order:

  1. Xerces 2.x (a.k.a. IBM XML parser for Java)
  2. Crimson
  3. Piccolo
  4. GNU Ælfred
  5. Oracle
  6. XP
  7. Saxon's Ælfred
  8. dom4j's Ælfred
  9. 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 a fully 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

public Builder(boolean validate,
               NodeFactory factory)

Creates a Builder based on a fully 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 based on the specified SAX parser 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

Builder

public Builder(NodeFactory factory)

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 parser does not support the features XOM requires

Builder

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

Creates a 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

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

Creates a 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 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
factory - the NodeFactory this builder uses to create objects in the tree
Throws:
XMLException - if parser does not support the features XOM requires
Method Detail

build

public Document build(java.lang.String systemID)
               throws ParsingException,
                      ValidityException,
                      java.io.IOException

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
java.io.IOException - if an I/O error such as a broken socket prevents the document from being fully read

build

public Document build(java.io.InputStream in)
               throws ParsingException,
                      ValidityException,
                      java.io.IOException

Reads the document from an input stream.

Parameters:
in - the InputStream 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
java.io.IOException - if an I/O error such as a broken socket prevents the document from being fully read.

build

public Document build(java.io.InputStream in,
                      java.lang.String baseURI)
               throws ParsingException,
                      ValidityException,
                      java.io.IOException

Reads the document from an input stream while allowing a base URI to be specified.

Parameters:
in - the InputStream 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
java.io.IOException - if an I/O error such as a broken socket prevents the document from being fully read

build

public Document build(java.io.File in)
               throws ParsingException,
                      ValidityException,
                      java.io.IOException

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:
ParsingException - if a well-formedness error is detected
java.io.IOException - if an I/O error such as a bad disk prevents the file from being read
ValidityException - if a validity error is detected. This is only thrown if the builder has been instructed to validate.

build

public Document build(java.io.Reader in)
               throws ParsingException,
                      ValidityException,
                      java.io.IOException

Reads the document from a reader.

Parameters:
in - the Reader from which the document is read
Returns:
the parsed Document
Throws:
ParsingException - if a well-formedness error is detected
java.io.IOException - if an I/O error such as a bad disk prevents the document from being fully read
ValidityException - if a validity error is detected. This is only thrown if the builder has been instructed to validate.

build

public Document build(java.io.Reader in,
                      java.lang.String baseURI)
               throws ParsingException,
                      ValidityException,
                      java.io.IOException

Reads the document from an input stream while allowing a base URI to be specified.

Parameters:
in - the Reader from which the document is read
baseURI - the base URI for this document
Returns:
the parsed Document
Throws:
ParsingException - if a well-formedness error is detected
java.io.IOException - if an I/O error such as a bad disk prevents the document from being completely read
ValidityException - if a validity error is detected. This is only thrown if the builder has been instructed to validate.

build

public Document build(java.lang.String document,
                      java.lang.String baseURI)
               throws ParsingException,
                      ValidityException,
                      java.io.IOException

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:
java.io.IOException - if an I/O error such as a bad disk prevents the document's external DTD subset from being read
ParsingException - if a well-formedness error is detected
ValidityException - if a validity error is detected. This is only thrown if the builder has been instructed to validate.

getNodeFactory

public NodeFactory getNodeFactory()

If a custom NodeFactory was passed to the constructor, then this method returns a reference to it. If no NodeFactory was passed to the constructor, then this method returns null.

Returns:
the node factory this builder uses, or null if none was specified in the constructor


Copyright 2002-2004 Elliotte Rusty Harold
elharo@metalab.unc.edu