Class XMLSerializer


  • public class XMLSerializer
    extends Object
    Utility class for transforming JSON to XML an back.
    When transforming JSONObject and JSONArray instances to XML, this class will add hints for converting back to JSON.
    Examples:

     JSONObject json = JSONObject.fromObject("{\"name\":\"json\",\"bool\":true,\"int\":1}");
     String xml = new XMLSerializer().write( json );
     <o class="object">
     <name type="string">json</name>
     <bool type="boolean">true</bool>
     <int type="number">1</int>
     </o>
     
     JSONArray json = JSONArray.fromObject("[1,2,3]");
     String xml = new XMLSerializer().write( json );
     <a class="array">
     <e type="number">1</e>
     <e type="number">2</e>
     <e type="number">3</e>
     </a>
     
    Author:
    Andres Almiray
    • Constructor Summary

      Constructors 
      Constructor Description
      XMLSerializer()
      Creates a new XMLSerializer with default options.
      objectName: 'o' arrayName: 'a' elementName: 'e' typeHinstEnabled: true typeHinstCompatibility: true namespaceLenient: false expandableProperties: [] skipNamespaces: false removeNameSpacePrefixFromElement: false trimSpaces: false expandableProperties: [] skipWhitespace: false performAutoExpansion: false keepCData: false escapeLowerChars: false keepArrayName: false
    • Constructor Detail

      • XMLSerializer

        public XMLSerializer()
        Creates a new XMLSerializer with default options.
        • objectName: 'o'
        • arrayName: 'a'
        • elementName: 'e'
        • typeHinstEnabled: true
        • typeHinstCompatibility: true
        • namespaceLenient: false
        • expandableProperties: []
        • skipNamespaces: false
        • removeNameSpacePrefixFromElement: false
        • trimSpaces: false
        • expandableProperties: []
        • skipWhitespace: false
        • performAutoExpansion: false
        • keepCData: false
        • escapeLowerChars: false
        • keepArrayName: false
    • Method Detail

      • isSortPropertyNames

        public boolean isSortPropertyNames()
        Returns whether this serializer will sort object properties by name or not.
      • setSortPropertyNames

        public void setSortPropertyNames​(boolean sortPropertyNames)
        Returns whether this serializer will sort object properties by name or not.
      • addNamespace

        public void addNamespace​(String prefix,
                                 String uri)
        Adds a namespace declaration to the root element.
        Parameters:
        prefix - namespace prefix
        uri - namespace uri
      • addNamespace

        public void addNamespace​(String prefix,
                                 String uri,
                                 String elementName)
        Adds a namespace declaration to an element.
        If the elementName param is null or blank, the namespace declaration will be added to the root element.
        Parameters:
        prefix - namespace prefix
        uri - namespace uri
        elementName - name of target element
      • clearNamespaces

        public void clearNamespaces()
        Removes all namespaces declarations (from root an elements).
      • clearNamespaces

        public void clearNamespaces​(String elementName)
        Removes all namespace declarations from an element.
        If the elementName param is null or blank, the declarations will be removed from the root element.
        Parameters:
        elementName - name of target element
      • getArrayName

        public String getArrayName()
        Returns the name used for JSONArray.
      • setArrayName

        public void setArrayName​(String arrayName)
        Sets the name used for JSONArray.
        Default is 'a'.
      • getElementName

        public String getElementName()
        Returns the name used for JSONArray elements.
      • setElementName

        public void setElementName​(String elementName)
        Sets the name used for JSONArray elements.
        Default is 'e'.
      • getExpandableProperties

        public String[] getExpandableProperties()
        Returns a list of properties to be expanded from child to parent.
      • setExpandableProperties

        public void setExpandableProperties​(String[] expandableProperties)
        Sets the list of properties to be expanded from child to parent.
      • getObjectName

        public String getObjectName()
        Returns the name used for JSONArray.
      • setObjectName

        public void setObjectName​(String objectName)
        Sets the name used for JSONObject.
        Default is 'o'.
      • getRootName

        public String getRootName()
        Returns the name used for the root element.
      • setRootName

        public void setRootName​(String rootName)
        Sets the name used for the root element.
      • isForceTopLevelObject

        public boolean isForceTopLevelObject()
      • setForceTopLevelObject

        public void setForceTopLevelObject​(boolean forceTopLevelObject)
      • isNamespaceLenient

        public boolean isNamespaceLenient()
        Returns whether this serializer is tolerant to namespaces without URIs or not.
      • setNamespaceLenient

        public void setNamespaceLenient​(boolean namespaceLenient)
        Sets whether this serializer is tolerant to namespaces without URIs or not.
      • isRemoveNamespacePrefixFromElements

        public boolean isRemoveNamespacePrefixFromElements()
        Returns whether this serializer will remove namespace prefix from elements or not.
      • setRemoveNamespacePrefixFromElements

        public void setRemoveNamespacePrefixFromElements​(boolean removeNamespacePrefixFromElements)
        Sets if this serializer will remove namespace prefix from elements when reading.
      • isSkipNamespaces

        public boolean isSkipNamespaces()
        Returns whether this serializer will skip adding namespace declarations to elements or not.
      • setSkipNamespaces

        public void setSkipNamespaces​(boolean skipNamespaces)
        Sets if this serializer will skip adding namespace declarations to elements when reading.
      • isSkipWhitespace

        public boolean isSkipWhitespace()
        Returns whether this serializer will skip whitespace or not.
      • setSkipWhitespace

        public void setSkipWhitespace​(boolean skipWhitespace)
        Sets if this serializer will skip whitespace when reading.
      • isTrimSpaces

        public boolean isTrimSpaces()
        Returns whether this serializer will trim leading and trealing whitespace from values or not.
      • setTrimSpaces

        public void setTrimSpaces​(boolean trimSpaces)
        Sets if this serializer will trim leading and trealing whitespace from values when reading.
      • isTypeHintsCompatibility

        public boolean isTypeHintsCompatibility()
        Returns true if types hints will have a 'json_' prefix or not.
      • setTypeHintsCompatibility

        public void setTypeHintsCompatibility​(boolean typeHintsCompatibility)
        Sets whether types hints will have a 'json_' prefix or not.
      • isTypeHintsEnabled

        public boolean isTypeHintsEnabled()
        Returns true if JSON types will be included as attributes.
      • setTypeHintsEnabled

        public void setTypeHintsEnabled​(boolean typeHintsEnabled)
        Sets whether JSON types will be included as attributes.
      • read

        public JSON read​(String xml)
        Creates a JSON value from a XML string.
        Parameters:
        xml - A well-formed xml document in a String
        Returns:
        a JSONNull, JSONObject or JSONArray
        Throws:
        JSONException - if the conversion from XML to JSON can't be made for I/O or format reasons.
      • readFromFile

        public JSON readFromFile​(File file)
        Creates a JSON value from a File.
        Parameters:
        file -
        Returns:
        a JSONNull, JSONObject or JSONArray
        Throws:
        JSONException - if the conversion from XML to JSON can't be made for I/O or format reasons.
      • readFromFile

        public JSON readFromFile​(String path)
        Creates a JSON value from a File.
        Parameters:
        path -
        Returns:
        a JSONNull, JSONObject or JSONArray
        Throws:
        JSONException - if the conversion from XML to JSON can't be made for I/O or format reasons.
      • readFromStream

        public JSON readFromStream​(InputStream stream)
        Creates a JSON value from an input stream.
        Parameters:
        stream -
        Returns:
        a JSONNull, JSONObject or JSONArray
        Throws:
        JSONException - if the conversion from XML to JSON can't be made for I/O or format reasons.
      • removeNamespace

        public void removeNamespace​(String prefix)
        Removes a namespace from the root element.
        Parameters:
        prefix - namespace prefix
      • removeNamespace

        public void removeNamespace​(String prefix,
                                    String elementName)
        Removes a namespace from the root element.
        If the elementName is null or blank, the namespace will be removed from the root element.
        Parameters:
        prefix - namespace prefix
        elementName - name of target element
      • setNamespace

        public void setNamespace​(String prefix,
                                 String uri)
        Sets the namespace declaration to the root element.
        Any previous values are discarded.
        Parameters:
        prefix - namespace prefix
        uri - namespace uri
      • setNamespace

        public void setNamespace​(String prefix,
                                 String uri,
                                 String elementName)
        Adds a namespace declaration to an element.
        Any previous values are discarded. If the elementName param is null or blank, the namespace declaration will be added to the root element.
        Parameters:
        prefix - namespace prefix
        uri - namespace uri
        elementName - name of target element
      • setPerformAutoExpansion

        public void setPerformAutoExpansion​(boolean autoExpansion)
        Sets whether this serializer should perform automatic expansion of array elements or not.
      • setKeepCData

        public void setKeepCData​(boolean keepCData)
        Sets whether this serializer should keep the CDATA information in the value or not.
        Parameters:
        keepCData - True to keep CDATA, false to only use the text value.
      • setEscapeLowerChars

        public void setEscapeLowerChars​(boolean escape)
        Sets whether this serializer should escape characters lower than ' ' in texts.
        Parameters:
        escape - True to escape, false otherwise.
      • setKeepArrayName

        public void setKeepArrayName​(boolean keepName)
        Sets whether this serializer should keep the XML element being an array.
        Parameters:
        keepName - True to include the element name in the JSON object, false otherwise.
      • write

        public String write​(JSON json)
        Writes a JSON value into a XML string with UTF-8 encoding.
        Parameters:
        json - The JSON value to transform
        Returns:
        a String representation of a well-formed xml document.
        Throws:
        JSONException - if the conversion from JSON to XML can't be made for I/O reasons.
      • write

        public String write​(JSON json,
                            String encoding)
        Writes a JSON value into a XML string with an specific encoding.
        If the encoding string is null it will use UTF-8.
        Parameters:
        json - The JSON value to transform
        encoding - The xml encoding to use
        Returns:
        a String representation of a well-formed xml document.
        Throws:
        JSONException - if the conversion from JSON to XML can't be made for I/O reasons or the encoding is not supported.