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.3.6
  Author:
    Elliotte Rusty Harold

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `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(NodeFactory factory)` Creates a `Builder` that uses the specified `NodeFactory` to create node objects.
    `Builder(org.xml.sax.XMLReader parser)` Creates a `Builder` that uses the specified SAX `XMLReader`.
    `Builder(org.xml.sax.XMLReader parser, boolean validate)` Creates a optionally validating `Builder` based on the specified parser object.
    `Builder(org.xml.sax.XMLReader parser, boolean validate, NodeFactory factory)` Creates an optionally validating `Builder` that reads data from the specified parser object and constructs new nodes using the specified factory object.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `Document` | `build(File in)` Reads the document from a file.
    `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(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 systemID)` Parses the document at the specified URL.
    `Document` | `build(String document, String baseURI)` Reads the document from the contents of a string.
    `NodeFactory` | `getNodeFactory()` Returns this builder's `NodeFactory`.

    - ### Methods inherited from class 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 order of preference, it looks for:

      1. Xerces 2.x (a.k.a. IBM XML parser for Java)
      2. GNU Ælfred
      3. Crimson
      4. Piccolo
      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 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

          public Builder(boolean validate,
                         NodeFactory factory)

      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.

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

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

      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

  - ### Method Detail

    - #### build

          public Document build(String systemID)
                         throws ParsingException,
                                ValidityException,
                                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` - 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 detected
        `IOException` - if an I/O error such as a broken socket prevents the document from being fully read

    - #### build

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

      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

    - #### 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 read
        `baseURI` - 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 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

    - #### build

          public Document build(File in)
                         throws ParsingException,
                                ValidityException,
                                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:
        `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

    - #### build

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

      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

    - #### 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 read
        `baseURI` - 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 detected
        `IOException` - 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 document
        `baseURI` - 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 detected
        `IOException` - if an I/O error such as a bad disk prevents the document's external DTD subset from being read

    - #### getNodeFactory

          public NodeFactory 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

Copyright 2002-2020 Elliotte Rusty Harold
elharo@ibiblio.org