com.ls.util.xml
Class XMLFragment

java.lang.Object
  |
  +--com.ls.util.xml.XMLFragment
All Implemented Interfaces:
Comparable, Map, Serializable

public class XMLFragment
extends Object
implements Comparable, Map, Serializable

This class represents an XML structure that can deal with attributes, sub elements and any String content. The sub elements are handled in the order as they have been read from the XML source (i.e. in the order as they have been created). Hereby, every sub element itself is an instance of XMLFragment.

Version:
$Revision: 1.19 $
Author:
Last modified by $Author: OHittmeyer $
See Also:
Serialized Form

Inner classes inherited from class java.util.Map
Map.Entry
 
Field Summary
protected  Map documentAttributes
          holds the root element's attributes
protected  Map documentChildren
          holds the root element's sub elements (its 'children')
static String EMTPY_ATTRIBUTE
          constant for specifying that an element's attribute is empty
static String EMTPY_CONTENT
          constant for specifying that an element's content is empty
 
Constructor Summary
XMLFragment(String element)
          Creates an empty XMLFragment having the given root element.
XMLFragment(String element, Map attributes)
          Creates an empty XMLFragment having the given root element and a list of attributes.
 
Method Summary
 void addAttribute(String attributeName, String attributeValue)
          Adds an attribute with the given name and value to the root element of this XMLFragment.
 XMLFragment addChild(String element, String content)
          Adds a new sub element to this XMLFragment.
 void addChild(XMLFragment element)
          Adds a new sub element to this XMLFragment as given by element
 void addChildren(Map elementMapping)
          Adds a new sub element to this XMLFragment.
 void addContent(String stringContent)
          Adds the given stringContent to this XMLFragment's content.
 void clear()
          Any call to this method throws always an UnsupportedOperationException!
 int compareTo(Object object)
          Compares this object with the specified object for order.
 boolean containsKey(Object element)
          Returns whether or not this XMLFragment contains a sub element element .
 boolean containsValue(Object value)
          Returns whether or not this XMLFragment contains a sub element element .
static Map convertToStandardMap(XMLFragment xmlFragment)
          Converts the given XMLFragment object into a 'normal' the java.util.HashMap implementations of the Map interface and returns it.
 Set entrySet()
          Returns a set view of the sub elements contained in this XMLFragment.
 boolean equals(Object object)
          Returns whether or not the given Object is equal to this XMLFragment.
 Object get(Object object)
          Returns the Object which is mapped to the given object.
 String getAttribute(String attributeName)
          Returns the value of the given attribute.
 Object getChild(String element)
          Returns the sub element specified by the given name.
 List getChildren()
          Returns a list of all sub elements.
 List getChildren(String element)
          Returns a list of sub elements as specified by the given name.
 String getContent()
          Returns the content of this XMLFragment.
 String getNamespaceURI()
          Returns the namespace URI for this XMLFragment.
 String getQualifiedName()
          Returns the qualified XML Name for this XMLFragment.
 String getRootName()
          Returns the name of the root element of this XMLFragment.
 boolean hasAttributes()
          Returns whether or not this XMLFragment's root has attributes.
 boolean hasChildren()
          Returns whether or not this XMLFragment contains sub elements.
 boolean isEmpty()
          Returns whether or not there are any sub elements of this XMLFragment.
 boolean isValidXMLName(String stringObject)
          Validates the given String object against the rules of XML Names.
 Iterator iterateAttributes()
          Returns an Iterator view on the attributes of this XMLFragment.
 Iterator iterateChildren()
          Returns an Iterator view on the sub elements of this XMLFragment.
 Set keySet()
          Returns a set view of the names of the sub element contained in this XMLFragment.
 List listChildrenNames()
          Returns a List containing the names of the sub elements.
 int numberOfAttributes()
          Returns the number of attributes of this XMLFragment.
 int numberOfChildren()
          Returns the number of sub elements of this XMLFragment.
static XMLFragment parseXML(Reader reader)
          parses an xml structure from the given reader and creates an XMLFragment from it.
