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.

Why Can I Make Betwixt Faster?

Betwixt is a dynamic binder. This means that it uses reflection. One of the biggest costs is introspection by reflection of the beans. Betwixt caches the results of reflection in a XMLBeanInfoRegistry implementation. One simple way to improve performance is to share a single, threadsafe implementation (DefaultXMLBeanInfoRegistry, for example) between all readers and writers.

Writing Beans

In what forms can Betwixt output the xml?

Betwixt can output xml as streaming text or as SAX events.

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), when a cycle reference is encountered in the bean graph, a CyclicReferenceException will be thrown.

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. With care and knowledge of the way that Betwixt reads beans, extra rules can be used to add custom functionality.

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".

Does Betwixt Validate Values Read?

Betwixt does not directly validate any property values read. The convertion of the string in the xml to values suitable for setting on the bean property is delegated to the ObjectStringConverter. The converter may - or may not - validate values (and throw exceptions when they fall outside acceptable ranges).

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.