com.soa.json.xml.script

Class JSON2XML

java.lang.Object

com.soa.json.xml.script.JSON2XML

public class JSON2XML
extends java.lang.Object

Utility for converting JSON to XML.

To obtain a converter from a script use:

converter = JSON2XML.converter();

To perform the conversion simply call:

xml = converter.convert(json);

Note that depending on the scripting language in use, it may be necessary to use the fully qualified class name to create a converter, e.g.:

converter = com.soa.json.xml.script.JSON2XML.converter();

Typically JSON content begins with an anonymous object or array. XML needs a root element. There are a few different approaches for controlling the output root XML element. Using setRootName(String) will dictate the name of the XML root element. There will be no namespace or prefix. So calling

converter.setRootName("myRoot");

with JSON input of

{ "a" : 1 }

will result in

<myRoot><a>1</a></myRoot>

As an alternative setObjectName(String) and setArrayName(String) can be used to name the root XML element if the input content is a JSON object or array respectively. For example, calling

converter.setArrayName("myArray");

with JSON input of

[ 1, 2 ]

will result in

<myArray><e>1</e><e>2</e></myArray>

To add a namespace and an optional prefix use setRootName(String, String, String). For example, calling

converter.setRootName("myRoot", "http://myns", "n1");

with JSON input of

{ "a" : 1 }

will result in

<n1:myRoot xmlns:n1="http://myns"><a>1</a></n1:myRoot>

XML does not have the concept of an array like JSON does. XML will need to create an element for each JSON array element. Since the JSON array elements are not named the converter will have to create names for the JSON array elements on its own. By default the name of the XML element for each JSON array element will be 'e'. See the example for setArrayName(String) above. This can be changed however using setElementName(String). For example, calling

converter.setElementName("num");

with JSON input of

[ 1, 2 ]

will result in

<myArray><num>1</num><num>2</num></myArray>

This will change all array elements to use the same XML element name. It is common however to want different XML names for different JSON arrays. To configure different names for a particular array use setElementName(String,String). This establishes a new name for JSON array elements starting from the given XML element in the XML hierarchy. It will apply to all arrays within that hierarchy. So by calling

