Betwixt is flexible when it comes to outputting the results of bean writing.
AbstractBeanWriter class provides a basic framework
with an implementation API inspired by SAX
Betwixt ships with writers that support SAX and textual streams
but others can be created with relative ease.
BeanWriter pushes results to a textual stream. This can be used
to efficiently push content through a socket or just to create a simple String.
Note that only document fragments are created so you may need to append any prologs before writing the bean.
Note: also that Betwixt leaves management of the streams and readers to the
user (respecting the maxim that the opener should close). When a fragment has been written, Betwixt will
not close the stream automatically. However, for convenience,
methods have been provided in
BeanWriter which will close or flush (respectively) the underlying
stream or reader.
Empty tags (ones containing no body content and no child nodes) can be rendered
in two ways: as a single closed tag (for example
<element/>) or as a
pair of tags (
<element></element>). By default, Betwixt
renders empty tags as a single close tag but setting the
endTagForEmptyElement to true will ensures that all empty elements are
rendered as a pair of tags. For example:
BeanWriter writer = new BeanWriter(out); writer.setEndTagForEmptyElement(true);
When writing character data (the content between markup tags) to a textual stream, sections of character data can be processed in various ways by Betwixt with the aim of easily producing valid xml from beans. In particular, Betwixt assumes that bean's property values are plain java rather than pre-processed xml and so may contain characters that should be escaped.
There are two primary use cases for this processing:
Betwixt provides a plug-in
and a property on
which allows the processing to be varied.
Factory constants are provided on
for the two common use cases above.
For example, to have all content wrapped in
BeanWriter writer = ... writer.setMixedContentEncodingStrategy(MixedContentEncodingStrategy.CDATA);
By default, Betwixt uses character escaping only. However, the default
strategy also supports per-property specification through
setting the appropriate option
CDATA will instruct the default strategy to wrap
the element's body text in a CDATA section.
For example, the following betwixt file fragment encodes the
some-property element's body text as CDATA
(when the default strategy is used):
<?xml version='1.0'?> <info primitiveTypes="attribute"> <element name='some-bean'> ... <element name='some-property' property='someProperty'> <option> <name>org.apache.commons.betwixt.mixed-content-encoding</name> <value>CDATA</value> </option> </element> ... </element> </info>
SAXBeanWriter pushes events to a SAX content handler.
This allows Betwixt to efficiently participate as a content generator
in SAX-based pipelines such as cocoon