XML (JSON in Java 20240205 API)

Package org.json

## Class XML

- java.lang.Object
- - org.json.XML

-     public class XML
      extends Object

  This provides static methods to convert an XML text into a JSONObject, and to covert a JSONObject into an XML text.
  Version:
    2016-08-10
  Author:
    JSON.org

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static Character` | `AMP` | The Character '&'.
    `static Character` | `APOS` | The Character '''.
    `static Character` | `BANG` | The Character '!'.
    `static Character` | `EQ` | The Character '='.
    `static Character` | `GT` | The Character
    `static Character` | `LT` | The Character '<'.
    `static String` | `NULL_ATTR` | Null attribute name
    `static Character` | `QUEST` | The Character '?'.
    `static Character` | `QUOT` | The Character '"'.
    `static Character` | `SLASH` | The Character '/'.
    `static String` | `TYPE_ATTR` |

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `XML()` |

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static String` | `escape​(String string)` | Replace special characters with XML escapes:
    `static void` | `noSpace​(String string)` | Throw an exception if the string contains whitespace.
    `static Object` | `stringToValue​(String string)` | This method is the same as `JSONObject.stringToValue(String)`.
    `static Object` | `stringToValue​(String string, XMLXsiTypeConverter<?> typeConverter)` | This method tries to convert the given string value to the target object
    `static JSONObject` | `toJSONObject​(Reader reader)` | Convert a well-formed (but not necessarily valid) XML into a JSONObject.
    `static JSONObject` | `toJSONObject​(Reader reader, boolean keepStrings)` | Convert a well-formed (but not necessarily valid) XML into a JSONObject.
    `static JSONObject` | `toJSONObject​(Reader reader, XMLParserConfiguration config)` | Convert a well-formed (but not necessarily valid) XML into a JSONObject.
    `static JSONObject` | `toJSONObject​(String string)` | Convert a well-formed (but not necessarily valid) XML string into a JSONObject.
    `static JSONObject` | `toJSONObject​(String string, boolean keepStrings)` | Convert a well-formed (but not necessarily valid) XML string into a JSONObject.
    `static JSONObject` | `toJSONObject​(String string, XMLParserConfiguration config)` | Convert a well-formed (but not necessarily valid) XML string into a JSONObject.
    `static String` | `toString​(Object object)` | Convert a JSONObject into a well-formed, element-normal XML string.
    `static String` | `toString​(Object object, int indentFactor)` | Convert a JSONObject into a well-formed, pretty printed element-normal XML string.
    `static String` | `toString​(Object object, String tagName)` | Convert a JSONObject into a well-formed, element-normal XML string.
    `static String` | `toString​(Object object, String tagName, int indentFactor)` | Convert a JSONObject into a well-formed, pretty printed element-normal XML string.
    `static String` | `toString​(Object object, String tagName, XMLParserConfiguration config)` | Convert a JSONObject into a well-formed, element-normal XML string.
    `static String` | `toString​(Object object, String tagName, XMLParserConfiguration config, int indentFactor)` | Convert a JSONObject into a well-formed, pretty printed element-normal XML string.
    `static String` | `unescape​(String string)` | Removes XML escapes from the string.

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

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

