Class XmlNodeBuilder

java.lang.Object
org.apache.maven.internal.xml.XmlNodeBuilder
@Deprecated public class XmlNodeBuilder extends Object
Deprecated.
Use XmlService instead.
Builds an XmlNodeImpl DOM tree from XML input using an XmlPullParser.

All build methods in this class parse a single XML document element (including its children) from the input and return it as an XmlNodeImpl. The caller is responsible for closing any InputStream or Reader passed to these methods.

Multi-document stream reading

When the underlying Reader or InputStream contains multiple concatenated XML documents, each call to build consumes exactly one root element and its children. The stream position is left immediately after the closing tag of that element, so a subsequent call to build with a new parser wrapping the same reader will parse the next document. For example, given a reader over the concatenation of two identical documents:

  String doc = "<?xml version='1.0'?><doc><child>foo</child></doc>";
  Reader r = new StringReader(doc + doc);
  XmlNode first  = XmlService.read(r);   // reads the first <doc>
  XmlNode second = XmlService.read(r);   // reads the second <doc>
  // first.equals(second) is true

Whitespace trimming

By default, text content is trimmed of leading and trailing whitespace. This can be disabled by passing trim = false, or on a per-element basis by setting the xml:space="preserve" attribute on an element.

Empty vs. self-closing elements

Self-closing tags (e.g. <item/>) produce a node whose value is null. An element with an explicit open and close tag but no content (e.g. <item></item>) produces a node whose value is the empty string "".

Child elements vs. text content

