org.apache.commons.io.input

## Class XmlStreamReader

- java.lang.Object
- - java.io.Reader
  - - org.apache.commons.io.input.XmlStreamReader

- All Implemented Interfaces:
    Closeable, AutoCloseable, Readable

      public class XmlStreamReader
      extends Reader

  Character stream that handles all the necessary Voodoo to figure out the charset encoding of the XML document within the stream.

  IMPORTANT: This class is not related in any way to the org.xml.sax.XMLReader. This one IS a character stream.

  All this has to be done without consuming characters from the stream, if not the XML parser will not recognized the document as a valid XML. This is not 100% true, but it's close enough (UTF-8 BOM is not handled by all parsers right now, XmlStreamReader handles it and things work in all parsers).

  The XmlStreamReader class handles the charset encoding of XML documents in Files, raw streams and HTTP streams by offering a wide set of constructors.

  By default the charset encoding detection is lenient, the constructor with the lenient flag can be used for a script (following HTTP MIME and XML specifications). All this is nicely explained by Mark Pilgrim in his blog, Determining the character encoding of a feed.

  To build an instance, use `XmlStreamReader.Builder`.

  Originally developed for ROME under Apache License 2.0.

  See Also:
    `XmlStreamReader.Builder`, `XmlStreamWriter`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `XmlStreamReader.Builder` Builds a new `XmlStreamWriter`.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static Pattern` | `ENCODING_PATTERN` Pattern capturing the encoding of the `'xml'` processing instruction.

    - ### Fields inherited from class java.io.Reader

      `lock`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `XmlStreamReader(URL url)` Constructs a Reader using the InputStream of a URL.
    `XmlStreamReader(URLConnection urlConnection, String defaultEncoding)` Constructs a Reader using the InputStream of a URLConnection.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static XmlStreamReader.Builder` | `builder()` Constructs a new `XmlStreamReader.Builder`.
    `(package private) String` | `calculateHttpEncoding(String bomEnc, String xmlGuessEnc, String xmlEnc, boolean lenient, String httpContentType)` Calculates the HTTP encoding.
    `(package private) String` | `calculateRawEncoding(String bomEnc, String xmlGuessEnc, String xmlEnc)` Calculate the raw encoding.
    `void` | `close()` Closes the XmlStreamReader stream.
    `(package private) static String` | `getContentTypeEncoding(String httpContentType)` Gets the charset parameter value, `null` if not present, `null` if httpContentType is `null`.
    `(package private) static String` | `getContentTypeMime(String httpContentType)` Gets the MIME type or `null` if httpContentType is `null`.
    `String` | `getDefaultEncoding()` Gets the default encoding to use if none is set in HTTP content-type, XML prolog and the rules based on content-type are not adequate.
    `String` | `getEncoding()` Gets the charset encoding of the XmlStreamReader.
    `(package private) static boolean` | `isAppXml(String mime)` Tests if the MIME type belongs to the APPLICATION XML family.
    `(package private) static boolean` | `isTextXml(String mime)` Tests if the MIME type belongs to the TEXT XML family.
    `int` | `read(char[] buf, int offset, int len)` Reads the underlying reader's `read(char[], int, int)` method.

    - ### Methods inherited from class java.io.Reader

      `mark, markSupported, read, read, read, ready, reset, skip`

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

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

