org.newdawn.slick.util.xml
Class ObjectTreeParser

java.lang.Object
  org.newdawn.slick.util.xml.ObjectTreeParser

public class ObjectTreeParser
extends java.lang.Object

Provides a method of parsing XML into an existing data model. This does not provide the same functionality as JAXB or the variety of XML bindings out there. This is a utility to map XML onto an existing data model. The idea being that the design level model should not be driven by the XML schema thats defined. The two arn't always equal and often you end up with a set of class that represent your XML that you then have to traverse to extract into your normal data model. This utility hopes to take a piece of XML and map it onto a previously designed data model. At the moment it's way to tied to the structure of the XML but this will hopefully change with time. XML element names must be mapped to class names. This can be done in two ways either: - Specify an explict mapping with addElementMapping() - Specify the default package name and use the element name as the class name Each attribute in an element is mapped into a property of the element class, preferably through a set bean method, but alternatively by direct injection into private fields. Each child element is added to the target class by call the method add() on it with a single parameter of the type generated for the child element. Classes can optionally implement setXMLElementName(String) and setXMLElementContent(String) to recieve the name and content respectively of the XMLElement they were parsed from. This can help when mapping two elements to a single class. To reiterate, I'm not sure this is a good idea yet. It helps me as a utility since I've done this several times in the past but in the general case it may not be perfect. Consider a custom parser using XMLParser or JAXB (et al) seriously instead.

Author:

kevin

Constructor Summary

ObjectTreeParser()
Create an object tree parser with no default package

ObjectTreeParser(java.lang.String defaultPackage)
Create an object tree parser specifing the default package where classes will be search for using the XML element name

Method Summary

void	addElementMapping(java.lang.String elementName, java.lang.Class elementClass) Add a mapping between XML element name and class name
void	addIgnoredElement(java.lang.String elementName) Add a name to the list of elements ignored
java.lang.Object	parse(java.lang.String ref) Parse the XML document located by the slick resource loader using the reference given.
java.lang.Object	parse(java.lang.String name, java.io.InputStream in) Parse the XML document that can be read from the given input stream
java.lang.Object	parseOnto(java.lang.String name, java.io.InputStream in, java.lang.Object target) Parse the XML document that can be read from the given input stream
java.lang.Object	parseOnto(java.lang.String ref, java.lang.Object target) Parse the XML document located by the slick resource loader using the reference given.
void	setAddMethodName(java.lang.String methodName) Set the name of the method to use to add child objects to their parents.
void	setDefaultPackage(java.lang.String defaultPackage) Set the default package which will be search for classes by their XML element name.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ObjectTreeParser

public ObjectTreeParser()

Create an object tree parser with no default package

ObjectTreeParser

public ObjectTreeParser(java.lang.String defaultPackage)

Create an object tree parser specifing the default package where classes will be search for using the XML element name

Parameters:

defaultPackage - The default package to be searched

Method Detail

addElementMapping

public void addElementMapping(java.lang.String elementName,
                              java.lang.Class elementClass)

Add a mapping between XML element name and class name

Parameters:

elementName - The name of the XML element

elementClass - The class to be created for the given element

addIgnoredElement

public void addIgnoredElement(java.lang.String elementName)

Add a name to the list of elements ignored

Parameters:

elementName - The name to ignore

setAddMethodName

public void setAddMethodName(java.lang.String methodName)

Set the name of the method to use to add child objects to their parents. This is sometimes useful to not clash with the existing data model methods.

Parameters:

methodName - The name of the method to call

setDefaultPackage

public void setDefaultPackage(java.lang.String defaultPackage)

Set the default package which will be search for classes by their XML element name.

Parameters:

defaultPackage - The default package to be searched

parse

public java.lang.Object parse(java.lang.String ref)
                       throws SlickXMLException

Parse the XML document located by the slick resource loader using the reference given.

Parameters:

ref - The reference to the XML document

Returns:

The root element of the newly parse document

Throws:

SlickXMLException - Indicates a failure to parse the XML, most likely the XML is malformed in some way.

parse

public java.lang.Object parse(java.lang.String name,
                              java.io.InputStream in)
                       throws SlickXMLException

Parse the XML document that can be read from the given input stream

Parameters:

name - The name of the document

in - The input stream from which the document can be read

Returns:

The root element of the newly parse document

Throws:

SlickXMLException - Indicates a failure to parse the XML, most likely the XML is malformed in some way.

parseOnto

public java.lang.Object parseOnto(java.lang.String ref,
                                  java.lang.Object target)
                           throws SlickXMLException

Parse the XML document located by the slick resource loader using the reference given.

Parameters:

ref - The reference to the XML document

target - The top level object that represents the root node

Returns:

The root element of the newly parse document

Throws:

SlickXMLException - Indicates a failure to parse the XML, most likely the XML is malformed in some way.

parseOnto

public java.lang.Object parseOnto(java.lang.String name,
                                  java.io.InputStream in,
                                  java.lang.Object target)
                           throws SlickXMLException

Parse the XML document that can be read from the given input stream

Parameters:

name - The name of the document

in - The input stream from which the document can be read

target - The top level object that represents the root node

Returns:

The root element of the newly parse document

Throws:

SlickXMLException - Indicates a failure to parse the XML, most likely the XML is malformed in some way.