Package org.json

Class XMLParserConfiguration


  • public class XMLParserConfiguration
    extends ParserConfiguration
    Configuration object for the XML parser. The configuration is immutable.
    • Constructor Summary

      Constructors 
      Modifier 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, java.lang.String cDataTagName)
      Deprecated.
      This constructor has been deprecated in favor of using the new builder pattern for the configuration.
        XMLParserConfiguration​(boolean keepStrings, java.lang.String cDataTagName, boolean convertNilAttributeToNull)
      Deprecated.
      This constructor has been deprecated in favor of using the new builder pattern for the configuration.
      private XMLParserConfiguration​(boolean keepStrings, java.lang.String cDataTagName, boolean convertNilAttributeToNull, java.util.Map<java.lang.String,​XMLXsiTypeConverter<?>> xsiTypeMap, java.util.Set<java.lang.String> forceList, int maxNestingDepth, boolean closeEmptyTag)
      Configure the parser to use custom settings.
        XMLParserConfiguration​(java.lang.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.
      java.lang.String getcDataTagName()
      The name of the key in a JSON Object that indicates a CDATA section.
      java.util.Set<java.lang.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
      java.util.Map<java.lang.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()
      Checks if the parser should automatically close empty XML tags.
      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()
      Checks if the parser should trim white spaces from XML content.
      XMLParserConfiguration withcDataTagName​(java.lang.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​(java.util.Set<java.lang.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​(java.util.Map<java.lang.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 java.lang.Object

        equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • KEEP_STRINGS

        public static final XMLParserConfiguration KEEP_STRINGS
        Original configuration of the XML Parser except that values are kept as strings.
      • cDataTagName

        private java.lang.String cDataTagName
        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.
      • convertNilAttributeToNull

        private boolean convertNilAttributeToNull
        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)
      • closeEmptyTag

        private boolean closeEmptyTag
        When creating an XML from JSON Object, an empty tag by default will self-close. If it has to be closed explicitly, with empty content between start and end tag, this flag is to be turned on.
      • xsiTypeMap

        private java.util.Map<java.lang.String,​XMLXsiTypeConverter<?>> xsiTypeMap
        This will allow type conversion for values in XML if xsi:type attribute is defined
      • forceList

        private java.util.Set<java.lang.String> forceList
        When parsing the XML into JSON, specifies the tags whose values should be converted to arrays
      • shouldTrimWhiteSpace

        private boolean shouldTrimWhiteSpace
        Flag to indicate whether white space should be trimmed when parsing XML. The default behaviour is to trim white space. When this is set to false, inputting XML with tags that are the same as the value of cDataTagName is unsupported. It is recommended to set cDataTagName to a distinct value in this case.
    • 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​(java.lang.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,
                                      java.lang.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,
                                      java.lang.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}.
      • XMLParserConfiguration

        private XMLParserConfiguration​(boolean keepStrings,
                                       java.lang.String cDataTagName,
                                       boolean convertNilAttributeToNull,
                                       java.util.Map<java.lang.String,​XMLXsiTypeConverter<?>> xsiTypeMap,
                                       java.util.Set<java.lang.String> forceList,
                                       int maxNestingDepth,
                                       boolean closeEmptyTag)
        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}.
        xsiTypeMap - new HashMap>() to parse values with attribute xsi:type="integer" as integer, xsi:type="string" as string
        forceList - new HashSet() to parse the provided tags' values as arrays
        maxNestingDepth - int to limit the nesting depth
        closeEmptyTag - boolean to turn on explicit end tag for tag with empty value
    • Method Detail

      • 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 java.lang.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​(java.lang.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 java.util.Map<java.lang.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​(java.util.Map<java.lang.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 java.util.Set<java.lang.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​(java.util.Set<java.lang.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()
        Checks if the parser should automatically close empty XML tags.
        Returns:
        true if empty XML tags should be automatically closed, false otherwise.
      • shouldTrimWhiteSpace

        public boolean shouldTrimWhiteSpace()
        Checks if the parser should trim white spaces from XML content.
        Returns:
        true if white spaces should be trimmed, false otherwise.