Holger's Java API

## 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)

(c) Holger Antelmann since 2001- all rights reserved (contact: info@antelmann.com)
see www.antelmann.com/developer for further details and available downloads