net.sf.json.xml
Class XMLSerializer

java.lang.Object
  net.sf.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

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

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.
String[]	getExpandableProperties() Returns a list of properties to be expanded from child to parent.
String	getObjectName() Returns the name used for JSONArray.
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(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	setExpandableProperties(String[] expandableProperties) Sets the list of properties to be expanded from child to parent.
void	setForceTopLevelObject(boolean forceTopLevelObject)
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 wether this serializer is tolerant to namespaces without URIs or not.
void	setObjectName(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(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.
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

Method Detail

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.

getElementName

public String getElementName()

Returns the name used for JSONArray elements.

getExpandableProperties

public String[] getExpandableProperties()

Returns a list of properties to be expanded from child to parent.

getObjectName

public String getObjectName()

Returns the name used for JSONArray.

getRootName

public 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(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

setArrayName

public void setArrayName(String arrayName)

Sets the name used for JSONArray.
Default is 'a'.

setElementName

public void setElementName(String elementName)

Sets the name used for JSONArray elements.
Default is 'e'.

setExpandableProperties

public void setExpandableProperties(String[] expandableProperties)

Sets the list of properties to be expanded from child to parent.

setForceTopLevelObject

public void setForceTopLevelObject(boolean forceTopLevelObject)

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

setNamespaceLenient

public void setNamespaceLenient(boolean namespaceLenient)

Sets wether this serializer is tolerant to namespaces without URIs or not.

setObjectName

public void setObjectName(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(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 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.