org.cybergarage.xml

## Class Parser

- java.lang.Object
- - org.cybergarage.xml.Parser

- Direct Known Subclasses:
    JaxpParser

      public abstract class Parser
      extends Object

  Abstract base class for XML parsers.

  This class provides the foundation for parsing XML documents from various sources including URLs, files, and strings. It includes security measures specific to I2P to prevent access to localhost and private networks.

  Key features:

  - Abstract parse method for InputStream implementation
  - URL parsing with security checks
  - File parsing support
  - String parsing support
  - I2P-specific security restrictions

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Parser()` Creates a new Parser instance.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `Node` | `parse(File descriptionFile)` Parses XML content from the specified file.
    `abstract Node` | `parse(InputStream inStream)` Parses XML content from the specified input stream.
    `Node` | `parse(String descr)` Parses XML content from the specified string.
    `Node` | `parse(URL locationURL)` Parses XML content from the specified URL.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### Parser

          public Parser()

      Creates a new Parser instance.

  - ### Method Detail

    - #### parse

          public Node parse(File descriptionFile)
                     throws ParserException

      Parses XML content from the specified file.
      Parameters:
        `descriptionFile` - the file containing XML content to parse
      Returns:
        the root node of the parsed XML document
      Throws:
        `ParserException` - if file reading fails or parsing fails

    - #### parse

          public abstract Node parse(InputStream inStream)
                              throws ParserException

      Parses XML content from the specified input stream.

      This is the core parsing method that must be implemented by subclasses. The implementation should parse the XML content and return the root node of the parsed XML document.

      Parameters:
        `inStream` - the input stream containing XML content
      Returns:
        the root node of the parsed XML document
      Throws:
        `ParserException` - if parsing fails

    - #### parse

          public Node parse(String descr)
                     throws ParserException

      Parses XML content from the specified string.

      The string is assumed to contain UTF-8 encoded XML content.

      Parameters:
        `descr` - the string containing XML content to parse
      Returns:
        the root node of the parsed XML document
      Throws:
        `ParserException` - if parsing fails

    - #### parse

          public Node parse(URL locationURL)
                     throws ParserException

      Parses XML content from the specified URL.

      This method includes I2P-specific security checks to prevent access to localhost and private networks. Only HTTP URLs are supported.

      Parameters:
        `locationURL` - the URL to fetch and parse XML content from
      Returns:
        the root node of the parsed XML document
      Throws:
        `ParserException` - if URL validation fails, HTTP request fails, or parsing fails