Bean Naming ConventionsThe Java Beans specification contains various naming conventions that should be used when writing beans that will allow the beans introspector to automatically guess the properties in a bean and their getters, their setter methods etc. Betwixt will use these same naming conventions to deduce how to make the beans appear as XML. There are some other naming conventions that you can use to make your beans easier to output as XML or parse.
One common requirement when mapping beans to xml is that the property and type names from the bean
must be processed (in some way) before they are used in the xml. For example, a property
called
Betwixt supports customization of these mappings through plug-in implementations of the
Note that the attribute and element names given in a .betwixt file (as usual)
override the name mapping settings on the Using A Custom Type Name To Element Name Mapping
Betwixt supports pluggable conversion of type names to element names. Setting the
Using A Custom Property Name To Attribute Name Mapping
Betwixt supports pluggable conversion of type names to attribute names. Setting the
Custom Mapping ExampleHere's a simple bean which will be mapped to xml: public class TallTreeBean { private float heightOfTree; public TallTreeBean(float height) { setHeightOfTree(height); } public float getHeightOfTree() { return heightOfTree; } public void setHeightOfTree(float heightOfTree) { this.heightOfTree = heightOfTree; } } Next is an application that writes that bean to xml. Custom name mappers for elements and attributes are set. import org.apache.commons.betwixt.io.BeanWriter; import org.apache.commons.betwixt.strategy.DecapitalizeNameMapper; import org.apache.commons.betwixt.strategy.HyphenatedNameMapper; public class NameMapperExampleApp { public static final void main(String args[]) throws Exception{ // create write and set basic properties BeanWriter writer = new BeanWriter(); writer.getXMLIntrospector().setAttributesForPrimitives(true); writer.enablePrettyPrint(); writer.setWriteIDs(false); // set a custom name mapper for attributes writer.getXMLIntrospector().setAttributeNameMapper(new HyphenatedNameMapper()); // set a custom name mapper for elements writer.getXMLIntrospector().setElementNameMapper(new DecapitalizeNameMapper()); // write out the bean writer.write(new TallTreeBean(15.1f)); System.out.println(""); } } The application should print out (to System.out) an xml fragment which looks like: <tallTreeBean height-of-tree="15.1"/> As you can see, the first letter of the element name has been decapitalized and the capitals in the property separated by hyphens after being converted to lower case. Using Adder Methods For Composite PropertiesThis naming convention is used to indicate the singular type of some composite property. To use: create an add method to match the getter method for 'composite properties'. public class SomeBean { public <CollectionType> getFoo*(); public void addFoo(<SingularType> foo); } Where CollectionType can be an array, a Collection, Enumeration, Iterator, Map. The [SinglularType] refers to the type of an item in the collection. The name of the getter property starts with 'Foo'. So 'Foo' is the singular name, the plural collection name could be Foos, FooArray, FooList, FooIterator or some other encoding, though the plural name should start with the singular name for auto-detection to work properly. Using A Custom Plural Stemmer
Betwixt allows this auto-detection of plurals from singulars to be customized.
Implementations of
One important usage of custom plural stemmers is to support classes with non-english method names.
A custom
The default implementation supports common english plural patterns and then falls back to finding
any property that starts with the singular name. For example, it will match a plural property called
Reading And Writing Map Properties
Maps are a special kind of composite property. Each entry in a map has a key and a value.
Betwixt handles maps by adding extra elements which wrap each entry. Each entry is wrapped in
a The structure is something like: ... <entry> <key>...</key> <value>...</value> <entry> <entry> <key>...</key> <value>...</value> <entry> ...
Reading map properties is an extension of the ways that Betwixt handles collections. Rather than
searching for an Customized Mapping (Advanced)Caching and the XMLRegistry
Introspection is slow and so caching the results improves preformance. Though the writers
and readers can - by nature - only be used safely in a single thread, a single
The
Before using the standard introspection techniques to create a new The default strategy caches everything and supports flushes. Betwixt contains an alternative implementation that does not cache anything. Users that require more sophisticated caching strategies should create custom implementations.
The Other XMLIntrospector SettingsHere are discussed the important settings that haven't been covered already.
The <PersonBean> <age>21</age> ... isAttributesForPrimitives is false but to
<PersonBean age='21'> ...
The Using .betwixt files To Read And Write Mixed Content
An element with mixed content contains child elements and text.
For example, element <foo> Some text <bar/> </foo> text elements in the
.betwixt file.
A For example, a simple bean with the .betwixt file <?xml version="1.0" encoding="UTF-8" ?> <info primitiveTypes="attribute"> <element name='foo'> <attribute name='version' value='1.0'/> <element name='bar'> <attribute name='version' property='alpha'/> <text value='static text'/> <element name='baa' property='beta'/> <text property='gamma'/> </element> </element> </info> <foo version="1.0"> <bar version="One">static text<baa>Two</baa>Three</bar> </foo> Betwixt supports reading back mixed content in one special situation which happily is also a common use case. Betwixt will call a single property with all the mixed content text. So, only one mixed content property is specified then the bean can be written and then read back. Introspection And Normalization
When an Object is introspected by the
Betwixt provides the
Betwixt supplies a second implementation called
For example, take a class
Converting Objects And Primitives To Strings (And Back Again)Using ConvertUtils To Customize Conversion Of Primitives
Converting Dates (And Other Objects)There are numerous situations when read beans from xml or writing beans to xml that String to Object or Object to String conversions are required. Betwixt uses a Strategy class to allow a convenient default which will work well for most basic users whilst allowing advanced users to fully hook in and customize this process.
The default strategy uses
There is one exception to this rule. If the class is a
Advanced users will probably need a particular date format. The recommended way to do this is through
registering appropriate converters with ConvertUtils. The default conversion strategy must also be
replaced with an instance of
ConvertUtilsObjectStringConverter
. This is set though a
For example, to delegate to Custom ObjectStringConverters (Advanced)
The strategy class
ObjectStringConverter
is simple: containing only two simple methods. For more information about creating subclasses, see the javadocs.
The implementation to be used is set through the
For example, to set a custom
Betwixt is distributed with a range of (Brief) Guide To Creating Custom Strategy PluginsIt is common for users of Betwixt to need to develop their own custom strategies to handle some parts of the binding process. This section contains some information that may of of some use for those people. Help to create a more comprehensive guide would be appreciated. Using Options
Options provide an extensible way for extra mapping information to be communicated
from the binding to those components executing the mapping. Each
Setting option values through the <?xml version='1.0'?> <info primitiveTypes="attribute"> <element name='some-bean'> <element name='some-property' property='someProperty'> <option> <name>org.apache.commons.betwixt.example-one</name> <value>value-one</value> </option> </element> <element name='another-property' property='anotherProperty'> <option> <name>org.apache.commons.betwixt.example-two</name> <value>value-two</value> </option> </element> </element> </info>
will have the value value-one associated with the option name
org.apache.commons.betwixt.example-one in the options for the
The recommended convention for naming option's is to prefix with the reverse domain
name (the same convension that is used for the standard naming of packages).
In any case, all option names beginning with At the moment, there is no support for inheritance of options (from parent to child) through this may be considered later if there is sufficient demand. |