XMLParserConfiguration (JSON in Java 20240205 API)

Package org.json

## Class XMLParserConfiguration

- java.lang.Object
- - org.json.ParserConfiguration
  - - org.json.XMLParserConfiguration

-     public class XMLParserConfiguration
      extends ParserConfiguration

  Configuration object for the XML parser. The configuration is immutable.
  Author:
    AylwardJ

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static XMLParserConfiguration` | `KEEP_STRINGS` | Original configuration of the XML Parser except that values are kept as strings.
    `static XMLParserConfiguration` | `ORIGINAL` | Original Configuration of the XML Parser.

    - ### Fields inherited from class org.json.ParserConfiguration

      `DEFAULT_MAXIMUM_NESTING_DEPTH, keepStrings, maxNestingDepth, UNDEFINED_MAXIMUM_NESTING_DEPTH`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `XMLParserConfiguration()` | Default parser configuration.
    `XMLParserConfiguration​(boolean keepStrings)` | Deprecated. This constructor has been deprecated in favor of using the new builder pattern for the configuration.
    `XMLParserConfiguration​(boolean keepStrings, String cDataTagName)` | Deprecated. This constructor has been deprecated in favor of using the new builder pattern for the configuration.
    `XMLParserConfiguration​(boolean keepStrings, String cDataTagName, boolean convertNilAttributeToNull)` | Deprecated. This constructor has been deprecated in favor of using the new builder pattern for the configuration.
    `XMLParserConfiguration​(String cDataTagName)` | Deprecated. This constructor has been deprecated in favor of using the new builder pattern for the configuration.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected XMLParserConfiguration` | `clone()` | Provides a new instance of the same configuration.
    `String` | `getcDataTagName()` | The name of the key in a JSON Object that indicates a CDATA section.
    `Set<String>` | `getForceList()` | When parsing the XML into JSON, specifies that tags that will be converted to arrays in this configuration `Set<String>` to parse the provided tags' values as arrays
    `Map<String,​XMLXsiTypeConverter<?>>` | `getXsiTypeMap()` | When parsing the XML into JSON, specifies that the values with attribute xsi:type will be converted to target type defined to client in this configuration `Map<String, XMLXsiTypeConverter<?>>` to parse values with attribute xsi:type="integer" as integer, xsi:type="string" as string
    `boolean` | `isCloseEmptyTag()` |
    `boolean` | `isConvertNilAttributeToNull()` | When parsing the XML into JSON, specifies if values with attribute xsi:nil="true" should be kept as attribute(`false`), or they should be converted to `null`(`true`)
    `boolean` | `shouldTrimWhiteSpace()` |
    `XMLParserConfiguration` | `withcDataTagName​(String newVal)` | The name of the key in a JSON Object that indicates a CDATA section.
    `XMLParserConfiguration` | `withCloseEmptyTag​(boolean closeEmptyTag)` | To enable explicit end tag with empty value.
    `XMLParserConfiguration` | `withConvertNilAttributeToNull​(boolean newVal)` | When parsing the XML into JSON, specifies if values with attribute xsi:nil="true" should be kept as attribute(`false`), or they should be converted to `null`(`true`)
    `XMLParserConfiguration` | `withForceList​(Set<String> forceList)` | When parsing the XML into JSON, specifies that tags that will be converted to arrays in this configuration `Set<String>` to parse the provided tags' values as arrays
    `XMLParserConfiguration` | `withKeepStrings​(boolean newVal)` | When parsing the XML into JSON, specifies if values should be kept as strings (`true`), or if they should try to be guessed into JSON values (numeric, boolean, string)
    `XMLParserConfiguration` | `withMaxNestingDepth​(int maxNestingDepth)` | Defines the maximum nesting depth that the parser will descend before throwing an exception when parsing the XML into JSON.
    `XMLParserConfiguration` | `withShouldTrimWhitespace​(boolean shouldTrimWhiteSpace)` | Sets whether whitespace should be trimmed inside of tags.
    `XMLParserConfiguration` | `withXsiTypeMap​(Map<String,​XMLXsiTypeConverter<?>> xsiTypeMap)` | When parsing the XML into JSON, specifies that the values with attribute xsi:type will be converted to target type defined to client in this configuration `Map<String, XMLXsiTypeConverter<?>>` to parse values with attribute xsi:type="integer" as integer, xsi:type="string" as string

    - ### Methods inherited from class org.json.ParserConfiguration

      `getMaxNestingDepth, isKeepStrings`

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

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

