Outputting Results (Of Bean Writing)

Betwixt is flexible when it comes to outputting the results of bean writing. The abstract 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.

Pushing Results to a Textual Stream

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, close() and flush methods have been provided in BeanWriter which will close or flush (respectively) the underlying stream or reader.

Rendering Empty Tags

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 BeanWriterendTagForEmptyElement 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);

Content Encoding

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:

  • Escaping the character data
  • Wrapping the entire section as CDATA

Betwixt provides a plug-in MixedCharacterEncodingStrategy and a property on BeanWriter which allows the processing to be varied. Factory constants are provided on MixedCharacterEncodingStrategy for the two common use cases above.

For example, to have all content wrapped in CDATA sections: 

        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 . Setting the org.apache.commons.betwixt.mixed-content-encoding option to 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>

Pushing Results to SAX

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 .