On 16 April 2013 10:56, Jörg Schaible <[email protected]> wrote:
> Hi Stuart, > > Stuart Rossiter wrote: > > > On 8 April 2013 22:13, Jörg Schaible > > <[email protected]> wrote: > > > >> Stuart Rossiter wrote: > >> > >> > On 6 April 2013 21:21, Jörg Schaible > >> > <[email protected]> wrote: > >> > > >> >> Hi Stuart, > >> >> > >> >> Stuart Rossiter wrote: > >> >> > >> >> > Hi. With the latest XStream 1.4.4 (on Windows with Java 6), using > >> >> > the > >> >> StAX > >> >> > driver instead of the XPP3 or JAXP DOM one means that toXML > includes > >> >> > the XML declaration (<?xml version="1.0"?>) *and* doesn't > >> >> > pretty-print the string. The other drivers work fine. > >> >> > > >> >> > This looks like a consistency bug, given that the declaration > should > >> >> never > >> >> > be written, and it should always be pretty-printed. However, the > >> >> > JIRA log-in link doesn't allow me to request a userid as the > XStream > >> >> > pages suggest. (It says 'contact your JIRA admin'.) > >> >> > > >> >> > So: > >> >> > (a) Is this a bug? (Browsing JIRA suggests none registered.) > >> >> > >> >> No. Actually we normally have only XML parsers, but StAX is the one > of > >> >> the view XML frameworks that also includes a writer. And XStream is > >> using > >> >> the defaults of the framework. Note, that the default for all the > >> >> other parsers (PrettyPrintWriter of XStream) does not support > >> >> namespaces. > >> >> > >> >> > >> > That makes sense, but surely XStream should present a consistent API > >> > that isn't dependent on the driver used? > >> > > >> > The XStream toXML method Javadoc states that it "Serialize[s] an > object > >> to > >> > a pretty-printed XML String". > >> > > >> > The FAQ states: > >> > Q. Why does XStream not write an XML declaration? > >> > A. XStream is designed to write XML snippets, so you can embed its > >> > output into an existing stream or string. You can write the XML > >> > declaration yourself into the Writer before using it to call > >> > XStream.toXML(writer). > >> > > >> > So, if the wrapped driver doesn't do this by default, shouldn't > XStream > >> be > >> > doing it (either by configuring the driver internally or parsing its > >> > outputs)? Particularly since XStream has no functionality to > >> pretty-print > >> > or remove the header 'manually'. (I appreciate that there are probably > >> > XML-related libraries that can do this for me, but still...) > >> > > >> > Am I missing something here? > >> > >> That's the point: XStream does *not* write the XML header. However, in > >> case of StAX it is written by javax.xml.stream.XMLStreamWriter. XStream > >> is limited to its capabilities. Iy you have no need for namespaces, you > >> can use > >> XStream's PrettyPrintWriter instead. > >> > >> > >> > > I'm really sorry to drag this out (and possibly offend you) but, unless > > I'm missing something *massive*, I really don't understand your response. > > It is irrelevant whether it is XStream or dependency code *actually* > > writing the XML header and/or doing the pretty-printing. XStream is > > providing an abstracted interface for XML serialisation of objects. The > > interface contract states that toXML pretty-prints XML and doesn't > include > > an XML header. > > > > So either: > > (a) The Javadoc and FAQ entry need changing to make clear that the > > header-writing and pretty-printing are governed by the driver chosen. > > (Really the Javadoc should mention the header-writing, not leaving that > > detail to the FAQ.) > > > > (b) XStream should honour this contract by whatever means necessary > (e.g., > > if the STaX driver is being used, use STaX to generate the XML and then > > strip off the header and pretty-print it before returning). > > > > I'm just really confused since this is a standard > principles-of-API-design > > thing isn't it (with (b) being the 'normal' option in such > > circumstances)?? > > Well, I have to confess that I'd been bitten by the behavior myself ;-) > > The biggest issue here is backward compatibility, because anyone who used > the StaxDriver in the last years expect it to behave in this way. > Nevertheless, the behavior could probably adjusted for a major release > using > something like StaxMate that provides pretty print functionality (AFAICS). > > > Thanks for the update Jorg, and looks like we agree on the issue now. Understand what you're saying about changing in a major release. However, I would think that at least the Javadoc should be updated. Ideally, to provide helper functionality without breaking backwards compatibility, you could do something *like* one of the below: (a) add a ContractConsistentStaxDriver which wraps Stax driver and enforces the 'toXML contract' (b) add a standardiseStaxOutput(String rawXML) helper method to XStream which strips the header and pretty-prints it (c) add an overloaded StaxDriver constructor with an standardiseXML boolean flag that does the standardisation in (a), where the default constructor sets this as false I need to raise a (definite!) bug for something completely different. Would you like me to add a bug and/or enhancement request(s) for this? I was thinking of: (1) A Javadoc and FAQ correction bug (2) An enhancement request for the helper functionality (3) A major-release enhancement request for consistent toXML functionality (which would supercede the changes in (2)) Am I overdoing it? :-) Stuart
