Package net.sf.json.xml

Class XMLSerializer

  • public class XMLSerializer
extends java.lang.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

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addNamespace​(java.lang.String prefix, java.lang.String uri)
      Adds a namespace declaration to the root element.
      void addNamespace​(java.lang.String prefix, java.lang.String uri, java.lang.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.
      void clearNamespaces()
      Removes all namespaces declarations (from root an elements).
      void clearNamespaces​(java.lang.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.
      java.lang.String getArrayName()
      Returns the name used for JSONArray.
      java.lang.String getElementName()
      Returns the name used for JSONArray elements.
      java.lang.String[] getExpandableProperties()
      Returns a list of properties to be expanded from child to parent.
      java.lang.String getObjectName()
      Returns the name used for JSONArray.
      java.lang.String getRootName()
      Returns the name used for the root element.
      boolean isForceTopLevelObject()  
      boolean isNamespaceLenient()
      Returns wether this serializer is tolerant to namespaces without URIs or not.
      boolean isRemoveNamespacePrefixFromElements()
      Returns wether this serializer will remove namespace prefix from elements or not.
      boolean isSkipNamespaces()
      Returns wether this serializer will skip adding namespace declarations to elements or not.
      boolean isSkipWhitespace()
      Returns wether this serializer will skip whitespace or not.
      boolean isTrimSpaces()
      Returns wether this serializer will trim leading and trealing whitespace from values or not.
      boolean isTypeHintsCompatibility()
      Returns true if types hints will have a 'json_' prefix or not.
      boolean isTypeHintsEnabled()
      Returns true if JSON types will be included as attributes.
      JSON read​(java.lang.String xml)
      Creates a JSON value from a XML string.
      JSON readFromFile​(java.io.File file)
      Creates a JSON value from a File.
      JSON readFromFile​(java.lang.String path)
      Creates a JSON value from a File.
      JSON readFromStream​(java.io.InputStream stream)
      Creates a JSON value from an input stream.
      void removeNamespace​(java.lang.String prefix)
      Removes a namespace from the root element.
      void removeNamespace​(java.lang.String prefix, java.lang.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.
      void setArrayName​(java.lang.String arrayName)
      Sets the name used for JSONArray.
      Default is 'a'.
      void setElementName​(java.lang.String elementName)
      Sets the name used for JSONArray elements.
      Default is 'e'.
      void setExpandableProperties​(java.lang.String[] expandableProperties)
      Sets the list of properties to be expanded from child to parent.
      void setForceTopLevelObject​(boolean forceTopLevelObject)  
      void setNamespace​(java.lang.String prefix, java.lang.String uri)
      Sets the namespace declaration to the root element.
      Any previous values are discarded.
      void setNamespace​(java.lang.String prefix, java.lang.String uri, java.lang.String elementName)
      Adds a namespace declaration to an element.
      Any previous values are discarded.
      void setNamespaceLenient​(boolean namespaceLenient)
      Sets wether this serializer is tolerant to namespaces without URIs or not.
      void setObjectName​(java.lang.String objectName)
      Sets the name used for JSONObject.
      Default is 'o'.
      void setRemoveNamespacePrefixFromElements​(boolean removeNamespacePrefixFromElements)
      Sets if this serializer will remove namespace prefix from elements when reading.
      void setRootName​(java.lang.String rootName)
      Sets the name used for the root element.
      void setSkipNamespaces​(boolean skipNamespaces)
      Sets if this serializer will skip adding namespace declarations to elements when reading.
      void setSkipWhitespace​(boolean skipWhitespace)
      Sets if this serializer will skip whitespace when reading.
      void setTrimSpaces​(boolean trimSpaces)
      Sets if this serializer will trim leading and trealing whitespace from values when reading.
      void setTypeHintsCompatibility​(boolean typeHintsCompatibility)
      Sets wether types hints will have a 'json_' prefix or not.
      void setTypeHintsEnabled​(boolean typeHintsEnabled)
      Sets wether JSON types will be included as attributes.
      java.lang.String write​(JSON json)
      Writes a JSON value into a XML string with UTF-8 encoding.
      java.lang.String write​(JSON json, java.lang.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.

      • Methods inherited from class java.lang.Object

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

    • 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

    • Method Detail

      • addNamespace

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

      • addNamespace

        public void addNamespace​(java.lang.String prefix,
                         java.lang.String uri,
                         java.lang.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​(java.lang.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 java.lang.String getArrayName()
        Returns the name used for JSONArray.

      • getElementName

        public java.lang.String getElementName()
        Returns the name used for JSONArray elements.

      • getExpandableProperties

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

      • getObjectName

        public java.lang.String getObjectName()
        Returns the name used for JSONArray.

      • getRootName

        public java.lang.String getRootName()
        Returns the name used for the root element.

      • isForceTopLevelObject

        public boolean isForceTopLevelObject()

      • isNamespaceLenient

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

      • isRemoveNamespacePrefixFromElements

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

      • isSkipNamespaces

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

      • isSkipWhitespace

        public boolean isSkipWhitespace()
        Returns wether this serializer will skip whitespace or not.

      • isTrimSpaces

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

      • isTypeHintsCompatibility

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

      • isTypeHintsEnabled

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

      • read

        public JSON read​(java.lang.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​(java.io.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​(java.lang.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​(java.io.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​(java.lang.String prefix)
        Removes a namespace from the root element.
        Parameters:
        prefix - namespace prefix

      • removeNamespace

        public void removeNamespace​(java.lang.String prefix,
                            java.lang.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

      • setArrayName

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

      • setElementName

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

      • setExpandableProperties

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

      • setForceTopLevelObject

        public void setForceTopLevelObject​(boolean forceTopLevelObject)

      • setNamespace

        public void setNamespace​(java.lang.String prefix,
                         java.lang.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​(java.lang.String prefix,
                         java.lang.String uri,
                         java.lang.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

      • setNamespaceLenient

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

      • setObjectName

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

      • setRemoveNamespacePrefixFromElements

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

      • setRootName

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

      • setSkipNamespaces

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

      • setSkipWhitespace

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

      • setTrimSpaces

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

      • setTypeHintsCompatibility

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

      • setTypeHintsEnabled

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

      • write

        public java.lang.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 java.lang.String write​(JSON json,
                              java.lang.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.