XMLSerializer (json-lib 3.0.2-SNAPSHOT)

java.lang.Object
- org.kordamp.json.xml.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 and 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 `forcedArrayElements`: [] `parseJsonLiterals`: true

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addNamespace(String prefix, String uri)` Adds a namespace declaration to the root element.
`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.
`void`	`clearNamespaces()` Removes all namespaces declarations (from root an elements).
`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.
`String`	`getArrayName()` Returns the name used for JSONArray.
`String`	`getElementName()` Returns the name used for JSONArray elements.
`Map`	`getElementNamespace(String elementName)` Returns a read-only view of the particular element name space if found.
`String[]`	`getExpandableProperties()` Returns a list of properties to be expanded from child to parent.
`Collection<String>`	`getForcedArrayElements()` Returns the set of XML elements that force their children to be treated as array elements.
`String`	`getObjectName()` Returns the name used for JSONArray.
`String`	`getRootName()` Returns the name used for the root element.
`Map`	`getRootNamespace()` Returns a read-only view of the root name space.
`boolean`	`isForceTopLevelObject()`
`boolean`	`isNamespaceLenient()` Returns whether this serializer is tolerant to namespaces without URIs or not.
`boolean`	`isParseJsonLiterals()` Returns whether JSON literals are parsed as JSON or not.
`boolean`	`isRemoveNamespacePrefixFromElements()` Returns whether this serializer will remove namespace prefix from elements or not.
`boolean`	`isSkipNamespaces()` Returns whether this serializer will skip adding namespace declarations to elements or not.
`boolean`	`isSkipWhitespace()` Returns whether this serializer will skip whitespace or not.
`boolean`	`isSortPropertyNames()` Returns whether this serializer will sort object properties by name or not.
`boolean`	`isTrimSpaces()` Returns whether 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(String xml)` Creates a JSON value from a XML string.
`JSON`	`readFromFile(File file)` Creates a JSON value from a File.
`JSON`	`readFromFile(String path)` Creates a JSON value from a File.
`JSON`	`readFromStream(InputStream stream)` Creates a JSON value from an input stream.
`void`	`removeNamespace(String prefix)` Removes a namespace from the root element.
`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.
`void`	`setArrayName(String arrayName)` Sets the name used for JSONArray. Default is 'a'.
`void`	`setElementName(String elementName)` Sets the name used for JSONArray elements. Default is 'e'.
`void`	`setEscapeLowerChars(boolean escape)` Sets whether this serializer should escape characters lower than ' ' in texts.
`void`	`setExpandableProperties(String[] expandableProperties)` Sets the list of properties to be expanded from child to parent.
`void`	`setForcedArrayElements(Collection<String> forcedArrayElements)` Defines the set of XML elements that force their children to be treated as array elements.
`void`	`setForceTopLevelObject(boolean forceTopLevelObject)`
`void`	`setKeepArrayName(boolean keepName)` Sets whether this serializer should keep the XML element being an array.
`void`	`setKeepCData(boolean keepCData)` Sets whether this serializer should keep the CDATA information in the value or not.
`void`	`setNamespace(String prefix, String uri)` Sets the namespace declaration to the root element. Any previous values are discarded.
`void`	`setNamespace(String prefix, String uri, String elementName)` Adds a namespace declaration to an element. Any previous values are discarded.
`void`	`setNamespaceLenient(boolean namespaceLenient)` Sets whether this serializer is tolerant to namespaces without URIs or not.
`void`	`setObjectName(String objectName)` Sets the name used for JSONObject. Default is 'o'.
`void`	`setParseJsonLiterals(boolean parseJsonLiterals)` Sets whether JSON literals are parsed as JSON or not.
`void`	`setPerformAutoExpansion(boolean autoExpansion)` Sets whether this serializer should perform automatic expansion of array elements or not.
`void`	`setRemoveNamespacePrefixFromElements(boolean removeNamespacePrefixFromElements)` Sets if this serializer will remove namespace prefix from elements when reading.
`void`	`setRootName(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`	`setSortPropertyNames(boolean sortPropertyNames)` Returns whether this serializer will sort object properties by name or not.
`void`	`setTrimSpaces(boolean trimSpaces)` Sets if this serializer will trim leading and trealing whitespace from values when reading.
`void`	`setTypeHintsCompatibility(boolean typeHintsCompatibility)` Sets whether types hints will have a 'json_' prefix or not.
`void`	`setTypeHintsEnabled(boolean typeHintsEnabled)` Sets whether JSON types will be included as attributes.
`String`	`write(JSON json)` Writes a JSON value into a XML string with UTF-8 encoding.
`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.

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
    - expandableProperties: []
    - skipWhitespace: false
    - performAutoExpansion: false
    - keepCData: false
    - escapeLowerChars: false
    - keepArrayName: false
    - forcedArrayElements: []
    - parseJsonLiterals: true
- Method Detail
  - isParseJsonLiterals
```
public boolean isParseJsonLiterals()
```
    Returns whether JSON literals are parsed as JSON or not.
  - setParseJsonLiterals
```
public void setParseJsonLiterals(boolean parseJsonLiterals)
```
    Sets whether JSON literals are parsed as JSON or not.
  - 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
  - getRootNamespace
```
public Map getRootNamespace()
```
    Returns a read-only view of the root name space.
  - getElementNamespace
```
public Map getElementNamespace(String elementName)
```
    Returns a read-only view of the particular element name space if found.
  - 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.
  - getForcedArrayElements
```
public Collection<String> getForcedArrayElements()
```
    Returns the set of XML elements that force their children to be treated as array elements.
  - setForcedArrayElements
```
public void setForcedArrayElements(Collection<String> forcedArrayElements)
```
    Defines the set of XML elements that force their children to be treated as array elements.
  - 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.

Class XMLSerializer

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

XMLSerializer

Method Detail

isParseJsonLiterals

setParseJsonLiterals

isSortPropertyNames

setSortPropertyNames

addNamespace

addNamespace

getRootNamespace

getElementNamespace

clearNamespaces

clearNamespaces

getArrayName

setArrayName

getElementName

setElementName

getExpandableProperties

setExpandableProperties

getObjectName

setObjectName

getRootName

setRootName

isForceTopLevelObject

setForceTopLevelObject

isNamespaceLenient

setNamespaceLenient

isRemoveNamespacePrefixFromElements

setRemoveNamespacePrefixFromElements

isSkipNamespaces

setSkipNamespaces

isSkipWhitespace

setSkipWhitespace

isTrimSpaces

setTrimSpaces

isTypeHintsCompatibility

setTypeHintsCompatibility

isTypeHintsEnabled

setTypeHintsEnabled

getForcedArrayElements

setForcedArrayElements

read

readFromFile

readFromFile

readFromStream

removeNamespace

removeNamespace

setNamespace

setNamespace

setPerformAutoExpansion

setKeepCData

setEscapeLowerChars

setKeepArrayName

write

write