eu.beesoft.gaia.util
Class XmlReader

java.lang.Object
  extended by org.xml.sax.helpers.DefaultHandler
      extended by eu.beesoft.gaia.util.XmlReader
All Implemented Interfaces:
org.xml.sax.ContentHandler, org.xml.sax.DTDHandler, org.xml.sax.EntityResolver, org.xml.sax.ErrorHandler

public abstract class XmlReader
extends org.xml.sax.helpers.DefaultHandler

This class supports the SAX parsing of the XML stream.

It suppresses the interactivity with W3C (SAX) structures and creates its own structure instead. This structure is called XmlElement and offers these advantages:

All of this is done to make the XML parsing and processing easier. You don't need to create your own structures for each application you write - the XmlElement meets your needs.

There are 3 methods you can / should override in your subclass:

Of course, you can override any of the methods of org.xml.sax.helpers.DefaultHandler, they are accessible, but you will not see it necessary, probably.

Let's look at some example. Here is a part of the XML file, with two nested elements and we want to load it and store data from XML to our instances of Person and City class (they can be some plain value objects):

                <person name="Johny" >
                        <city name="London" />
                </person >
 

Here is a our subclass of XmlReader:

 public class MyXmlProcessor extends XmlReader {
 
        private List<Person> persons = new ArrayList<Person> ();
 
        public List<Person> getPersons () {
                return persons;
        }
 
        public void startElement (XmlElement element) {
                String tag = element.getTag ();
                if ("person".equals (tag)) {
                        Person p = new Person ();
                        String name = element.getElementAttributes ().get ("name");
                        p.setName (name);
                        persons.add (p);
                        // store new Person instance to element as an user object
                        element.setUserObject (p);
                }
                else if ("city".equals (tag)) {
                        City c = new City ();
                        String name = element.getElementAttributes ().get ("name");
                        c.setName (name);
 
                        // here you can see the usage of the user object:
                        Person p = (Person) element.getParentElement ().getUserObject ();
                        p.setCity (c);
                }
        }
 
        public void endElement (XmlElement element) {
                // empty
        }
 
        public void characters (XmlElement element, char[] characters, int offset, int length) {
                // empty
        }
 }
 

And here you can see its usage:

 File xmlFile = new File (...);
 MyXmlProcessor processor = new MyXmlProcessor ();
 processor.read (file);
 List<Person> persons = processor.getPersons ();
 


Constructor Summary
XmlReader()
           
 
Method Summary
 void endElement(java.lang.String uri, java.lang.String localName, java.lang.String qName)
          Overrides method from org.xml.sax.helpers.DefaultHandler to get current XML element and then invokes endElement(XmlElement).
protected  void endElement(XmlElement element)
          Invoked when end of element found in XML stream.
protected  XmlElement getCurrentElement()
          Returns currently processed XML element.
 void characters(char[] characters, int offset, int length)
          Overrides method from org.xml.sax.helpers.DefaultHandler to get current XML element and then invokes characters(XmlElement, char[], int, int).
protected  void characters(XmlElement element, char[] characters, int offset, int length)
          Invoked when some character data found inside the element.
 void read(java.io.File file)
          Loads XML from the file in file-system and starts SAX parser.
 void read(java.io.InputStream inputStream)
          Loads XML from the given input stream and starts SAX parser.
 void read(java.lang.String fileName)
          Loads XML from the file in file-system and starts SAX parser.
 void startElement(java.lang.String uri, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes attributes)
          Overrides method from org.xml.sax.helpers.DefaultHandler to prepare XML element and then invokes startElement(XmlElement).
protected  void startElement(XmlElement element)
          Invoked when the start of the next element found in XML stream.
 
Methods inherited from class org.xml.sax.helpers.DefaultHandler
endDocument, endPrefixMapping, error, fatalError, ignorableWhitespace, notationDecl, processingInstruction, resolveEntity, setDocumentLocator, skippedEntity, startDocument, startPrefixMapping, unparsedEntityDecl, warning
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XmlReader

public XmlReader()
Method Detail

read

public void read(java.lang.String fileName)
Loads XML from the file in file-system and starts SAX parser.

Parameters:
fileName - - name of the XML file

read

public void read(java.io.File file)
Loads XML from the file in file-system and starts SAX parser.

Parameters:
file - - XML file

read

public void read(java.io.InputStream inputStream)
Loads XML from the given input stream and starts SAX parser.

Parameters:
inputStream - - input stream with XML to parse

getCurrentElement

protected XmlElement getCurrentElement()
Returns currently processed XML element.

Returns:
current XML element

startElement

public void startElement(java.lang.String uri,
                         java.lang.String localName,
                         java.lang.String qName,
                         org.xml.sax.Attributes attributes)
Overrides method from org.xml.sax.helpers.DefaultHandler to prepare XML element and then invokes startElement(XmlElement).

Specified by:
startElement in interface org.xml.sax.ContentHandler
Overrides:
startElement in class org.xml.sax.helpers.DefaultHandler
Parameters:
uri - - the Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.
localName - - the local name (without prefix), or the empty string if Namespace processing is not being performed.
qName - - the qualified name (with prefix), or the empty string if qualified names are not available
attributes - - the attributes attached to the element. If there are no attributes, it shall be an empty Attributes object

startElement

protected void startElement(XmlElement element)
Invoked when the start of the next element found in XML stream.

Parameters:
element - - descriptor of started element

characters

public void characters(char[] characters,
                       int offset,
                       int length)
Overrides method from org.xml.sax.helpers.DefaultHandler to get current XML element and then invokes characters(XmlElement, char[], int, int).

Specified by:
characters in interface org.xml.sax.ContentHandler
Overrides:
characters in class org.xml.sax.helpers.DefaultHandler
Parameters:
characters - - the characters.
offset - - the start position in the character array.
length - - the number of characters to use from the character array.

characters

protected void characters(XmlElement element,
                          char[] characters,
                          int offset,
                          int length)
Invoked when some character data found inside the element.

Parameters:
element - - descriptor of current element
characters - - the characters.
offset - - the start position in the character array.
length - - the number of characters to use from the character array.

endElement

public void endElement(java.lang.String uri,
                       java.lang.String localName,
                       java.lang.String qName)
Overrides method from org.xml.sax.helpers.DefaultHandler to get current XML element and then invokes endElement(XmlElement).

Specified by:
endElement in interface org.xml.sax.ContentHandler
Overrides:
endElement in class org.xml.sax.helpers.DefaultHandler
Parameters:
uri - - the Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.
localName - - the local name (without prefix), or the empty string if Namespace processing is not being performed.
qName - - the qualified name (with prefix), or the empty string if qualified names are not available

endElement

protected void endElement(XmlElement element)
Invoked when end of element found in XML stream.

Parameters:
element - - descriptor of current (finished) element