JDOM2 Feature Outputter Updates
Clone this wiki locally
The internals of XMLOutputter have been completely reworked. The public API itself is unchanged, but the implementation has been modified to meet the following goals:
- Consistency of output - changing the way that Namespaces are output was hard to do without some changes.
- Consistency of subclass-interface - people wanting to subclass the XMLOutputter had a real challenge finding the right hooks.
- Complexity of implementation - managing the Namespaces and Format changes was a problem for performance and for complexity.
This change has a significant impact on people who sub-class the XMLOutputter, but the benefit on the subclassing-API is significant.
An Interface is used to describe what types of data needs to be output, and a fully functional Abstract class implementing that interface is provided. The Abstract class is compatible with JDOM 1.x output formats. For those times where using the Format class is insufficient for customizing the XMLOutput, you can choose to either implement the base interface, or using a Decorator pattern, you can subclass the Abstract class.
This same mechanism has been used for implementing the new StAX Outputters.
This process allows the default system to implement high-performance and reusable classes for output, while at the same time making it easier to subclass and customize the output if you need to.
To support the Outputters the NamespaceStack and FormatStack are available. These classes are efficient ways of maintaining Namespace scopes and output state respectively.
Further, the 'back-end' code was analysed, and a large amount of code redundancy was identified. In essence, there are 5 outputters, XML (text), SAX, DOM, StAX Event, and StAX Stream. Each of these 5 implementations have two code functions: format the output; and interface with the output target.
The 'format the output' code was common to all 5 output types, and it is complicated code because there are essentially four tpes of formats: Raw, Pretty, Compact, and 'Trim-Full-White'. The output formating code has now been 'isolated' in to the 'Walker' interface (and it's specific implementations): http://hunterhacker.github.com/jdom/jdom2/apidocs/org/jdom2/output/support/Walker.html
It is now possible to create a new formatter, and apply the same formatter (Walker) to any of the 5 output targets. Additionally, it is possible to create a new type of output target without having to worry about the actual formatting of the XML.