Package org.kiwiproject.xml

Class KiwiXml

java.lang.Object

org.kiwiproject.xml.KiwiXml

public class KiwiXml
extends Object

Static utilities for converting to/from XML using JAXB and a few other XML-related utilities.

Implementation Note:

the appropriate JAXB dependencies must be available at runtime

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	KiwiXml.NamespaceValidation	Whether validation should be performed or not.

Field Summary

Fields

Modifier and Type	Field	Description
static String	DISABLE_NAMESPACE_VALIDATION	Constant that can be used to disable all namespace validations when converting from XML to objects.

Constructor Summary

Constructors

Constructor	Description
KiwiXml()

Method Summary

Modifier and Type	Method	Description
static void	clearCachedJAXBContextClasses()	Clear the internal cache of class to JAXBContext mappings.
static Set<Class<?>>	getCachedJAXBContextClasses()	Find the classes for which there is a cached JAXBContext.
static Map<String,String>	getNameAndNamespace(Class<?> objectClass)	Extract XML name and namespace from the given class, assuming it is annotated with XmlType.
static String	stripTags(String xml, String... tagsToRemove)	Removes tags from the given XML but ignoring namespaces.
static String	stripTagsConsideringNamespace(String xml, String... tagsToRemove)	Removes tags from the given XML taking into account the full tag name (i.e.
static <T> T	toObject(String xml, Class<T> clazz)	Convert the given XML into an object of the specified type.
static <T> T	toObjectAssertingValid(String xml, Class<T> clazz, KiwiXml.NamespaceValidation namespaceValidation)	Convert the given XML into an object of the specified type, optionally performing namespace validation.
static <T> T	toObjectAssertingValid(String xml, Class<T> clazz, KiwiXml.NamespaceValidation namespaceValidation, List<String> ignoredNamespaces)	Convert the given XML into an object of the specified type, performing basic validation and ignoring the specified namespaces.
static <T> T	toObjectIgnoringNamespace(String xml, Class<T> clazz)	Convert the given XML into an object of the specified type, ignoring any XML namespace information and not performing any namespace validation.
static String	toXml(Object object)	Convert the given object to an XML representation.
static String	toXml(Object object, Class<?> clazz)	Convert the given object to an XML representation.
static String	toXml(Object object, Class<?> clazz, Map<String,Object> marshallerProperties)	Convert the given object to an XML representation.
static <T> boolean	validateXmlMatchesType(String xml, Class<T> clazz)	Validate that the given XML has a namespace that matches the given class, which is generally assumed to be annotated with XmlType.
static <T> boolean	validateXmlMatchesType(String xml, Class<T> clazz, List<String> ignoredNamespaces)	Validate that the given XML has a namespace that matches the given class, which is generally assumed to be annotated with XmlType, but ignoring the given list of namespaces.

Methods inherited from class java.lang.Object

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

Field Detail

DISABLE_NAMESPACE_VALIDATION

public static final String DISABLE_NAMESPACE_VALIDATION

Constant that can be used to disable all namespace validations when converting from XML to objects.

See Also:

toObjectAssertingValid(String, Class, NamespaceValidation, List), Constant Field Values

Constructor Detail

KiwiXml

public KiwiXml()

Method Detail

getCachedJAXBContextClasses

public static Set<Class<?>> getCachedJAXBContextClasses()

Find the classes for which there is a cached JAXBContext. Each time an instance of a class is converted to XML, the JAXBContext is retrieved from an internal cache. If there isn't one, then one is created and stored in the cache.

Returns:

the set of classes for which KiwiXml has a cached JAXBContext. The returned set is an unmodifiable copy of the actual cached classes

Implementation Note:

The internal cache is a static ConcurrentMap.

clearCachedJAXBContextClasses

public static void clearCachedJAXBContextClasses()

Clear the internal cache of class to JAXBContext mappings.

toXml

public static String toXml(Object object)

Convert the given object to an XML representation.

Parameters:

object - the object to convert to XML

Returns:

the XML representation of the object

toXml

public static String toXml(Object object,
                           Class<?> clazz)

Convert the given object to an XML representation.

Parameters:

object - the object to convert to XML

clazz - the type of class being converted

Returns:

the XML representation of the object

toXml

public static String toXml(Object object,
                           Class<?> clazz,
                           Map<String,Object> marshallerProperties)

Convert the given object to an XML representation.

Parameters:

object - the object to convert to XML

clazz - the type of class being converted

marshallerProperties - the properties to be set on the Marshaller during the conversion process

Returns:

the XML representation of the object

See Also:

Marshaller.setProperty(String, Object)

toObject

public static <T> T toObject(String xml,
                             Class<T> clazz)

Convert the given XML into an object of the specified type.

Type Parameters:

T - the target type

Parameters:

xml - the XML to convert

clazz - type of object to convert into

Returns:

a new instance of the specified type

toObjectIgnoringNamespace

public static <T> T toObjectIgnoringNamespace(String xml,
                                              Class<T> clazz)

Convert the given XML into an object of the specified type, ignoring any XML namespace information and not performing any namespace validation.

Type Parameters:

T - the target type

Parameters:

xml - the XML to convert

clazz - type of object to convert into

Returns:

a new instance of the specified type

toObjectAssertingValid

public static <T> T toObjectAssertingValid(String xml,
                                           Class<T> clazz,
                                           KiwiXml.NamespaceValidation namespaceValidation)

Convert the given XML into an object of the specified type, optionally performing namespace validation.

Type Parameters:

T - the target type

Parameters:

xml - the XML to convert

clazz - type of object to convert into

namespaceValidation - should namespace validation be performed or not

Returns:

a new instance of the specified type

toObjectAssertingValid

public static <T> T toObjectAssertingValid(String xml,
                                           Class<T> clazz,
                                           KiwiXml.NamespaceValidation namespaceValidation,
                                           List<String> ignoredNamespaces)

Convert the given XML into an object of the specified type, performing basic validation and ignoring the specified namespaces.

Type Parameters:

T - the target type

Parameters:

xml - the XML to convert

clazz - type of object to convert into

namespaceValidation - should namespace validation be performed or not

ignoredNamespaces - list of namespaces to ignore

Returns:

a new instance of the specified type

validateXmlMatchesType

public static <T> boolean validateXmlMatchesType(String xml,
                                                 Class<T> clazz)

Validate that the given XML has a namespace that matches the given class, which is generally assumed to be annotated with XmlType.

Type Parameters:

T - the type of the target class

Parameters:

xml - the input XML to compare

clazz - the Class to compare; assumed to be annotated with XmlType

Returns:

true if the XML namespace (e.g. xmlns) matches the namespace of the XmlType annotation on the given class

Throws:

XmlRuntimeException - if something bad and unexpected happens. The thrown exception wraps a XMLStreamException or other cause.

validateXmlMatchesType

public static <T> boolean validateXmlMatchesType(String xml,
                                                 Class<T> clazz,
                                                 List<String> ignoredNamespaces)

Validate that the given XML has a namespace that matches the given class, which is generally assumed to be annotated with XmlType, but ignoring the given list of namespaces.

Type Parameters:

T - the type of the target class

Parameters:

xml - the input XML to compare

clazz - the Class to compare; assumed to be annotated with XmlType

ignoredNamespaces - the namespaces to ignore

Returns:

true if the XML namespace (e.g. xmlns) matches the namespace of the XmlType annotation on the given class

Throws:

XmlRuntimeException - if something bad and unexpected happens. The thrown exception wraps a XMLStreamException or other cause.

getNameAndNamespace

public static Map<String,String> getNameAndNamespace(Class<?> objectClass)

Extract XML name and namespace from the given class, assuming it is annotated with XmlType.

If the given class is not annotated with XmlType, we return the namespace as null and the name as the "simple name" of the class from Class.getSimpleName(). This allows some degree of flexibility when working with non-annotated classes, though this should be the exception not the normal situation.

Parameters:

objectClass - the class to get name and namespace from

Returns:

a map containing entries for name and namespace

See Also:

XmlType.name(), XmlType.namespace()

stripTags

public static String stripTags(String xml,
                               String... tagsToRemove)

Removes tags from the given XML but ignoring namespaces.

Parameters:

xml - the XML containing tags to be removed

tagsToRemove - names of the tags to remove

Returns:

XML with the given tags removed

stripTagsConsideringNamespace

public static String stripTagsConsideringNamespace(String xml,
                                                   String... tagsToRemove)

Removes tags from the given XML taking into account the full tag name (i.e. possibly including namespace).

Parameters:

xml - the XML containing tags to be removed

tagsToRemove - names of the tags to remove

Returns:

XML with the given tags removed