ShiftOne Arbor

What is Arbor?

Arbor is a library for easily reading XML into user defined Java beans.

How is it different from DOM?

It can be used to build an object tree, much like DOM. With DOM however the nodes of the object model are instances of generic classes such as Node, Element, Text, etc. Arbor builds an object tree from user defined classes. This provides type safety and gives the developer a place to implement custom validation logic.

The resulting structure ends up being easier to work with, and may also be relevant outside of XML processing.

How does it work?

What conventions do my beans need to follow?

When an attribute is encountered in the XML source, the current bean's set accessor method is called with the value of the attribute as a parameter. The accessor method is selected based on the name of the attribute. Type conversion is done based on the parameter type of the selected accessor method.

When an child element is encountered in the XML source, a create method is called on the current bean. The create method is selected based on the name of the attribute. (an element named <billingAddress/> will cause the method createBillingAddress to be called) The object that is returned by the create method, becomes the new current element.

There is one exception to the above two rules. If an element is encountered and there is no matching create method, then Arbor will attempt to treat the body text of the element as an attribute of the current bean. The following two sections of XML will produce the same structure, as long as there is no createBar method on the bean that represents foo.

        <foo bar="shiftOne"/>

        <foo>
           <bar>shiftOne</bar>
        </foo>

Though required by the JavaBeans spec, Arbor does not need a no argument constructor. Creation of beans is always delegated to the create methods.

What if I don't like the method naming conventions?

Typically, when Arbor encounters an elements, such as myElement or my-element it tries to make a method call createMyElement on the current bean. If the conversion that is defined by default does not meet your requirement, then you can plug your own NameMapper implementaion into Arbor.

What's the down side?

Well, it depends on your application. For some usages, Arbor would not be the right choice. This is because Arbor performs it's actons based on the contence of the source XML document, not what the application needs. Arbor takes all the data in a document and feeds it into a set of beans. This is opposite of other approaches in which a programmer writes code to extract needed information from XML. Arbor can save a lot of tedious and error-prone development, but it makes your program unable to process documents with unexpected elements or attributes.

For good or bad, there is a level of validation built into Arbor.

How do I find out about Text nodes?

Arbor by default discards text nodes. If your bean implementation needs the text contained within it's XML element, then the interface TextSupport must be implemented. This interface defines the single method addText(String text).

How can I tell when Arbor is done processing a bean?

Arbor processes elements in the order they occur in the document. If a bean needs to know when the processing of it and it's children has completed, then it may implement the LifecycleListener interface. This interface defines the single method finished().

How do I feed XML to Arbor?

Arbor will process an InputStream or an existing DOM. InputStreams are processed using SAX.

How about an example?