xmlutil
Class XMLUtil

java.lang.Object
  org.xml.sax.helpers.DefaultHandler
      xmlutil.XMLUtil

All Implemented Interfaces:

org.xml.sax.ContentHandler, org.xml.sax.DTDHandler, org.xml.sax.EntityResolver, org.xml.sax.ErrorHandler

public class XMLUtil

extends org.xml.sax.helpers.DefaultHandler

XMLUtil is a SAX events handler which understands a simple object construction vocabulary designed for extracing patterns like lists and hashes from an XML document; it can also allow custom hooks. The intention is that you will use a tool like XSLT to transform the XML you want to parse into the appropriate form for XMLUtil, which can then handle the boring and repetitive task of parsing the SAX events.

XMLUtil's XML vocabulary consists of a set of content constructors which may be inserted into each other etc etc. Each content constructor produces one java object.

There are two attributes which may appear on any content constructor.

• id: the id attribute specifies a globally unique key which can be referenced once construction is complete.

• custom: the custom attribute indicates that a custom handler should be used to create the final Object for this content constructor. In this case, once the content constructor is finished constructing as it normally would, the handler named in the custom attribute will be passed the constructed object and will be expected to return an Object to be constructed in its stead. So, for example, one might do:

      
      Verndale St.
      Brookline
      MA
      
      

  This would cause a hashtable to be initially constructed with the keys "street", "town", and "state". The custom handler object registered under the name "address" would then be invoked with this hashtable and would return a custom object, likely some representation of an address, which would be inserted.

The different type of content constructors:

Hashtables

    XML Format:
    <hash [id="yyy"]>
    <item>
    &key><!-- content constructor here --></key> 
        <value><!-- content constructor here --></value>
    </item>
    
     
    
    
    ...
    </hash>
    

Once the document is parsed, a hash element will result in the creation of a java.util.Hashtable, with the values and keys one would expect. The shorter form of the 'item' element automatically constructs a String object with the value of the 'key' attribute as the key. The longer form can be used if non String elements are desired or simply to be pedantic. They are totaly equivalent.

Vectors

    XML Format:
    <vect [id="xxx"]>
    <!-- content constructors go here -->
    </vect>
    

vect elements will result in the creation of a java.util.Vector, with the list of elements one would expect.

Strings

    XML Format:
    <string>string text goes here</string>
    

String elements result in the creation of a java.lang.String object.

Longs

    XML Format:
    <long>integer text goes here</long>
    

Long elements result in a java.lang.Long object

References

    XML Format:
    <ref>xxx</ref>
    

Uses the same object that was previously created with the id 'xxx'

Nested Class Summary

protected class

XMLUtil.InProgress

Field Summary

protected java.util.Stack	mContent the content constructor stack: the top of the stack is always the object currently being constructed
protected java.util.Hashtable	mCustoms custom handler objects are placed in here
protected java.util.Hashtable	mIDs each content constructor with an id is placed in here

Constructor Summary

XMLUtil()

Method Summary

void	characters(char[] ch, int start, int length)
void	endElement(java.lang.String uri, java.lang.String name, java.lang.String qname)
java.lang.Object	get(java.lang.String id) after parsing a document, use this to retrieve constructor objects by id
Handler	getHandler(java.lang.String s) look up a handler from those registered
java.lang.Object	getResult() after parsing a document, use this to retrieve the top level result
java.util.Hashtable	getResultAsHash() convenience routine to do the cast to Hashtable for you
java.util.Vector	getResultAsVect() convenience routine to do the cast to Hashtable for you
void	ignorableWhitespace(char[] ch, int start, int length)
protected XMLUtil.InProgress	peek()
void	put(java.lang.String id, java.lang.Object o) during parsing, this is called to register objects with a particular id.
void	registerCustomHandler(java.lang.String s, Handler h) adds a custom handler that may then be referenced in the constructed document
void	startElement(java.lang.String uri, java.lang.String name, java.lang.String qname, org.xml.sax.Attributes attributes)

Methods inherited from class org.xml.sax.helpers.DefaultHandler

endDocument, endPrefixMapping, error, fatalError, 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

Field Detail

mIDs

protected java.util.Hashtable mIDs

each content constructor with an id is placed in here

mCustoms

protected java.util.Hashtable mCustoms

custom handler objects are placed in here

mContent

protected java.util.Stack mContent

the content constructor stack: the top of the stack is always the object currently being constructed

Constructor Detail

XMLUtil

public XMLUtil()

Method Detail

registerCustomHandler

public void registerCustomHandler(java.lang.String s,
                                  Handler h)

adds a custom handler that may then be referenced in the constructed document

getHandler

public Handler getHandler(java.lang.String s)

look up a handler from those registered

get

public java.lang.Object get(java.lang.String id)

after parsing a document, use this to retrieve constructor objects by id

put

public void put(java.lang.String id,
                java.lang.Object o)

during parsing, this is called to register objects with a particular id. You can also call it before parsing, in which case the objects can be referenced by a '' during parsing.

getResult

public java.lang.Object getResult()

after parsing a document, use this to retrieve the top level result

getResultAsHash

public java.util.Hashtable getResultAsHash()

convenience routine to do the cast to Hashtable for you

getResultAsVect

public java.util.Vector getResultAsVect()

convenience routine to do the cast to Hashtable for you

peek

protected XMLUtil.InProgress peek()

characters

public void characters(char[] ch,
                       int start,
                       int length)
                throws org.xml.sax.SAXException

Throws:

org.xml.sax.SAXException

ignorableWhitespace

public void ignorableWhitespace(char[] ch,
                                int start,
                                int length)
                         throws org.xml.sax.SAXException

Throws:

org.xml.sax.SAXException

startElement

public void startElement(java.lang.String uri,
                         java.lang.String name,
                         java.lang.String qname,
                         org.xml.sax.Attributes attributes)
                  throws org.xml.sax.SAXException

Throws:

org.xml.sax.SAXException

endElement

public void endElement(java.lang.String uri,
                       java.lang.String name,
                       java.lang.String qname)
                throws org.xml.sax.SAXException

Throws:

org.xml.sax.SAXException