static XMLFragment parseXML(String string)
          parses an xml structure from the given reader and creates an XMLFragment from it.
 Object put(Object element, Object content)
          Creates a new XMLFragment with name element and a content of content.
 void putAll(Map map)
          Adds a number of sub elements to this XMLFragment, as specified in the given Map.
 Object remove(Object o)
          Any call to this method throws always an UnsupportedOperationException!
 void setNamespaceURI(String namespaceURI)
          Sets the namespace URI for this XMLFragment.
 void setQualifiedName(String qName)
          Sets the qualified XML Name for this XMLFragment.
 int size()
          Returns the number of sub elements of this XMLFragment.
 String toString()
          Creates a string representation of this XMLFragment.
 Collection values()
          Any call to this method throws always an UnsupportedOperationException!
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface java.util.Map
hashCode
 

Field Detail

EMTPY_ATTRIBUTE

public static final String EMTPY_ATTRIBUTE
constant for specifying that an element's attribute is empty

EMTPY_CONTENT

public static final String EMTPY_CONTENT
constant for specifying that an element's content is empty

documentAttributes

protected Map documentAttributes
holds the root element's attributes

documentChildren

protected Map documentChildren
holds the root element's sub elements (its 'children')
Constructor Detail

XMLFragment

public XMLFragment(String element)
            throws IllegalArgumentException,
                   XMLException
Creates an empty XMLFragment having the given root element.
Parameters:
element - the root element (tag) of this XMLFragment
Throws:
IllegalArgumentException - if the given root element is null or empty
XMLException - if the given root element is not a valid XML Name

XMLFragment

public XMLFragment(String element,
                   Map attributes)
            throws IllegalArgumentException,
                   XMLException,
                   MissingDataException
Creates an empty XMLFragment having the given root element and a list of attributes.
Parameters:
element - the root element (tag) of this XMLFragment
Throws:
IllegalArgumentException - if the given root element is null or empty
MissingDataException - if the attributes contain objects other than Strings
XMLException - if the given root element is not a valid XML Name, or if the given attributes contain duplicate entries
Method Detail

parseXML

public static XMLFragment parseXML(Reader reader)
                            throws XMLException
parses an xml structure from the given reader and creates an XMLFragment from it.
Parameters:
reader - the source from where to read the xml structure
Returns:
an XMLFragment as created from the xml structure
Throws:
XMLException - if the parsing fails

parseXML

public static XMLFragment parseXML(String string)
                            throws XMLException
parses an xml structure from the given reader and creates an XMLFragment from it.
Parameters:
string - the source from where to read the xml structure
Returns:
an XMLFragment as created from the xml structure
Throws:
XMLException - if the parsing fails

isValidXMLName

public boolean isValidXMLName(String stringObject)
Validates the given String object against the rules of XML Names. A XML Name is a token beginning with a letter or one of a few punctuation characters, and continuing with letters, digits, hyphens, underscores, colons, or full stops, together known as name characters. Names beginning with the string "xml", or any string which would match (('X'|'x') ('M'|'m') ('L'|'l')), are reserved for standardization in the current or future versions of the XML standard.
Parameters:
stringObject - the String to be validated
Returns:
true if the given argument is a valid XML Name

getRootName

public String getRootName()
Returns the name of the root element of this XMLFragment.
Returns:
the root element name

setNamespaceURI

public void setNamespaceURI(String namespaceURI)
Sets the namespace URI for this XMLFragment.
Parameters:
namespaceURI - the namespace URI for this XMLFragment

getNamespaceURI

public String getNamespaceURI()
Returns the namespace URI for this XMLFragment.
Returns:
the namespace URI for this XMLFragment

setQualifiedName

public void setQualifiedName(String qName)
Sets the qualified XML Name for this XMLFragment.
Parameters:
qName - the qualified name for this XMLFragment

getQualifiedName

public String getQualifiedName()
Returns the qualified XML Name for this XMLFragment.
Returns:
the qualified name for this XMLFragment

