[jdom-interest] XSLT API is too complex

[Elliotte Rusty Harold]

During Jason's talk on JDOM at SD2002West last Friday, I noticed that 
the XSLT API is way too complex. It requires the user to be familiar 
with TrAX and use multiple annoying factory classes instead of the 
obvious constructors that are the hallmark of JDOM. Right now the sample 
app for XSLT transforms in JDOM looks like this:

  public static Document transform(Document in, String stylesheet)
                              throws JDOMException {
    try {
      Transformer transformer = TransformerFactory.newInstance()
        .newTransformer(new StreamSource(stylesheet));
 
      JDOMResult out = new JDOMResult();
      transformer.transform(new JDOMSource(in), out);
      return out.getDocument();
    }
    catch (TransformerException e) {
      throw new JDOMException("XSLT Transformation failed", e);
    }
  }

I think we should be able to make it look like this instead:

  public static Document transform(Document in, String stylesheet)
    throws XSLException {
      XSLTransform xform = new XSLTransform(stylesheet);
      return xform.transform(in);
  }


The TrAX API is complex because it needs to support many different 
models and factories.
We only need to support JDOM, and can mostly accept the default
transformer engine. (We can use the same system properties TrAX already
uses if the user does want more control over the engine chosen)
Here is my proposal for an XSLTransform class
that significantly simplifies XSLT transforms in JDOM:

package org.jdom.transform;

public class XSLTransform implements Serializable, Cloneable {

  public XSLTransform(InputStream stylesheet) throws XSLException;
  public XSLTransform(Reader stylesheet) throws XSLException;
  public XSLTransform(File stylesheet) throws XSLException;
  public XSLTransform(Document stylesheet) throws XSLException;
  public XSLTransform(String systemID) throws XSLException;
 
  public Document transform(Document in) throws XSLException;

  // Usual utility methods:
  public Object clone();
  public boolean equals();
  public int hashCode();
  public String toString();
 
}

Internally, this still relies on TrAX. Externally, that's completely 
hidden from the user.

The XSLException class is a subclass of JDOMException.

The XSLTransform class is thread-safe. The same transform can be reused 
simultaneously in multiple
threads without reloading the stylesheet.

Some questions:

1. What's the right name for this class? I originally called it 
Stylesheet, but that's too
generic since it could potentially inlcude CSS, DSSSL , and other 
stylesheets.

2. Do we really want or need the Java utility methods and interfaces here?

3. Is there any need for providing access to TrAX attibutes, output 
keys, or parameters?
Output keys I'm pretty confident we dont need. We're not serializing 
here, just producing
a new JDOM document. Attributes also don't really apply since that's 
mostly about determining
what kinds of sources and results the engine supports. Parameters might 
actually be useful for
some advanced uses, but in practice I don't see them being used from 
outside the stylesheet that
often.

I wrote simple implementations of XSLTransform and XSLException in the
San Jose and Las Vegas airports on my way home from the conference.
Since they're relatively long I've put them up on my web site at

http://cafeconleche.org/jdom/XSLTransform.java
http://cafeconleche.org/jdom/XSLException.java

Take a look if you want to see how this all works internally. The 
JavaDoc is here:

http://cafeconleche.org/jdom/apidocs/org/jdom/transform/XSLTransform.html

-- 
+-----------------------+------------------------+-------------------+
| Elliotte Rusty Harold | elharo at metalab.unc.edu | Writer/Programmer |
+-----------------------+------------------------+-------------------+ 
|           The XML Bible, 2nd Edition (IDG Books, 2001)             |
|             http://www.cafeconleche.org/books/bible2/              |
|   http://www.amazon.com/exec/obidos/ISBN=0764547607/cafeaulaitA/   |
+----------------------------------+---------------------------------+
|  Read Cafe au Lait for Java News:   http://www.cafeaulait.org/     | 
|  Read Cafe con Leche for XML News:  http://www.cafeconleche.org/   |
+----------------------------------+---------------------------------+