nu.xom.xinclude

## Class XIncluder

- Object
- - nu.xom.xinclude.XIncluder

-     public class XIncluder
      extends Object

  Implements XInclude resolution as specified in XML Inclusions (XInclude) Version 1.0. Fallbacks are supported. The XPointer `element()` scheme and shorthand XPointers are also supported. The XPointer `xpointer()` scheme is not supported. The `accept` and `accept-language` attributes are supported.

  Version:
    1.3.1
  Author:
    Elliotte Rusty Harold

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `XINCLUDE_NS` The namespace name of all XInclude elements.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Document` | `resolve(Document in)` Returns a copy of the document in which all `xinclude:include` elements have been replaced by their referenced content.
    `static Document` | `resolve(Document in, Builder builder)` Returns a copy of the document in which all `xinclude:include` elements have been replaced by their referenced content as loaded by the builder.
    `static void` | `resolveInPlace(Document in)` Modifies a document by replacing all `xinclude:include` elements by their referenced content.
    `static void` | `resolveInPlace(Document in, Builder builder)` Modifies a document by replacing all `xinclude:include` elements with their referenced content as loaded by the builder.

    - ### Methods inherited from class Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### XINCLUDE_NS

          public static final String XINCLUDE_NS

      The namespace name of all XInclude elements.

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### resolve

          public static Document resolve(Document in)
                                  throws BadParseAttributeException,
                                         InclusionLoopException,
                                         IOException,
                                         NoIncludeLocationException,
                                         ParsingException,
                                         UnsupportedEncodingException,
                                         XIncludeException

      Returns a copy of the document in which all `xinclude:include` elements have been replaced by their referenced content. The original `Document` object is not modified. Resolution is recursive; that is, include elements in the included documents are themselves resolved. The `Document` returned contains no include elements.

      Parameters:
        `in` - the document in which include elements should be resolved
      Returns:
        copy of the document in which all `xinclude:include` elements have been replaced by their referenced content
      Throws:
        `BadParseAttributeException` - if an `include` element has a `parse` attribute with any value other than `text` or `parse`
        `InclusionLoopException` - if the document contains an XInclude element that attempts to include a document in which this element is directly or indirectly included.
        `IOException` - if an included document could not be loaded, and no fallback was available
        `NoIncludeLocationException` - if an `xinclude:include` element does not have an `href` attribute
        `ParsingException` - if an included XML document was malformed
        `UnsupportedEncodingException` - if an included document used an encoding this parser does not support, and no fallback was available
        `XIncludeException` - if the document violates the syntax rules of XInclude
        `XMLException` - if resolving an include element would result in a malformed document

    - #### resolve

          public static Document resolve(Document in,
                                         Builder builder)
                                  throws BadParseAttributeException,
                                         InclusionLoopException,
                                         IOException,
                                         NoIncludeLocationException,
                                         ParsingException,
                                         UnsupportedEncodingException,
                                         XIncludeException

      Returns a copy of the document in which all `xinclude:include` elements have been replaced by their referenced content as loaded by the builder. The original `Document` object is not modified. Resolution is recursive; that is, include elements in the included documents are themselves resolved. The document returned contains no `include` elements.

      Parameters:
        `in` - the document in which include elements should be resolved
        `builder` - the builder used to build the nodes included from other documents
      Returns:
        copy of the document in which all `xinclude:include` elements have been replaced by their referenced content
      Throws:
        `BadParseAttributeException` - if an `include` element has a `parse` attribute with any value other than `text` or `parse`
        `InclusionLoopException` - if the document contains an XInclude element that attempts to include a document in which this element is directly or indirectly included.
        `IOException` - if an included document could not be loaded, and no fallback was available
        `NoIncludeLocationException` - if an `xinclude:include` element does not have an href attribute.
        `ParsingException` - if an included XML document was malformed
        `UnsupportedEncodingException` - if an included document used an encoding this parser does not support, and no fallback was available
        `XIncludeException` - if the document violates the syntax rules of XInclude
        `XMLException` - if resolving an include element would result in a malformed document

    - #### resolveInPlace

          public static void resolveInPlace(Document in)
                                     throws BadParseAttributeException,
                                            InclusionLoopException,
                                            IOException,
                                            NoIncludeLocationException,
                                            ParsingException,
                                            UnsupportedEncodingException,
                                            XIncludeException

      Modifies a document by replacing all `xinclude:include` elements by their referenced content. Resolution is recursive; that is, include elements in the included documents are themselves resolved. The resolved document contains no `xinclude:include` elements.

      If the inclusion fails for any reason—XInclude syntax error, missing resource with no fallback, etc.—the document may be left in a partially resolved state.

      Parameters:
        `in` - the document in which include elements should be resolved
      Throws:
        `BadParseAttributeException` - if an `include` element has a `parse` attribute with any value other than `text` or `parse`
        `InclusionLoopException` - if the document contains an XInclude element that attempts to include a document in which this element is directly or indirectly included
        `IOException` - if an included document could not be loaded, and no fallback was available
        `NoIncludeLocationException` - if an `xinclude:include` element does not have an `href` attribute
        `ParsingException` - if an included XML document was malformed
        `UnsupportedEncodingException` - if an included document used an encoding this parser does not support, and no fallback was available
        `XIncludeException` - if the document violates the syntax rules of XInclude
        `XMLException` - if resolving an include element would result in a malformed document

    - #### resolveInPlace

          public static void resolveInPlace(Document in,
                                            Builder builder)
                                     throws BadParseAttributeException,
                                            InclusionLoopException,
                                            IOException,
                                            NoIncludeLocationException,
                                            ParsingException,
                                            UnsupportedEncodingException,
                                            XIncludeException

      Modifies a document by replacing all `xinclude:include` elements with their referenced content as loaded by the builder. Resolution is recursive; that is, `include` elements in the included documents are themselves resolved. The resolved document contains no `xinclude:include` elements.

      If the inclusion fails for any reason — XInclude syntax error, missing resource with no fallback, etc. — the document may be left in a partially resolved state.

      Parameters:
        `in` - the document in which include elements should be resolved
        `builder` - the builder used to build the nodes included from other documents
      Throws:
        `BadParseAttributeException` - if an `include` element has a `parse` attribute with any value other than `text` or `parse`
        `InclusionLoopException` - if this element contains an XInclude element that attempts to include a document in which this element is directly or indirectly included
        `IOException` - if an included document could not be loaded, and no fallback was available
        `NoIncludeLocationException` - if an `xinclude:include` element does not have an `href` attribute.
        `ParsingException` - if an included XML document was malformed
        `UnsupportedEncodingException` - if an included document used an encoding this parser does not support, and no fallback was available
        `XIncludeException` - if the document violates the syntax rules of XInclude
        `XMLException` - if resolving an include element would result in a malformed document

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