- - ### Field Detail

    - #### AMP

          public static final Character AMP

      The Character '&'.

    - #### APOS

          public static final Character APOS

      The Character '''.

    - #### BANG

          public static final Character BANG

      The Character '!'.

    - #### EQ

          public static final Character EQ

      The Character '='.

    - #### GT

          public static final Character GT

      The Character

          '>'.

    - #### LT

          public static final Character LT

      The Character '<'.

    - #### QUEST

          public static final Character QUEST

      The Character '?'.

    - #### QUOT

          public static final Character QUOT

      The Character '"'.

    - #### SLASH

          public static final Character SLASH

      The Character '/'.

    - #### NULL_ATTR

          public static final String NULL_ATTR

      Null attribute name
      See Also:
        Constant Field Values

    - #### TYPE_ATTR

          public static final String TYPE_ATTR

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### XML

          public XML()

  - ### Method Detail

    - #### escape

          public static String escape​(String string)

      Replace special characters with XML escapes:

           &amp; (ampersand) is replaced by &amp;amp;
           &lt; (less than) is replaced by &amp;lt;
           &gt; (greater than) is replaced by &amp;gt;
           &quot; (double quote) is replaced by &amp;quot;
           &apos; (single quote / apostrophe) is replaced by &amp;apos;

      Parameters:
        `string` - The string to be escaped.
      Returns:
        The escaped string.

    - #### unescape

          public static String unescape​(String string)

      Removes XML escapes from the string.
      Parameters:
        `string` - string to remove escapes from
      Returns:
        string with converted entities

    - #### noSpace

          public static void noSpace​(String string)
                              throws JSONException

      Throw an exception if the string contains whitespace. Whitespace is not allowed in tagNames and attributes.
      Parameters:
        `string` - A string.
      Throws:
        `JSONException` - Thrown if the string contains whitespace or is empty.

    - #### stringToValue

          public static Object stringToValue​(String string,
                                             XMLXsiTypeConverter<?> typeConverter)

      This method tries to convert the given string value to the target object
      Parameters:
        `string` - String to convert
        `typeConverter` - value converter to convert string to integer, boolean e.t.c
      Returns:
        JSON value of this string or the string

    - #### stringToValue

          public static Object stringToValue​(String string)

      This method is the same as `JSONObject.stringToValue(String)`.
      Parameters:
        `string` - String to convert
      Returns:
        JSON value of this string or the string

    - #### toJSONObject

          public static JSONObject toJSONObject​(String string)
                                         throws JSONException

      Convert a well-formed (but not necessarily valid) XML string into a JSONObject. Some information may be lost in this transformation because JSON is a data format and XML is a document format. XML uses elements, attributes, and content text, while JSON uses unordered collections of name/value pairs and arrays of values. JSON does not does not like to distinguish between elements and attributes. Sequences of similar elements are represented as JSONArrays. Content text may be placed in a "content" member. Comments, prologs, DTDs, and

           &lt;[ [ ]]>

      are ignored.
      Parameters:
        `string` - The source string.
      Returns:
        A JSONObject containing the structured data from the XML string.
      Throws:
        `JSONException` - Thrown if there is an errors while parsing the string

    - #### toJSONObject

          public static JSONObject toJSONObject​(Reader reader)
                                         throws JSONException

      Convert a well-formed (but not necessarily valid) XML into a JSONObject. Some information may be lost in this transformation because JSON is a data format and XML is a document format. XML uses elements, attributes, and content text, while JSON uses unordered collections of name/value pairs and arrays of values. JSON does not does not like to distinguish between elements and attributes. Sequences of similar elements are represented as JSONArrays. Content text may be placed in a "content" member. Comments, prologs, DTDs, and

           &lt;[ [ ]]>

      are ignored.
      Parameters:
        `reader` - The XML source reader.
      Returns:
        A JSONObject containing the structured data from the XML string.
      Throws:
        `JSONException` - Thrown if there is an errors while parsing the string

    - #### toJSONObject

          public static JSONObject toJSONObject​(Reader reader,
                                                boolean keepStrings)
                                         throws JSONException

      Convert a well-formed (but not necessarily valid) XML into a JSONObject. Some information may be lost in this transformation because JSON is a data format and XML is a document format. XML uses elements, attributes, and content text, while JSON uses unordered collections of name/value pairs and arrays of values. JSON does not does not like to distinguish between elements and attributes. Sequences of similar elements are represented as JSONArrays. Content text may be placed in a "content" member. Comments, prologs, DTDs, and

           &lt;[ [ ]]>

      are ignored. All values are converted as strings, for 1, 01, 29.0 will not be coerced to numbers but will instead be the exact value as seen in the XML document.
      Parameters:
        `reader` - The XML source reader.
        `keepStrings` - If true, then values will not be coerced into boolean or numeric values and will instead be left as strings
      Returns:
        A JSONObject containing the structured data from the XML string.
      Throws:
        `JSONException` - Thrown if there is an errors while parsing the string

    - #### toJSONObject

          public static JSONObject toJSONObject​(Reader reader,
                                                XMLParserConfiguration config)
                                         throws JSONException

      Convert a well-formed (but not necessarily valid) XML into a JSONObject. Some information may be lost in this transformation because JSON is a data format and XML is a document format. XML uses elements, attributes, and content text, while JSON uses unordered collections of name/value pairs and arrays of values. JSON does not does not like to distinguish between elements and attributes. Sequences of similar elements are represented as JSONArrays. Content text may be placed in a "content" member. Comments, prologs, DTDs, and

           &lt;[ [ ]]>

      are ignored. All values are converted as strings, for 1, 01, 29.0 will not be coerced to numbers but will instead be the exact value as seen in the XML document.
      Parameters:
        `reader` - The XML source reader.
        `config` - Configuration options for the parser
      Returns:
        A JSONObject containing the structured data from the XML string.
      Throws:
        `JSONException` - Thrown if there is an errors while parsing the string

    - #### toJSONObject

          public static JSONObject toJSONObject​(String string,
                                                boolean keepStrings)
                                         throws JSONException

      Convert a well-formed (but not necessarily valid) XML string into a JSONObject. Some information may be lost in this transformation because JSON is a data format and XML is a document format. XML uses elements, attributes, and content text, while JSON uses unordered collections of name/value pairs and arrays of values. JSON does not does not like to distinguish between elements and attributes. Sequences of similar elements are represented as JSONArrays. Content text may be placed in a "content" member. Comments, prologs, DTDs, and

           &lt;[ [ ]]>

      are ignored. All values are converted as strings, for 1, 01, 29.0 will not be coerced to numbers but will instead be the exact value as seen in the XML document.
      Parameters:
        `string` - The source string.
        `keepStrings` - If true, then values will not be coerced into boolean or numeric values and will instead be left as strings
      Returns:
        A JSONObject containing the structured data from the XML string.
      Throws:
        `JSONException` - Thrown if there is an errors while parsing the string

    - #### toJSONObject

          public static JSONObject toJSONObject​(String string,
                                                XMLParserConfiguration config)
                                         throws JSONException

      Convert a well-formed (but not necessarily valid) XML string into a JSONObject. Some information may be lost in this transformation because JSON is a data format and XML is a document format. XML uses elements, attributes, and content text, while JSON uses unordered collections of name/value pairs and arrays of values. JSON does not does not like to distinguish between elements and attributes. Sequences of similar elements are represented as JSONArrays. Content text may be placed in a "content" member. Comments, prologs, DTDs, and

           &lt;[ [ ]]>

      are ignored. All values are converted as strings, for 1, 01, 29.0 will not be coerced to numbers but will instead be the exact value as seen in the XML document.
      Parameters:
        `string` - The source string.
        `config` - Configuration options for the parser.
      Returns:
        A JSONObject containing the structured data from the XML string.
      Throws:
        `JSONException` - Thrown if there is an errors while parsing the string

    - #### toString

          public static String toString​(Object object)
                                 throws JSONException

      Convert a JSONObject into a well-formed, element-normal XML string.
      Parameters:
        `object` - A JSONObject.
      Returns:
        A string.
      Throws:
        `JSONException` - Thrown if there is an error parsing the string

    - #### toString

          public static String toString​(Object object,
                                        String tagName)

      Convert a JSONObject into a well-formed, element-normal XML string.
      Parameters:
        `object` - A JSONObject.
        `tagName` - The optional name of the enclosing tag.
      Returns:
        A string.
      Throws:
        `JSONException` - Thrown if there is an error parsing the string

    - #### toString

          public static String toString​(Object object,
                                        String tagName,
                                        XMLParserConfiguration config)
                                 throws JSONException

      Convert a JSONObject into a well-formed, element-normal XML string.
      Parameters:
        `object` - A JSONObject.
        `tagName` - The optional name of the enclosing tag.
        `config` - Configuration that can control output to XML.
      Returns:
        A string.
      Throws:
        `JSONException` - Thrown if there is an error parsing the string

    - #### toString

          public static String toString​(Object object,
                                        int indentFactor)

      Convert a JSONObject into a well-formed, pretty printed element-normal XML string.
      Parameters:
        `object` - A JSONObject.
        `indentFactor` - The number of spaces to add to each level of indentation.
      Returns:
        A string.
      Throws:
        `JSONException` - Thrown if there is an error parsing the string

    - #### toString

          public static String toString​(Object object,
                                        String tagName,
                                        int indentFactor)

      Convert a JSONObject into a well-formed, pretty printed element-normal XML string.
      Parameters:
        `object` - A JSONObject.
        `tagName` - The optional name of the enclosing tag.
        `indentFactor` - The number of spaces to add to each level of indentation.
      Returns:
        A string.
      Throws:
        `JSONException` - Thrown if there is an error parsing the string

    - #### toString

          public static String toString​(Object object,
                                        String tagName,
                                        XMLParserConfiguration config,
                                        int indentFactor)
                                 throws JSONException

      Convert a JSONObject into a well-formed, pretty printed element-normal XML string.
      Parameters:
        `object` - A JSONObject.
        `tagName` - The optional name of the enclosing tag.
        `config` - Configuration that can control output to XML.
        `indentFactor` - The number of spaces to add to each level of indentation.
      Returns:
        A string.
      Throws:
        `JSONException` - Thrown if there is an error parsing the string