hasAttributes

public boolean hasAttributes()
Returns whether or not this XMLFragment's root has attributes.
Returns:
true if the root element has attributes

numberOfAttributes

public int numberOfAttributes()
Returns the number of attributes of this XMLFragment.
Returns:
the number of attributes

iterateAttributes

public Iterator iterateAttributes()
Returns an Iterator view on the attributes of this XMLFragment.
Returns:
Iterator

getAttribute

public String getAttribute(String attributeName)
Returns the value of the given attribute.
Parameters:
attributeName - the name of the requested attribute
Returns:
the value of that attribute, null if the attribute does not exist

addAttribute

public void addAttribute(String attributeName,
                         String attributeValue)
                  throws IllegalArgumentException,
                         XMLException
Adds an attribute with the given name and value to the root element of this XMLFragment.
Parameters:
attributeName - the name of the new attribute
attributeValue - the value of the new attribute
Throws:
IllegalArgumentException - if the attribute's name is null or empty
XMLException - if the attribute's name does already exist

hasChildren

public boolean hasChildren()
Returns whether or not this XMLFragment contains sub elements.
Returns:
true if this XMLFragment has 'children'

numberOfChildren

public int numberOfChildren()
Returns the number of sub elements of this XMLFragment.
Returns:
the number of 'children'

listChildrenNames

public List listChildrenNames()
Returns a List containing the names of the sub elements.
Returns:
A List containing the names of the sub elements.

iterateChildren

public Iterator iterateChildren()
Returns an Iterator view on the sub elements of this XMLFragment.
Returns:
Iterator

getChild

public Object getChild(String element)
                throws IllegalArgumentException
Returns the sub element specified by the given name.
Parameters:
element - the name of the sub element to return
Returns:
an XMLFragment object
Throws:
IllegalArgumentException - if the given argument is null or empty

getChildren

public List getChildren()
Returns a list of all sub elements.
Returns:
an List object

getChildren

public List getChildren(String element)
                 throws IllegalArgumentException
Returns a list of sub elements as specified by the given name.
Parameters:
element - the name of the sub element to return
Returns:
an XMLFragment object
Throws:
IllegalArgumentException - if the given argument is null or empty

addChild

public XMLFragment addChild(String element,
                            String content)
                     throws IllegalArgumentException,
                            XMLException
Adds a new sub element to this XMLFragment. The sub elements name is specified by element, its content by content. This method is good for adding simple sub elements. If you want to specify more complex sub elements with attributes and nested childrens, please use the method addChild(XMLFragment) instead.
Parameters:
element - the name of the new sub element
content - the content of the new sub element
Returns:
the newly created XMLFragment instance
Throws:
IllegalArgumentException - if the given argument is null or empty
XMLException - if the given element is not a valid XML Name

addChildren

public void addChildren(Map elementMapping)
                 throws IllegalArgumentException,
                        XMLException
Adds a new sub element to this XMLFragment. The sub elements names and contents have to be specified in the given Map. This method is good for adding simple sub elements. If you want to specify more complex sub elements with attributes and nested childrens, please use the method addChild(XMLFragment) instead.
Parameters:
elementMapping - a Map containing element/content mappings
Throws:
IllegalArgumentException - if element is null or empty
XMLException - if the map contains objects other than Strings

addChild

public void addChild(XMLFragment element)
              throws IllegalArgumentException
Adds a new sub element to this XMLFragment as given by element
Parameters:
element - the new element to be added to this XMLFragment
Throws:
IllegalArgumentException - if the given argument is null

addContent

public void addContent(String stringContent)
Adds the given stringContent to this XMLFragment's content.
Parameters:
stringContent - the content of this XMLFragment

getContent

public String getContent()
Returns the content of this XMLFragment.
Returns:
the content of this xml structure

convertToStandardMap

public static Map convertToStandardMap(XMLFragment xmlFragment)
                                throws IllegalArgumentException,
                                       InvalidArgumentException