If an element contains child elements, the resulting node carries the children and its text value is null, even if there is interleaved text content. If an element contains only text (no child elements), the node carries the text value and has no children.

  • Constructor Details

    • XmlNodeBuilder

      public XmlNodeBuilder()
      Deprecated.

  • Method Details

    • build

      public static XmlNodeImpl build(Reader reader) throws org.codehaus.plexus.util.xml.pull.XmlPullParserException, IOException
      Deprecated.
      Builds an XML node tree from the given reader, trimming whitespace by default and without tracking input locations.
      Parameters:
      reader - the reader to parse XML from
      Returns:
      the parsed XML node tree
      Throws:
      org.codehaus.plexus.util.xml.pull.XmlPullParserException - if the XML is not well-formed
      IOException - if an I/O error occurs while reading

    • build

      public static XmlNodeImpl build(Reader reader, XmlNodeBuilder.InputLocationBuilder locationBuilder) throws org.codehaus.plexus.util.xml.pull.XmlPullParserException, IOException
      Deprecated.
      Builds an XML node tree from the given reader, trimming whitespace by default.
      Parameters:
      reader - the reader to parse XML from
      locationBuilder - optional builder for recording input locations of parsed elements, or null to skip location tracking
      Returns:
      the parsed XML node tree
      Throws:
      org.codehaus.plexus.util.xml.pull.XmlPullParserException - if the XML is not well-formed
      IOException - if an I/O error occurs while reading
      Since:
      3.2.0

    • build

      public static XmlNodeImpl build(InputStream is, String encoding) throws org.codehaus.plexus.util.xml.pull.XmlPullParserException, IOException
      Deprecated.
      Builds an XML node tree from the given input stream, trimming whitespace by default.
      Parameters:
      is - the input stream to parse XML from
      encoding - the character encoding of the stream (e.g. "UTF-8"), or null to let the parser detect it
      Returns:
      the parsed XML node tree
      Throws:
      org.codehaus.plexus.util.xml.pull.XmlPullParserException - if the XML is not well-formed
      IOException - if an I/O error occurs while reading

    • build

      public static XmlNodeImpl build(InputStream is, String encoding, boolean trim) throws org.codehaus.plexus.util.xml.pull.XmlPullParserException, IOException
      Deprecated.
      Builds an XML node tree from the given input stream.
      Parameters:
      is - the input stream to parse XML from
      encoding - the character encoding of the stream (e.g. "UTF-8"), or null to let the parser detect it
      trim - if true, leading and trailing whitespace is removed from text content unless the element has xml:space="preserve"
      Returns:
      the parsed XML node tree
      Throws:
      org.codehaus.plexus.util.xml.pull.XmlPullParserException - if the XML is not well-formed
      IOException - if an I/O error occurs while reading

    • build

      public static XmlNodeImpl build(Reader reader, boolean trim) throws org.codehaus.plexus.util.xml.pull.XmlPullParserException, IOException
      Deprecated.
      Builds an XML node tree from the given reader without location tracking.
      Parameters:
      reader - the reader to parse XML from
      trim - if true, leading and trailing whitespace is removed from text content unless the element has xml:space="preserve"
      Returns:
      the parsed XML node tree
      Throws:
      org.codehaus.plexus.util.xml.pull.XmlPullParserException - if the XML is not well-formed
      IOException - if an I/O error occurs while reading

    • build

      public static XmlNodeImpl build(Reader reader, boolean trim, XmlNodeBuilder.InputLocationBuilder locationBuilder) throws org.codehaus.plexus.util.xml.pull.XmlPullParserException, IOException
      Deprecated.
      Builds an XML node tree from the given reader.
      Parameters:
      reader - the reader to parse XML from
      trim - if true, leading and trailing whitespace is removed from text content unless the element has xml:space="preserve"
      locationBuilder - optional builder for recording input locations of parsed elements, or null to skip location tracking
      Returns:
      the parsed XML node tree
      Throws:
      org.codehaus.plexus.util.xml.pull.XmlPullParserException - if the XML is not well-formed
      IOException - if an I/O error occurs while reading
      Since:
      3.2.0

    • build

      public static XmlNodeImpl build(org.codehaus.plexus.util.xml.pull.XmlPullParser parser) throws org.codehaus.plexus.util.xml.pull.XmlPullParserException, IOException
      Deprecated.
      Builds an XML node tree from the given pull parser, trimming whitespace by default and without tracking input locations.
      Parameters:
      parser - the pull parser positioned at or before the root element's start tag
      Returns:
      the parsed XML node tree
      Throws:
      org.codehaus.plexus.util.xml.pull.XmlPullParserException - if the XML is not well-formed
      IOException - if an I/O error occurs while reading

    • build

      public static XmlNodeImpl build(org.codehaus.plexus.util.xml.pull.XmlPullParser parser, boolean trim) throws org.codehaus.plexus.util.xml.pull.XmlPullParserException, IOException
      Deprecated.
      Builds an XML node tree from the given pull parser without location tracking.
      Parameters:
      parser - the pull parser positioned at or before the root element's start tag
      trim - if true, leading and trailing whitespace is removed from text content unless the element has xml:space="preserve"
      Returns:
      the parsed XML node tree
      Throws:
      org.codehaus.plexus.util.xml.pull.XmlPullParserException - if the XML is not well-formed
      IOException - if an I/O error occurs while reading

    • build

      public static XmlNodeImpl build(org.codehaus.plexus.util.xml.pull.XmlPullParser parser, boolean trim, XmlNodeBuilder.InputLocationBuilder locationBuilder) throws org.codehaus.plexus.util.xml.pull.XmlPullParserException, IOException
      Deprecated.
      Core parsing method. Builds an XML node tree from the given pull parser.

      Parsing begins at the parser's current event and consumes tokens through the matching end tag of the first start tag encountered. When this method returns, the parser is positioned immediately after that end tag, so the caller (or a subsequent build call) can continue reading the same stream.

      Child elements are parsed recursively. If the element contains only text content (no child elements), the text is stored as the node's value. If child elements are present, the text value is null and children are accessible via XmlNodeImpl.getChildren().

      Parameters:
      parser - the pull parser positioned at or before the root element's start tag
      trim - if true, leading and trailing whitespace is removed from text content unless the element has xml:space="preserve"
      locationBuilder - optional builder for recording input locations of parsed elements, or null to skip location tracking
      Returns:
      the parsed XML node tree
      Throws:
      org.codehaus.plexus.util.xml.pull.XmlPullParserException - if the XML is not well-formed
      IOException - if an I/O error occurs while reading
      IllegalStateException - if the end of the document is reached before the root element's end tag is found
      Since:
      3.2.0