You need to convert an XML document into a Bean.

Use Betwixt's BeanReader to parse an XML document and create an instance of the appropriate bean. Register bean classes with the BeanReader, and parse an XML document loaded from an InputStream, InputSource, or Reader. The following XML document will be parsed into the Play and Character beans introduced in Recipe 6.2:

<play genre="tragedy" year="1603" language="english">
  <author>William Shakespeare</author>
  <character protagonist="false">
    <description>King of Denmark</description>
    <name>Claudius</name>
  </character>
  <character protagonist="true">
    <description>Son to the late, and nephew of the present king</description>
    <name>Hamlet</name>
  </character>
  <character protagonist="false">
    <description>friend to Hamlet</description>
    <name>Horatio</name>
  </character>
  <name>Hamlet</name>
  <summary>Prince of Denmark (Hamlet) freaks out, talks to father's ghost, and
    finally dies in a duel.</summary>
</play>

This XML document was created with BeanWriter, using the customized format from Recipe 6.8. To read this XML document with BeanReader, the Play class will need to be registered with BeanReader and the XMLIntrospector must have the same settings as the XMLIntrospector used when writing the document with BeanWriter. The following code instantiates and configures a BeanReader to read this customized XML for the Play object:

import org.apache.commons.betwixt.io.BeanReader;
InputStream customPlay = 
    getClass( ).getResourceAsStream("./customized-play.xml");
BeanReader beanReader = new BeanReader( );
beanReader.getXMLIntrospector( ).setWrapCollectionsInElement(false);
beanReader.registerBeanClass(Play.class);
Play play = (Play) beanReader.parse( customPlay );

Betwixt uses Commons Digester to parse XML, and the BeanReader object is an extension of the Digester. BeanReader creates a Digester rule set using introspection and the Betwixt mapping files available on the classpath. Digester, as introduced in the first half of this chapter, is a quick way to parse an XML document; all that is required to parse XML with the Digester is a rule set and a little bit of code. Betwixt is built-upon Digester, and the BeanReader further reduces the amount of work required to parse XML to a bean. Instead of completing the process demonstrated in Recipe 6.2, you can simply write a few, very manageable, .betwixt files using BeanReader to read the XML documents and BeanWriter to write the XML documents.

When Betwixt is adding Character objects to the characters List on a Play object, it's calling the addCharacter() method on the Play object. Without this addCharacter( ) object, Betwixt would not be able to populate this List. Betwixt automatically recognizes a plural property name such as characters, characterList, or characterSet, and it attempts to call the corresponding addCharacter( ) method. For more information about the algorithm Betwixt uses to recognize composite properties, see "Using Adder Methods for Composite Properties" in the Betwixt user guide (http://commons.apache.org/betwixt/guide/binding.html).

For more information about reading beans with Betwixt, see "Reading Beans" in the Betwixt user guide (http://commons.apache.org/betwixt/guide/reading.html).