public class JSON2XML
extends java.lang.Object
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>
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.
|
public static JSON2XML converter()
public java.lang.String convert(java.lang.Object json)
json
- JSON object or array.public java.lang.String convert(java.lang.Object json, java.lang.String charset)
json
- JSON object or array.charset
- Charset to use.public void setExpandNamedArrays(boolean expand)
setElementName(java.lang.String)
. The array must be named ("a" in this
case) so the name can be used for the element names.expand
- true to expand from child to parent, false to nest the children. The
default is false.public void setArrayName(java.lang.String name)
name
- Name for JSON arrays. If a prefix is required it must be
part of the name with a : delimiter.public void setElementName(java.lang.String name)
name
- Name for JSON array elements. If a prefix is required it must be
part of the name with a : delimiter.public void setElementName(java.lang.String name, java.lang.String xmlElement)
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.public void setObjectName(java.lang.String name)
name
- Name for JSON objects. If a prefix is required it must be
part of the name with a : delimiter.public void changeObjectName(java.lang.String oldName, java.lang.String newName)
oldName
- Original JSON name.newName
- New XML name.public void setRootName(java.lang.String name)
name
- Name for the resulting XML root element.public void setRootName(java.lang.String name, java.lang.String namespace, java.lang.String prefix)
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.public void setUseParentPrefix(boolean useParentPrefix)
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.public void addNamespaceDecl(java.lang.String prefix, java.lang.String namespace)
prefix
- Prefix of the namespace being declared.namespace
- URI of the namespace being declared.public void addNamespaceDecl(java.lang.String prefix, java.lang.String namespace, java.lang.String xmlElement)
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.public void setExpandableArrays(java.lang.String[] arrayNames)
setElementName(java.lang.String)
. The array must be named ("a" in this
case) so the name can be used for the element names.arrayNames
- List of array names to expand from child to parent.?? 2022 Perforce Software, All rights reserved
This software is the confidential and proprietary information of Perforce, Inc. and is subject to copyright protection under laws of the United States of America and other countries. The use of this software should be in accordance with the license agreement terms you entered into with Perforce, Inc.