com.antelmann.util
Class XmlHelper

java.lang.Object
  com.antelmann.util.XmlHelper

All Implemented Interfaces:

XMLSerializable, DetailedString, Wrapped<Element>, Serializable

Direct Known Subclasses:

RSSChannel, RSSItem

public class XmlHelper
extends Object
implements DetailedString, Serializable, Wrapped<Element>, XMLSerializable

a helper class that allows to easily handle some aspects of an xml source element and also provides some convenient utility functions. Note that this implementation is not synchronized as all operations work on the element that could easily itself be altered outside this instance in another thread - which should be avoided, of course. The only method that will actually change the identity of the embedded element itself is importXML(InputStream).

Since:

15.07.2009, 12:45:42

Author:

Holger Antelmann

See Also:

setBuilderFactory(Class), DatatypeConverter, Serialized Form

Constructor Summary

XmlHelper(DocumentBuilder builder, InputSource source)

XmlHelper(Element element)

XmlHelper(InputSource source)

XmlHelper(String sourceXml)

XmlHelper(URL url)

Method Summary

void	addBinaryElement(String tagName, InputStream in)
Element	addElement(String tagName, String value) adds the generated element (which is also returned) to the given element
Node	append(Element node, XMLSerializable xs)
static Node	append(Element node, XMLSerializable xs, DocumentBuilder builder)
Node	append(XMLSerializable xs)
Node	append(XMLSerializable xs, DocumentBuilder builder)
boolean	containsTag(String name)
int	countTags(String tagName)
static XmlHelper	createDocument(String documentElementName)
static Element	createElement(InputSource source) used by the constructor to generate the element stored internally
static Element	createElement(String source) used by the constructor to generate the element stored internally
static <T> T	deserializeXML(String xml)
static <T> T	deserializeXML(String xml, boolean throwExceptions)
void	exportXML(OutputStream out) exports the entire object as XML and writes it to the given Writer, so that the object can be reconstructed with importXML(InputSource).
String[]	getAllTagText(String tagName)
byte[]	getBinaryTagData(String tagName)
ArrayList<Element>	getChildElements(boolean all) if all is false, only direct child elements are returned
ArrayList<Element>	getChildElements(String tagName, boolean all) if all is false, only direct child elements are returned
static DocumentBuilder	getDocumentBuilder()
Element	getElement()
Element	getFirstChild(String tagName, boolean all) if all is false, only a direct child element is returned
InputSource	getInputSource()
InputStream	getInputStream()
XmlHelper	getParent()
static Hashtable<Class<?>,PersistenceDelegate>	getPersistenceDelegates() allows to register PersistenceDelegate instances for customizing the XML serialization
String	getTagText(String tagName) returns the text for the first tag found with the given name
String	getTagText(String tag, String defaultValue)
static PersistenceDelegate	getToStringDelegator() very useful to provide PersistenceDelegate instances for classes, that can be best created by passing their toString()-value to the constructor.
void	importXML(InputStream source) The object is fully reinitialized with the XML data contained in the given ImputSource, so that the object has the same state as it had during export.
static void	readIntoXMLSerializable(Element node, XMLSerializable xs)
boolean	removeFirstTag(String tagName)
int	removeTags(String tagName, boolean all) if all is false, only those elements that have the root as the parent are removed
static String	serializeXML(Object object) calls serializeXML(Object, boolean) with the option true
static String	serializeXML(Object object, boolean throwExceptions) first uses serializeXML(XMLSerializable) if applicable and then takes the delegates configured in getPersistenceDelegates() to call.
static String	serializeXML(Object object, Map<Class<?>,PersistenceDelegate> delegates)
static String	serializeXML(Object object, Map<Class<?>,PersistenceDelegate> delegates, boolean throwExceptions)
static String	serializeXML(XMLSerializable object)
static void	setBuilderFactory(Class<?> factoryClass)
void	setTagText(String tagName, String value)
void	storeTo(OutputStream out) stores the xml as reformatted xml in utf8 (including flushing/closing)
String	toDetailedString() returns the reformatted xml in utf8 encoding
static String	toXmlString(XMLSerializable xs)
Element	unwrap() returns the embedded instance that this wrapper encloses

Methods inherited from class java.lang.Object

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

Constructor Detail

XmlHelper

public XmlHelper(URL url)
          throws SAXException,
                 IOException,
                 ParserConfigurationException

Throws:

SAXException

IOException

ParserConfigurationException

XmlHelper

public XmlHelper(String sourceXml)
          throws SAXException,
                 IOException,
                 ParserConfigurationException

Throws:

SAXException

IOException

ParserConfigurationException

XmlHelper

public XmlHelper(InputSource source)
          throws SAXException,
                 IOException,
                 ParserConfigurationException

Throws:

SAXException

IOException

ParserConfigurationException

XmlHelper

public XmlHelper(DocumentBuilder builder,
                 InputSource source)
          throws SAXException,
                 IOException,
                 ParserConfigurationException

Throws:

SAXException

IOException

ParserConfigurationException

XmlHelper

public XmlHelper(Element element)

Method Detail

setBuilderFactory

public static void setBuilderFactory(Class<?> factoryClass)

See Also:

com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderFactoryImpl, DocumentBuilderFactory.newInstance()

getDocumentBuilder

public static DocumentBuilder getDocumentBuilder()
                                          throws ParserConfigurationException

Throws:

ParserConfigurationException

createElement

public static Element createElement(String source)
                             throws SAXException,
                                    IOException,
                                    ParserConfigurationException

used by the constructor to generate the element stored internally

Throws:

SAXException

IOException

ParserConfigurationException

createElement

