com.acsinet_solutions.util.xml
Class XMLObjectFactory

java.lang.Object
  org.xml.sax.helpers.DefaultHandler
      com.acsinet_solutions.util.xml.XMLObjectFactory

All Implemented Interfaces:

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

public final class XMLObjectFactory
extends org.xml.sax.helpers.DefaultHandler

An XML-based Object Factory implementation. Feeds a BlockBuilder instance, and provides an easy way to create hierarchies of objects from an XML file ( there are many approaches that perform this type of task, but this implementation is really simple and convenient for a lot of cases ).

Hierarchies in an XML document are mapped to a Hierarchy of objects. The root object instance ( or class ) is passed to this factory as a parameter in the constructer. Starting from there, reflection and property names are used in the following way:

All attributes of a tag are mapped to standard properties in a bean class. The BlockBuilder.setValue() method is used for this mapping.

All sub elements ( and sub-subelements... ) are mapped to nested objects. A non-standard addElement( Object instance ) method on th current bean is called for these cases. The name of the method is matched to the XML element name, for example <book> element matches addBook( ... ) method. The addBook() method receives an instance which is the type of a new object that will be created and used within the builder for new attributes or subelements to be created there. The type of this object being created may be overriden using the "class" attribute at any level of the XML structure.

Check the source code of BlockBuilderTest for a working example of this.

WARNING! This class is not-thread safe and should be used only once

Author:

Santiago Arriaga - santiago.arriaga@acsinet-solutions.com

See Also:

BlockBuilder, BlockBuilderTest

Field Summary

static java.lang.String

_TEXT Text attribute

Constructor Summary

XMLObjectFactory()
Empty constructor

XMLObjectFactory(Builder builder)
Creata an object builder with an user-provided builder instance

XMLObjectFactory(java.lang.Class defaultRootClass)

XMLObjectFactory(java.lang.Object rootObject)

Method Summary

void	characters(char[] ch, int start, int length) If not empty, they are reported to the builder as an special "_text" attribute ( mapped to a set_text() method ).
void	endElement(java.lang.String uri, java.lang.String local, java.lang.String raw) Closes the current element level, and returns the current object context to the parent object.
java.lang.Object	getObject(org.xml.sax.InputSource source)
java.lang.Object	getObject(java.io.Reader reader)
java.lang.Object	getObject(java.lang.String file)
void	startElement(java.lang.String uri, java.lang.String local, java.lang.String raw, org.xml.sax.Attributes attrs) If an element is found in the input XML document, a new level is added to the object structure; the instance of the new object is determined by reflection using the datatype of the argument of the addXXX() method in the current object, or the "class" attribute of the currently found element is used as the FQCN of the object being created.

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

Field Detail

_TEXT

public static final java.lang.String _TEXT

Text attribute

See Also:

Constant Field Values

Constructor Detail

XMLObjectFactory

public XMLObjectFactory(Builder builder)

Creata an object builder with an user-provided builder instance

XMLObjectFactory

public XMLObjectFactory(java.lang.Object rootObject)

Parameters:

defaultRootClass - A maybe-null instance value

XMLObjectFactory

public XMLObjectFactory(java.lang.Class defaultRootClass)

Parameters:

defaultRootClass - A maybe-null Class value

XMLObjectFactory

public XMLObjectFactory()

Empty constructor

Method Detail

getObject

public final java.lang.Object getObject(java.lang.String file)
                                 throws java.io.IOException,
                                        BuildException

Parameters:

file - A not-null not-empty valid-file String instance

Returns:

A not-null Object instance

Throws:

com.acsinet_solutions.cetia4.build.BuildException - Thrown if the class instance could not be obtained

java.io.IOException

BuildException

getObject

public final java.lang.Object getObject(java.io.Reader reader)
                                 throws java.io.IOException,
                                        BuildException

Parameters:

reader - A not-null Reader instance

Returns:

A not-null Object instance

Throws:

com.acsinet_solutions.cetia4.build.BuildException - Thrown if the class instance could not be obtained

java.io.IOException

BuildException

getObject

public final java.lang.Object getObject(org.xml.sax.InputSource source)
                                 throws java.io.IOException,
                                        BuildException

Parameters:

inputSource - A not-null InputSource instance

Returns:

A not-null Object instance

Throws:

com.acsinet_solutions.cetia4.build.BuildException - Thrown if the class instance could not be obtained

java.io.IOException

BuildException

startElement

public final void startElement(java.lang.String uri,
                               java.lang.String local,
                               java.lang.String raw,
                               org.xml.sax.Attributes attrs)
                        throws org.xml.sax.SAXException

If an element is found in the input XML document, a new level is added to the object structure; the instance of the new object is determined by reflection using the datatype of the argument of the addXXX() method in the current object, or the "class" attribute of the currently found element is used as the FQCN of the object being created. Any attributes of the current element are mapped to standard properties of the newly created object.

Any name in the XML file that contains '-' characters is changed to a name in which '-' characters are replaced with '_' to work according to java naming restrictions.

Specified by:

startElement in interface org.xml.sax.ContentHandler

Overrides:

startElement in class org.xml.sax.helpers.DefaultHandler

Throws:

org.xml.sax.SAXException

See Also:

BlockBuilder.enterObject(String,String), BlockBuilder.setValue(String,Object)

characters

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

If not empty, they are reported to the builder as an special "_text" attribute ( mapped to a set_text() method ).

Specified by:

characters in interface org.xml.sax.ContentHandler

Overrides:

characters in class org.xml.sax.helpers.DefaultHandler

Throws:

org.xml.sax.SAXException

See Also:

BlockBuilder.setValue(String,Object)

endElement

public final void endElement(java.lang.String uri,
                             java.lang.String local,
                             java.lang.String raw)
                      throws org.xml.sax.SAXException

Closes the current element level, and returns the current object context to the parent object.

Specified by:

endElement in interface org.xml.sax.ContentHandler

Overrides:

endElement in class org.xml.sax.helpers.DefaultHandler

Throws:

org.xml.sax.SAXException

See Also:

BlockBuilder.exitObject()