General

What is Betwixt?

The Betwixt library provides an XML introspection mechanism for mapping beans to XML in a flexible way. Please see the Home page and Guide documents for more detail.

Why is this called Betwixt?

I grepped a dictionary for words containing B*T*X for Bean To XML. There's not many words around containing those 3 letters in order. Betwixt also seems a fitting name as its the stuff between (betwixt) Beans and XML.

How does Betwixt compare to technologies like JAXB and Castor?

Where JAXP and Castor are strong is when you have a well agreed schema (XML Schema for Castor or a DTD in the case of JAXB, last time I looked) and want to auto-generate beans for parsing and processing the XML.

Betwixt is strong is when you've already got the beans and just want a nice looking XML format to serialize/deserialize your beans. Indeed with Betwixt you can just write your beans and not even worry about XML schemas and providing you follow a simple bean naming convention (the use of getter, setter and adder methods) you'll get nice looking XML for free.

In JDK1.4 there is a long term bean serialization mechanism which you can use. However Betwixt generates cleaner looking XML which can be customized to your own look and feel. Long term bean serialization doesn't generate nice looking XML.

Writing Beans

In what forms can Betwixt output the xml?

At the moment, BeanWriter is the only way to output the xml. This writes the xml (as characters) to standard java io streams. Work will begin on a SAX-based writer (which will generate SAX events) very soon.

Can BeanWriter produce xml that's easy (for a human ;) to read?

Yes! Call

beanWriter.enablePrettyPrint();

(For those who are extra picky, how this is done can also be adjusted. See java docs for details.)

How does Betwixt cope with beans which have cyclic reference graphs?

The default behaviour is to use the ID-IDREF mechanism (described in the xml specification). Betwixt will automatically assign ID values to beans as it write out the graph. If it comes to a bean that it's written before, it will write an IDREF value matching the original.

How can I stop Betwixt generating ID attribute values for my beans?

This is controlled by a property on BeanWriter. Call

beanWriter.setWriteIDs(false);

and then Betwixt will no longer automatically add ID attributes. Once this property is set (to false), BeanWroter will throw a CyclicReferenceException when any cyclic references which are encountered in the bean graph.

How can I stop Betwixt writing out empty elements?

An empty element (for this discussion) is one which has no attributes and no child elements which are not empty. If you want to stop Betwixt writing out empty elements, then call:

beanWriter.setWriteEmptyElements(false);

(before writing your bean).

How can I stop Betwixt escaping my character data?

Betwixt processes the character data so that valid xml is created. The detault is to escape all character data but this can be changed by plugging in a new mixed context encoding strategy .

Reading Beans

How can I make my extra digestion Rules work with Betwixt?

Betwixt uses Digester for bean reading. There are problems integrating the last release with custom digester rules. The CVS HEAD version of betwixt now supports this and so users who need to do this should upgrade.

Why does reading my xml return null?

Here are some common reasons why this may happen:

• The class lacks a no-argument construct. Betwixt only supports creation of beans with no-argument constructors. This may be fixed in a future release. (Patches for this gratefully received!)
• The class need to be registered at a custom path. You may need to use registerBeanRegister(String path, Class beanClass) to register the class at a particular path.

How can I make Betwixt match adders to collective properties when using a .betwixt file without also adding default propertes?

Add the <addDefaults> and to it add an attribute add-properties="false".

Building Betwixt

How do I build Betwixt?

Betwixt uses Maven for its build system. So you should be able to build Betwixt just like any other Maven enabled project. Please see the Maven documentation for details.