public static Element createElement(InputSource source)
                             throws SAXException,
                                    IOException,
                                    ParserConfigurationException

used by the constructor to generate the element stored internally

Throws:

SAXException

IOException

ParserConfigurationException

createDocument

public static XmlHelper createDocument(String documentElementName)
                                throws ParserConfigurationException

Throws:

ParserConfigurationException

getParent

public XmlHelper getParent()

getChildElements

public ArrayList<Element> getChildElements(boolean all)

if all is false, only direct child elements are returned

getChildElements

public ArrayList<Element> getChildElements(String tagName,
                                           boolean all)

if all is false, only direct child elements are returned

getFirstChild

public Element getFirstChild(String tagName,
                             boolean all)

if all is false, only a direct child element is returned

getAllTagText

public String[] getAllTagText(String tagName)

getTagText

public String getTagText(String tagName)

returns the text for the first tag found with the given name

getTagText

public String getTagText(String tag,
                         String defaultValue)

setTagText

public void setTagText(String tagName,
                       String value)

addBinaryElement

public void addBinaryElement(String tagName,
                             InputStream in)
                      throws IOException

Throws:

IOException

getBinaryTagData

public byte[] getBinaryTagData(String tagName)
                        throws IOException

Throws:

IOException

addElement

public Element addElement(String tagName,
                          String value)

adds the generated element (which is also returned) to the given element

append

public Node append(XMLSerializable xs)
            throws IOException,
                   SAXException,
                   ParserConfigurationException

Throws:

IOException

SAXException

ParserConfigurationException

append

public Node append(XMLSerializable xs,
                   DocumentBuilder builder)
            throws IOException,
                   SAXException

Throws:

IOException

SAXException

append

public Node append(Element node,
                   XMLSerializable xs)
            throws IOException,
                   SAXException,
                   ParserConfigurationException

Throws:

IOException

SAXException

ParserConfigurationException

append

public static Node append(Element node,
                          XMLSerializable xs,
                          DocumentBuilder builder)
                   throws IOException,
                          SAXException

Throws:

IOException

SAXException

readIntoXMLSerializable

public static void readIntoXMLSerializable(Element node,
                                           XMLSerializable xs)
                                    throws IOException,
                                           ClassCastException,
                                           SAXException

Throws:

IOException

ClassCastException

SAXException

toXmlString

public static String toXmlString(XMLSerializable xs)
                          throws IOException

Throws:

IOException

countTags

public int countTags(String tagName)

removeFirstTag

public boolean removeFirstTag(String tagName)

removeTags

public int removeTags(String tagName,
                      boolean all)

if all is false, only those elements that have the root as the parent are removed

containsTag

public boolean containsTag(String name)

getInputSource

public InputSource getInputSource()

toDetailedString

public String toDetailedString()

returns the reformatted xml in utf8 encoding

Specified by:

toDetailedString in interface DetailedString

Returns:

a (potentially multi-line) String providing full details on this object instance

getInputStream

public InputStream getInputStream()

storeTo

public void storeTo(OutputStream out)
             throws IOException

stores the xml as reformatted xml in utf8 (including flushing/closing)

Throws:

IOException

getElement

public final Element getElement()

unwrap

public final Element unwrap()

Description copied from interface: Wrapped

returns the embedded instance that this wrapper encloses

Specified by:

unwrap in interface Wrapped<Element>

exportXML

public void exportXML(OutputStream out)
               throws IOException

Description copied from interface: XMLSerializable

exports the entire object as XML and writes it to the given Writer, so that the object can be reconstructed with importXML(InputSource). The given stream is neither flushed nor closed, so that other data may be effectively written to the InputSource after the method returned.

Specified by:

exportXML in interface XMLSerializable

Throws:

IOException

See Also:

XMLSerializable.importXML(InputStream)

importXML

public void importXML(InputStream source)
               throws SAXException,
                      IOException

Description copied from interface: XMLSerializable

The object is fully reinitialized with the XML data contained in the given ImputSource, so that the object has the same state as it had during export.

Specified by:

importXML in interface XMLSerializable

Throws:

SAXException

IOException

See Also:

XMLSerializable.exportXML(OutputStream)

getToStringDelegator

public static PersistenceDelegate getToStringDelegator()

very useful to provide PersistenceDelegate instances for classes, that can be best created by passing their toString()-value to the constructor.

See Also:

URL, BigDecimal

getPersistenceDelegates

public static Hashtable<Class<?>,PersistenceDelegate> getPersistenceDelegates()

allows to register PersistenceDelegate instances for customizing the XML serialization

Returns:

a map that allows to register additional PersistenceDelegate instances

See Also:

serializeXML(Object, boolean)

serializeXML

public static String serializeXML(Object object)

calls serializeXML(Object, boolean) with the option true

serializeXML

public static String serializeXML(Object object,
                                  boolean throwExceptions)

first uses serializeXML(XMLSerializable) if applicable and then takes the delegates configured in getPersistenceDelegates() to call.

Parameters:

throwExceptions - will be ignored if the object parameter is XMLSerializable serializeXML(Object, Map, boolean)

serializeXML

public static String serializeXML(XMLSerializable object)

serializeXML

public static String serializeXML(Object object,
                                  Map<Class<?>,PersistenceDelegate> delegates)

serializeXML

public static String serializeXML(Object object,
                                  Map<Class<?>,PersistenceDelegate> delegates,
                                  boolean throwExceptions)

deserializeXML

public static <T> T deserializeXML(String xml)

See Also:

deserializeXML(String, boolean)

deserializeXML

@Warning(value="the return value may be unsavely casted if generics are involved")
public static <T> T deserializeXML(String xml,
                                                boolean throwExceptions)