# ObjectTreeParser (Slick - The 2D Library)
Date: 2013-06-03

## 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<AttrName> 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.

Copyright © 2006 New Dawn Software. All Rights Reserved.