- - ### Field Detail

    - #### ORIGINAL

          public static final XMLParserConfiguration ORIGINAL

      Original Configuration of the XML Parser.

    - #### KEEP_STRINGS

          public static final XMLParserConfiguration KEEP_STRINGS

      Original configuration of the XML Parser except that values are kept as strings.

  - ### Constructor Detail

    - #### XMLParserConfiguration

          public XMLParserConfiguration()

      Default parser configuration. Does not keep strings (tries to implicitly convert values), and the CDATA Tag Name is "content". Trims whitespace.

    - #### XMLParserConfiguration

          @Deprecated
          public XMLParserConfiguration​(boolean keepStrings)

      Deprecated.
      This constructor has been deprecated in favor of using the new builder pattern for the configuration. This constructor may be removed in a future release.
      Configure the parser string processing and use the default CDATA Tag Name as "content".
      Parameters:
        `keepStrings` - `true` to parse all values as string. `false` to try and convert XML string values into a JSON value.

    - #### XMLParserConfiguration

          @Deprecated
          public XMLParserConfiguration​(String cDataTagName)

      Deprecated.
      This constructor has been deprecated in favor of using the new builder pattern for the configuration. This constructor may be removed in a future release.
      Configure the parser string processing to try and convert XML values to JSON values and use the passed CDATA Tag Name the processing value. Pass `null` to disable CDATA processing
      Parameters:
        `cDataTagName` - `null` to disable CDATA processing. Any other value to use that value as the JSONObject key name to process as CDATA.

    - #### XMLParserConfiguration

          @Deprecated
          public XMLParserConfiguration​(boolean keepStrings,
                                        String cDataTagName)

      Deprecated.
      This constructor has been deprecated in favor of using the new builder pattern for the configuration. This constructor may be removed in a future release.
      Configure the parser to use custom settings.
      Parameters:
        `keepStrings` - `true` to parse all values as string. `false` to try and convert XML string values into a JSON value.
        `cDataTagName` - `null` to disable CDATA processing. Any other value to use that value as the JSONObject key name to process as CDATA.

    - #### XMLParserConfiguration

          @Deprecated
          public XMLParserConfiguration​(boolean keepStrings,
                                        String cDataTagName,
                                        boolean convertNilAttributeToNull)

      Deprecated.
      This constructor has been deprecated in favor of using the new builder pattern for the configuration. This constructor may be removed or marked private in a future release.
      Configure the parser to use custom settings.
      Parameters:
        `keepStrings` - `true` to parse all values as string. `false` to try and convert XML string values into a JSON value.
        `cDataTagName` - `null` to disable CDATA processing. Any other value to use that value as the JSONObject key name to process as CDATA.
        `convertNilAttributeToNull` - `true` to parse values with attribute xsi:nil="true" as null. `false` to parse values with attribute xsi:nil="true" as {"xsi:nil":true}.

  - ### Method Detail

    - #### clone

          protected XMLParserConfiguration clone()

      Provides a new instance of the same configuration.
      Overrides:
        `clone` in class `ParserConfiguration`

    - #### withKeepStrings

          public XMLParserConfiguration withKeepStrings​(boolean newVal)

      When parsing the XML into JSON, specifies if values should be kept as strings (`true`), or if they should try to be guessed into JSON values (numeric, boolean, string)
      Overrides:
        `withKeepStrings` in class `ParserConfiguration`
      Parameters:
        `newVal` - new value to use for the `keepStrings` configuration option.
      Returns:
        The existing configuration will not be modified. A new configuration is returned.

    - #### getcDataTagName

          public String getcDataTagName()

      The name of the key in a JSON Object that indicates a CDATA section. Historically this has been the value "content" but can be changed. Use `null` to indicate no CDATA processing.
      Returns:
        The `cDataTagName` configuration value.

    - #### withcDataTagName

          public XMLParserConfiguration withcDataTagName​(String newVal)

      The name of the key in a JSON Object that indicates a CDATA section. Historically this has been the value "content" but can be changed. Use `null` to indicate no CDATA processing.
      Parameters:
        `newVal` - new value to use for the `cDataTagName` configuration option.
      Returns:
        The existing configuration will not be modified. A new configuration is returned.

    - #### isConvertNilAttributeToNull

          public boolean isConvertNilAttributeToNull()

      When parsing the XML into JSON, specifies if values with attribute xsi:nil="true" should be kept as attribute(`false`), or they should be converted to `null`(`true`)
      Returns:
        The `convertNilAttributeToNull` configuration value.

    - #### withConvertNilAttributeToNull

          public XMLParserConfiguration withConvertNilAttributeToNull​(boolean newVal)

      When parsing the XML into JSON, specifies if values with attribute xsi:nil="true" should be kept as attribute(`false`), or they should be converted to `null`(`true`)
      Parameters:
        `newVal` - new value to use for the `convertNilAttributeToNull` configuration option.
      Returns:
        The existing configuration will not be modified. A new configuration is returned.

    - #### getXsiTypeMap

          public Map<String,​XMLXsiTypeConverter<?>> getXsiTypeMap()

      When parsing the XML into JSON, specifies that the values with attribute xsi:type will be converted to target type defined to client in this configuration `Map<String, XMLXsiTypeConverter<?>>` to parse values with attribute xsi:type="integer" as integer, xsi:type="string" as string
      Returns:
        `xsiTypeMap` unmodifiable configuration map.

    - #### withXsiTypeMap

          public XMLParserConfiguration withXsiTypeMap​(Map<String,​XMLXsiTypeConverter<?>> xsiTypeMap)

      When parsing the XML into JSON, specifies that the values with attribute xsi:type will be converted to target type defined to client in this configuration `Map<String, XMLXsiTypeConverter<?>>` to parse values with attribute xsi:type="integer" as integer, xsi:type="string" as string
      Parameters:
        `xsiTypeMap` - `new HashMap<String, XMLXsiTypeConverter<?>>()` to parse values with attribute xsi:type="integer" as integer, xsi:type="string" as string
      Returns:
        The existing configuration will not be modified. A new configuration is returned.

    - #### getForceList

          public Set<String> getForceList()

      When parsing the XML into JSON, specifies that tags that will be converted to arrays in this configuration `Set<String>` to parse the provided tags' values as arrays
      Returns:
        `forceList` unmodifiable configuration set.

    - #### withForceList

          public XMLParserConfiguration withForceList​(Set<String> forceList)

      When parsing the XML into JSON, specifies that tags that will be converted to arrays in this configuration `Set<String>` to parse the provided tags' values as arrays
      Parameters:
        `forceList` - `new HashSet<String>()` to parse the provided tags' values as arrays
      Returns:
        The existing configuration will not be modified. A new configuration is returned.

    - #### withMaxNestingDepth

          public XMLParserConfiguration withMaxNestingDepth​(int maxNestingDepth)

      Defines the maximum nesting depth that the parser will descend before throwing an exception when parsing the XML into JSON. The default max nesting depth is 512, which means the parser will throw a JsonException if the maximum depth is reached. Using any negative value as a parameter is equivalent to setting no limit to the nesting depth, which means the parses will go as deep as the maximum call stack size allows.
      Overrides:
        `withMaxNestingDepth` in class `ParserConfiguration`
      Parameters:
        `maxNestingDepth` - the maximum nesting depth allowed to the XML parser
      Returns:
        The existing configuration will not be modified. A new configuration is returned.

    - #### withCloseEmptyTag

          public XMLParserConfiguration withCloseEmptyTag​(boolean closeEmptyTag)

      To enable explicit end tag with empty value.
      Parameters:
        `closeEmptyTag` - new value for the closeEmptyTag property
      Returns:
        same instance of configuration with empty tag config updated

    - #### withShouldTrimWhitespace

          public XMLParserConfiguration withShouldTrimWhitespace​(boolean shouldTrimWhiteSpace)

      Sets whether whitespace should be trimmed inside of tags. *NOTE* Do not use this if you expect your XML tags to have names that are the same as cDataTagName as this is unsupported. cDataTagName should be set to a distinct value in these cases.
      Parameters:
        `shouldTrimWhiteSpace` - boolean to set trimming on or off. Off is default.
      Returns:
        same instance of configuration with empty tag config updated

    - #### isCloseEmptyTag

          public boolean isCloseEmptyTag()

    - #### shouldTrimWhiteSpace

          public boolean shouldTrimWhiteSpace()