- - ### Field Detail

    - #### ENCODING_PATTERN

          public static final Pattern ENCODING_PATTERN

      Pattern capturing the encoding of the `'xml'` processing instruction.

      See also the NT-EncName XML specification.

      Note the documented pattern is:

           EncName   ::=   [A-Za-z] ([A-Za-z0-9._] | '-')*

      However this does not match all the aliases that are supported by Java. For example, `'437'`, `'ISO_8859-1:1987'` and `'ebcdic-de-273+euro'`.

  - ### Constructor Detail

    - #### XmlStreamReader

          public XmlStreamReader(URL url)
                          throws IOException

      Constructs a Reader using the InputStream of a URL.

      If the URL is not of type HTTP and there is not 'content-type' header in the fetched data it uses the same logic used for Files.

      If the URL is a HTTP Url or there is a 'content-type' header in the fetched data it uses the same logic used for an InputStream with content-type.

      It does a lenient charset encoding detection, check the constructor with the lenient parameter for details.

      Parameters:
        `url` - URL to create a Reader from.
      Throws:
        `NullPointerException` - if the input is `null`.
        `IOException` - thrown if there is a problem reading the stream of the URL.

    - #### XmlStreamReader

          public XmlStreamReader(URLConnection urlConnection,
                                 String defaultEncoding)
                          throws IOException

      Constructs a Reader using the InputStream of a URLConnection.

      If the URLConnection is not of type HttpURLConnection and there is not 'content-type' header in the fetched data it uses the same logic used for files.

      If the URLConnection is a HTTP Url or there is a 'content-type' header in the fetched data it uses the same logic used for an InputStream with content-type.

      It does a lenient charset encoding detection, check the constructor with the lenient parameter for details.

      Parameters:
        `urlConnection` - URLConnection to create a Reader from.
        `defaultEncoding` - The default encoding
      Throws:
        `NullPointerException` - if the input is `null`.
        `IOException` - thrown if there is a problem reading the stream of the URLConnection.

  - ### Method Detail

    - #### builder

          public static XmlStreamReader.Builder builder()

      Constructs a new `XmlStreamReader.Builder`.
      Returns:
        a new `XmlStreamReader.Builder`.

    - #### calculateHttpEncoding

          String calculateHttpEncoding(String bomEnc,
                                       String xmlGuessEnc,
                                       String xmlEnc,
                                       boolean lenient,
                                       String httpContentType)
                                throws IOException

      Calculates the HTTP encoding.
      Parameters:
        `bomEnc` - BOM encoding
        `xmlGuessEnc` - XML Guess encoding
        `xmlEnc` - XML encoding
        `lenient` - indicates if the charset encoding detection should be relaxed.
        `httpContentType` - The HTTP content type
      Returns:
        the HTTP encoding
      Throws:
        `IOException` - thrown if there is a problem reading the stream.

    - #### calculateRawEncoding

          String calculateRawEncoding(String bomEnc,
                                      String xmlGuessEnc,
                                      String xmlEnc)
                               throws IOException

      Calculate the raw encoding.
      Parameters:
        `bomEnc` - BOM encoding
        `xmlGuessEnc` - XML Guess encoding
        `xmlEnc` - XML encoding
      Returns:
        the raw encoding
      Throws:
        `IOException` - thrown if there is a problem reading the stream.

    - #### close

          public void close()
                     throws IOException

      Closes the XmlStreamReader stream.
      Specified by:
        `close` in interface `Closeable`
      Specified by:
        `close` in interface `AutoCloseable`
      Specified by:
        `close` in class `Reader`
      Throws:
        `IOException` - thrown if there was a problem closing the stream.

    - #### getContentTypeEncoding

          static String getContentTypeEncoding(String httpContentType)

      Gets the charset parameter value, `null` if not present, `null` if httpContentType is `null`.
      Parameters:
        `httpContentType` - the HTTP content type
      Returns:
        The content type encoding (upcased)

    - #### getContentTypeMime

          static String getContentTypeMime(String httpContentType)

      Gets the MIME type or `null` if httpContentType is `null`.
      Parameters:
        `httpContentType` - the HTTP content type
      Returns:
        The mime content type

    - #### getDefaultEncoding

          public String getDefaultEncoding()

      Gets the default encoding to use if none is set in HTTP content-type, XML prolog and the rules based on content-type are not adequate.

      If it is `null` the content-type based rules are used.

      Returns:
        the default encoding to use.

    - #### getEncoding

          public String getEncoding()

      Gets the charset encoding of the XmlStreamReader.
      Returns:
        charset encoding.

    - #### isAppXml

          static boolean isAppXml(String mime)

      Tests if the MIME type belongs to the APPLICATION XML family.
      Parameters:
        `mime` - The mime type
      Returns:
        true if the mime type belongs to the APPLICATION XML family, otherwise false

    - #### isTextXml

          static boolean isTextXml(String mime)

      Tests if the MIME type belongs to the TEXT XML family.
      Parameters:
        `mime` - The mime type
      Returns:
        true if the mime type belongs to the TEXT XML family, otherwise false

    - #### read

          public int read(char[] buf,
                          int offset,
                          int len)
                   throws IOException

      Reads the underlying reader's `read(char[], int, int)` method.
      Specified by:
        `read` in class `Reader`
      Parameters:
        `buf` - the buffer to read the characters into
        `offset` - The start offset
        `len` - The number of bytes to read
      Returns:
        the number of characters read or -1 if the end of stream
      Throws:
        `IOException` - if an I/O error occurs.