converter.setElementName("num1");
converter.setElementName("num2, "b");

with JSON input of

{ "a" : [ 1, 2 ], "b" : [ 3, 4 ] }

will result in

<myRoot><a><num1>1</num1><num1>2</num1></a> <b><num2>3</num2><num2>4</num2></b></myRoot>

By default JSON names are used as-is when generating XML element names. This can be changed by using changeObjectName(String, String). For example, calling

converter.changeObjectName("a", "apple");
converter.changeObjectName("b", "brick");

with JSON input of

{ "a" : 1, "b" : 2 }

will result in

<myRoot><apple>1</apple>;<brick>2</brick></myRoot>

If the JSON content does not have any prefixes in its names and XML namespace prefixes are required either use changeObjectName(String, String) for each JSON name or use setUseParentPrefix(boolean) if the prefix to be used is the same throughout the resulting document and established in the root element. For example

converter.setRootName("myRoot", "http://myns", "n1");
converter.setUseParentPrefix(true);

with JSON input of

{ "a" : 1 }

will result in

<n1:myRoot xmlns:n1="http://myns"><n1:a>1</n1:a></n1:myRoot>

If not all sub-elements in the output XML share the same namespace and prefix as the root element a combination of calls can be made as follows:

converter.setRootName("myRoot", "http://myns", "n1");
converter.setUseParentPrefix(true);
converter.changeObjectName("b", "n2:b");
converter.addNamespaceDecl("n2", "http://myns2", "n2:b");

with JSON input of

{ "a" : 1, "b" : { "c" : 2 } }

will result in

<n1:myRoot xmlns:n1="http://myns">
<n1:a>1</n1:a>
<n2:b xmlns:n2="http://myns2">
<n2:c>2</n2:c>
</n2:b>
</n1:myRoot>

Method Summary

Modifier and Type	Method and Description
void	addNamespaceDecl(java.lang.String prefix, java.lang.String namespace) Adds a namespace declaration to the root XML element.
void	addNamespaceDecl(java.lang.String prefix, java.lang.String namespace, java.lang.String xmlElement) Adds a namespace declaration to the given generated XML element.
void	changeObjectName(java.lang.String oldName, java.lang.String newName) Changes the name that a JSON object will have when converted to XML.
java.lang.String	convert(java.lang.Object json) Converts a JSON object or array to an XML string.
java.lang.String	convert(java.lang.Object json, java.lang.String charset) Converts a JSON object or array to an XML string using the given charset.
static JSON2XML	converter() Returns a JSON2XML converter.
void	setArrayName(java.lang.String name) Establishes a default XML element name for all un-named JSON arrays.
void	setElementName(java.lang.String name) Establishes a default XML element name for all un-named JSON array elements.
void	setElementName(java.lang.String name, java.lang.String xmlElement) Establishes a default XML element name for all un-named JSON array elements starting from the given XML element in the XML hierarchy.
void	setExpandableArrays(java.lang.String[] arrayNames) Identifies a list of array properties by their names that will be expanded.
void	setExpandNamedArrays(boolean expand) Indicates whether to automatically expand from child to parent all named array elements.
void	setObjectName(java.lang.String name) Establishes a default XML element name for all un-named JSON objects.
void	setRootName(java.lang.String name) Sets the output root XML element's name.
void	setRootName(java.lang.String name, java.lang.String namespace, java.lang.String prefix) Sets the output root XML element's name.
void	setUseParentPrefix(boolean useParentPrefix) Indicates whether prefixes from parent XML elements should automatically be applied to children elements or not.

Methods inherited from class java.lang.Object

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

Method Detail

converter

public static JSON2XML converter()

Returns a JSON2XML converter.

Returns:

JSON2XML converter.

convert

public java.lang.String convert(java.lang.Object json)

Converts a JSON object or array to an XML string.

Parameters:

json - JSON object or array.

Returns:

XML string.

convert

public java.lang.String convert(java.lang.Object json,
                                java.lang.String charset)

Converts a JSON object or array to an XML string using the given charset.

Parameters:

json - JSON object or array.

charset - Charset to use.

Returns:

XML string.

setExpandNamedArrays

public void setExpandNamedArrays(boolean expand)

Indicates whether to automatically expand from child to parent all named array elements. For example, by setting to true the JSON structure of { "a" : { "b" : [ "1", "2" ] } } will result in XML of <a><b>1</b><b>2</b></a> and a setting of false will result in XML of <a><b><e>1</e><e>2</e></b></a> where 'e' is controlled by setElementName(java.lang.String). The array must be named ("a" in this case) so the name can be used for the element names.

Parameters:

expand - true to expand from child to parent, false to nest the children. The default is false.

setArrayName

public void setArrayName(java.lang.String name)

Establishes a default XML element name for all un-named JSON arrays. If setRootName() has not been called and the root JSON object is an array this name will become the root XML element name. The default name is 'a'.

Parameters:

name - Name for JSON arrays. If a prefix is required it must be part of the name with a : delimiter.

setElementName

public void setElementName(java.lang.String name)

Establishes a default XML element name for all un-named JSON array elements. The default name is 'e'.

Parameters:

name - Name for JSON array elements. If a prefix is required it must be part of the name with a : delimiter.

setElementName

public void setElementName(java.lang.String name,
                           java.lang.String xmlElement)

Establishes a default XML element name for all un-named JSON array elements starting from the given XML element in the XML hierarchy. Typically this will be the XML element name for the array itself. Note it will be the default name for any sub-arrays unless changed.

Parameters:

name - Name for JSON array elements. If a prefix is required it must be part of the name with a : delimiter.

xmlElement - Name of the XML element at which point the given name will become the default. If a prefix is required it must be part of the name with a : delimiter.

setObjectName

public void setObjectName(java.lang.String name)

Establishes a default XML element name for all un-named JSON objects. If setRootName() has not been called and the root JSON object is an object this name will become the root XML element name. The default name is 'o'.

Parameters:

name - Name for JSON objects. If a prefix is required it must be part of the name with a : delimiter.

changeObjectName

public void changeObjectName(java.lang.String oldName,
                             java.lang.String newName)

Changes the name that a JSON object will have when converted to XML. By default an XML element's name will be identical to the original JSON's object. If the JSON object did not have a namespace prefix for example, the XML element would not after conversion. This method could be used to apply that namespace for example or change the name to something else entirely.

Parameters:

oldName - Original JSON name.

newName - New XML name.

setRootName

public void setRootName(java.lang.String name)

Sets the output root XML element's name. The element will have no namespace.

Parameters:

name - Name for the resulting XML root element.

setRootName

public void setRootName(java.lang.String name,
                        java.lang.String namespace,
                        java.lang.String prefix)

Sets the output root XML element's name. The element will have the given namespace and prefix (if supplied).

Parameters:

name - Local part of the root XML element name.

namespace - Namespace of the root XML element name.

prefix - Prefix for the namespace of the root XML element. Optional, can be null.

setUseParentPrefix

public void setUseParentPrefix(boolean useParentPrefix)

Indicates whether prefixes from parent XML elements should automatically be applied to children elements or not. By default namespace prefixes are not added. The input JSON names must have the prefixes in them already. If the input JSON names do not have namespace prefixes and the goal is to have them in the resulting XML then either changeObjectName() must be called for each JSON name without a prefix or use this setting or both. By setting this to true when an XML element is created, if the parent XML element has a prefix it will automatically be added to the new element.

Parameters:

useParentPrefix - True if namespace prefixes should automatically match the parent XML elements created or false to leave namespace prefixes to match the incoming JSON names.

addNamespaceDecl

public void addNamespaceDecl(java.lang.String prefix,
                             java.lang.String namespace)

Adds a namespace declaration to the root XML element.

Parameters:

prefix - Prefix of the namespace being declared.

namespace - URI of the namespace being declared.

addNamespaceDecl

public void addNamespaceDecl(java.lang.String prefix,
                             java.lang.String namespace,
                             java.lang.String xmlElement)

Adds a namespace declaration to the given generated XML element.

Parameters:

prefix - Prefix of the namespace being declared.

namespace - URI of the namespace being declared.

xmlElement - Generated XML element that will have the declaration. Note: if the generated XML element has a prefix it must be part of this parameter.

setExpandableArrays

public void setExpandableArrays(java.lang.String[] arrayNames)

Identifies a list of array properties by their names that will be expanded. When an array is expanded the array elements are converted to XML as a sequence of repetitive XML elements with their local names equal to the JSON array name. For example, by including the array name of "b" the JSON structure of { "a" : { "b" : [ "1", "2" ] } } will result in XML of 12 and not including the array name will result in XML of <a><b><e>1</e><e>2</e></b></a> where 'e' is controlled by setElementName(java.lang.String). The array must be named ("a" in this case) so the name can be used for the element names.

Parameters:

arrayNames - List of array names to expand from child to parent.