Converts the given XMLFragment object into a 'normal' the java.util.HashMap implementations of the Map interface and returns it.
Parameters:
xmlFragment - the XMLFragment to convert
Returns:
a Map view of the given XMLFragment
Throws:
IllegalArgumentException - if the xmlFragment is null
InvalidArgumentException - if the given xmlFragment cannot be converted

compareTo

public int compareTo(Object object)
              throws ClassCastException
Compares this object with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.
Specified by:
compareTo in interface Comparable
Parameters:
object - - the Object to be compared
Returns:
a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object
Throws:
ClassCastException - if the specified object's type prevents it from being compared to this Object

clear

public void clear()
           throws UnsupportedOperationException
Any call to this method throws always an UnsupportedOperationException!
Specified by:
clear in interface Map
Throws:
UnsupportedOperationException - if this method gets invoked (always)

containsKey

public boolean containsKey(Object element)
Returns whether or not this XMLFragment contains a sub element element . The passed argument should be a String object.
Specified by:
containsKey in interface Map
Parameters:
element - the name of a sub element
Returns:
true if the element is available

containsValue

public boolean containsValue(Object value)
Returns whether or not this XMLFragment contains a sub element element . The passed argument should be a XMLFragment object.
Specified by:
containsValue in interface Map
Parameters:
value - a concrete XMLFragment object
Returns:
true if the element is available

entrySet

public Set entrySet()
Returns a set view of the sub elements contained in this XMLFragment.
Specified by:
entrySet in interface Map
Returns:
Set

equals

public boolean equals(Object object)
Returns whether or not the given Object is equal to this XMLFragment.
Specified by:
equals in interface Map
Overrides:
equals in class Object
Parameters:
object - the object to be compared to this XMLFragment
Returns:
true if both objects are equal

get

public Object get(Object object)
           throws ProgrammingException
Returns the Object which is mapped to the given object. This method awaits object to be of type String. The returned object is either of type XMLFragment or List.
Specified by:
get in interface Map
Parameters:
object - the object to be looked up
Returns:
the element being bound to the given object
Throws:
ProgrammingException - if there is an error in the xml structure

isEmpty

public boolean isEmpty()
Returns whether or not there are any sub elements of this XMLFragment.
Specified by:
isEmpty in interface Map
Returns:
true if there exist no sub elements

keySet

public Set keySet()
Returns a set view of the names of the sub element contained in this XMLFragment.
Specified by:
keySet in interface Map
Returns:
Set

put

public Object put(Object element,
                  Object content)
Creates a new XMLFragment with name element and a content of content. The method awaits element to be of type String.
Specified by:
put in interface Map
Parameters:
element - the name of the XMLFragment to be added as child
content - the content of the new XMLFragment
Returns:
the newly created XMLFragment object

putAll

public void putAll(Map map)
            throws IllegalArgumentException
Adds a number of sub elements to this XMLFragment, as specified in the given Map.
Specified by:
putAll in interface Map
Parameters:
map - a Map containing element/content pairs
Throws:
IllegalArgumentException - if the given argument is null
See Also:
put(Object, Object)

remove

public Object remove(Object o)
              throws UnsupportedOperationException
Any call to this method throws always an UnsupportedOperationException!
Specified by:
remove in interface Map
Parameters:
o - the object to be removed from this XMLFragment
Returns:
Normally this method should return a boolean value but in this case this method always raises an exception.
Throws:
UnsupportedOperationException - if this method gets invoked (always)

size

public int size()
Returns the number of sub elements of this XMLFragment.
Specified by:
size in interface Map
Returns:
the number of 'childs'

values

public Collection values()
                  throws UnsupportedOperationException
Any call to this method throws always an UnsupportedOperationException!
Specified by:
values in interface Map
Returns:
Normally this method should return a boolean value but in this case this method always raises an exception.
Throws:
UnsupportedOperationException - if this method gets invoked (always)

toString

public String toString()
Creates a string representation of this XMLFragment.
Overrides:
toString in class Object
Returns:
the string representation of this XMLFragment