XOM API for Processing XML with Java

[Elliotte Rusty Harold <elharo AT ibiblio.org>]

On Fri, Sep 17, 2010 at 7:11 AM, Dmitry Katsubo <dma_k AT mail.ru> wrote:

> I fully agree on the statement that parsing the XSLT into XOM tree is
> fast and should not be considered as memory or time loss at all. However
> we can imagine, that I cannot receive the stylesheet neither as
> InputStream, File or String. It is passed to me from some other 3rd
> party library X as javax.xml.stream.XMLEventReader or as
> org.xmlpull.v1.XmlPullParser.

Supporting hypothetical use cases lead to bloated APIs. If there's a
complelling need for XMLEventReader or XmlPullParser I'll look into
it. So far I've never seen such a thing. Even you are not really
saying you need it, just that you think it should be there.

> I read you message here as "(a) TrAX API is bad, that is why we (b)
> should not support it and (c) suppress any attempts to add support for
> it in XOM". I might agree with (a) and (b), but doing (c) frustrates me.

No, the message is that the TrAX API is so bad that XOM CANNOT support
it. It is simply not possible even if I wanted to do this. TrAX does
not provide a usable abstraction of sources and results. If the TrAX
API actually allowed interoperability between representations I would
have supported it years ago. It doesn't.

> I personally think that "good API" also is "extendable API" (taken from
> page 4 in Google presentation [3]), so if somebody inherits its class
> from XSLTransform what is wrong with that? I agree that one can misuse
> the parent XSLTransform class, break things and do a lot of harm, but if
> I am to choose between "let people extend and re-use the classes and
> *probably* make mistakes (and learn from them)" and "do not allow people
> extend and re-use the classes (and get a headache)", I would choose the
> first one. I have stressed the word *probably* because one needs to be a
> real Java hacker to invent something to break XSLTransform class
> functionality (maybe via reflection? byte-code injection?
> java.lang.instrument.ClassFileTransformer?).

Extensible is hard. One of the hard parts is making something
extensible without making it fragile. XOM goes to a lot of trouble in
this area.

> There is nu.xom.DocumentFragment class, but it is (again) private. I try
> to imagine what are the probable ways to use the result of
> transformation. I think, in most cases applications serialize the result
> of transformation into String/OutputStream/Writer (and send pipe it to
> another module or application or DB). So I would expect to simply say:
>
> String xml = transform.transform(input).toXML();
> ... and send String to next consumer in a pipe ...

I've though about adding a toXML method to Nodes. That might be useful.

> So my points here:
>
> 1) If I use XSLTransform.toDocument(transform.transform(input)).toXML()
> I get additionally post-transformed tree with first Element in root and
> all other nodes as it's child.
> This post-transformation is not evident
> and not natural but maybe OK for most transformations.

I beg to differ. No way is XOM going to move nodes around into other
nodes behind the user's back. If the user wants that (and I can't see
why they would) they'll have to write code to do it.)

> I would like to
> keep the original document as is after the transformation.

That's as it is now.


> 2) So I need to write a loop over all nodes and serialize them. Not a
> big deal in general, but if API use case for almost all case is to loop
> over all nodes, isn't it a signal to improve it? nu.xom.Serializer also
> cannot write Nodes...

Java is not a list-based language. The use of loops is deliberate in
the design of both Java and XOM.

> 3) If transform() method returns DocumentFragment, I expect
> DocumentFragment.toXML() not to break down in
> UnsupportedOperationException, but correctly serialize all nodes in a
> loop. Yes, in this case toXML() returns a non-complete (non-valid) XML,
> but toXML() is not supposed to produce a valid XML, right? (e.g.
> Text.toXML()). So the caller knows, what can be in output.

This is why DocumentFragment is not public. :-)

> Also as we have touched the question of serialization, why
> nu.xom.Serializer does not have a constructor with Writer? Internally it
> uses a writer. The only added value I see in nu.xom.Serializer is to
> protect the user from using broken EBCDIC-family output streams. If I
> use broken JDK OutputStream implementation, I won't blame XOM, really.
> And if I have only a Writer, I need to think how to convert it to
> OutputStream for XOM, who will convert it to Writer :)

This is painful but ties directly to another design flaw in Java, not
XOM. Writers do not allow the client to determine the underlying
encoding of the text (UTF-8, ISO-8859-1, etc.). Therefore with only a
Writer I can't guarantee well-formed output. To answer your question
in another thread this is one (of several) ways you can get malformed
output from JDOM.

> XOM provides a nice nu.xom.EBCDICWriter but again, it is not public.
> This forces programmers to copy-paste the code, not not to re-use. Why
> preventing it from being used even outside XOM?

God sense. No one needs to, or should be, writing EBCDIC XML files in 2010.

-- 
Elliotte Rusty Harold
elharo AT ibiblio.org