cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Scott Boag/CAM/Lotus" <Scott_B...@lotus.com>
Subject SAT API Proposal (Draft 3) (was XSLT API)
Date Thu, 10 Feb 2000 08:19:45 GMT
I've done some radical things to the API formarly known as the "XSLT API".
I've come to the conclusion that this does not need to be, and should not
be, an XSLT API!  Rather, it should be a Transformation API.  Therefore I
am proposing renaming it to be the "Simple API for Transformations" (SAT
for now) in the potential siblingship with SAX, contengent, of course, on
Dave and who ever's in control on the org.xml space.

(Dave, I have been proposing a design for the past week that would define a
standard interface in Java for XSLT processors, that would be vendor
neutral).

I decided to use SAX2's (http://www.megginson.com/SAX/SAX2/) ContentHandler
and XMLReader interfaces, instead of SAX1's DocumentHandler and Parser,
which are depricated.  If the future is SAX2, this interface should just
use those and be done with it.  SAX1 can still be supported via some of
SAX2's helper classes, I think.  There's a fair number of methods that have
been ripped directly out of SAX.  This is in the spirit of trying to
provide a consistent interface with SAX.  Dave, if you are offended for
some reason, I'll rip them right out.

Making this a general Transformation API makes APIs for XML Serialization
logical to include in this package.  Therefore I have integrated in several
of Assaf Arkin's Serializer interfaces.  I pretty much just tossed them in
there, so some thinking will have to be done about the integration and
details.  In general, I think the serialization interfaces need to be
simplified a bit.

I did a pretty radical renaming of the objects based on the discussions in
the past days.  I think we should stick to Stylesheet instead of
Transformation for the stylesheet object, because it is in such common
usage, and letting us us that for the non-mutable bag of bits that is the
transformation instructions, let's us use "Transformation" for the
transformation context.  I am calling the object that creates stylesheets
the "Processor", again because it is in such common usage.  I added a
vendor neutral factory method on the Processor object that is modeled after
Sun's parser factory interfaces.

I've made the Transformation object derive from SAX2 XMLFilter/XMLReader.
This means that you can treate the transformation object as a parser!
Sounds a little weard at first (James Clark suggested doing this for Parser
several months back), but it seems to work out pretty well, at least from
the standpoint of the interface.  One could argue that
setDTDHandler/getDTDHandler is a little strange, but, then again, if you
think about it, maybe not so strange.

So, here is the english description of the transformation process described
by SAT:

========
You create an Processor, and it creates a Stylesheet from an input source.
You perform a transformation process to a result, using an input source,
stylesheet, parameters, and output properties.
========

Examples of usage:

  public static void exampleSimple()
    throws SATFactoryException, SATException
  {
    //=============================
    // Simple file transformation from file to output stream
    Processor processor = Processor.newInstance();

    Stylesheet stylesheet = processor.readStylesheet(new InputSource
("t1.xsl"));
    Transformation transform = stylesheet.newTransformation();

    transform.process(new InputSource("foo.xml"), new Result(System.out));
    //=============================
  }

  public static void exampleSAX()
    throws SATFactoryException, SATException,
    org.xml.sax.SAXException, java.io.IOException
  {
    //=============================
    // Use the Transformation as a SAX2 XMLFilter/XMLReader!
    Processor processor = Processor.newInstance();

    Stylesheet stylesheet = processor.readStylesheet(new InputSource
("t1.xsl"));
    Transformation transform = stylesheet.newTransformation();

    SerializerFactory sfactory = SerializerFactory.getSerializerFactory
( "xml" );
    Serializer serializer = sfactory.makeSerializer(System.out);

    transform.setContentHandler(serializer.asContentHandler());
    transform.parse(new InputSource("foo.xml"));
    //=============================
  }

  public static void exampleDOM()
    throws SATFactoryException, SATException,
           org.xml.sax.SAXException, java.io.IOException
  {
    //=============================
    // Use the Transformation as a SAX2 XMLFilter/XMLReader!
    Processor processor = Processor.newInstance();

    Stylesheet stylesheet = processor.readStylesheet(new InputSource
("t1.xsl"));
    Transformation transform = stylesheet.newTransformation();

    org.w3c.dom.Node outNode = new org.apache.xerces.dom.DocumentImpl();
    DOMParser parser = new DOMParser();
    parser.parse(new InputSource("foo.xml"));
    Document doc = parser.getDocument();
    transform.process(new NodeInputSource(doc), new Result(outNode));
    //=============================
  }


  public static void exampleParam()
    throws SATFactoryException, SATException
  {
    //=============================
    // Setting a parameter.
    Processor processor = Processor.newInstance();

    Stylesheet stylesheet = processor.readStylesheet(new InputSource
("t1.xsl"));
    Transformation transform = stylesheet.newTransformation();
    transform.setParameter("my-param", "http://foo.com" /* namespace */,
"hello");

    transform.process(new InputSource("foo.xml"), new Result(System.out));
    //=============================
  }

  public static void exampleOutputProps()
    throws SATFactoryException, SATException
  {
    //=============================
    // Simple setting of output instructions.
    Processor processor = Processor.newInstance();

    Stylesheet stylesheet = processor.readStylesheet(new InputSource
("t1.xsl"));
    OutputProperties oprops = stylesheet.getOutputProperties();
    oprops.setIndenting( true );
    Transformation transform = stylesheet.newTransformation();
    transform.setOutputProperties(oprops);

    transform.process(new InputSource("foo.xml"), new Result(System.out));
    //=============================
  }

  public static void exampleGetAssociated()
    throws SATFactoryException, SATException
  {
    //=============================
    // Get the default stylesheet for the document.
    Processor processor = Processor.newInstance();

    InputSource source
      = processor.getAssociatedStylesheet("text/xslt", null, null);
    // Processor may remember it read the given document...

    Stylesheet stylesheet = (null != source) ?
                            processor.readStylesheet(source) :
                            processor.readStylesheet(new InputSource
("default.xsl"));

    Transformation transform = stylesheet.newTransformation();

    transform.process(new InputSource("foo.xml"), new Result(System.out));
    //=============================
  }

  public static void exampleChaining()
    throws SATFactoryException, SATException,
           java.io.IOException, org.xml.sax.SAXException
  {
    //=============================
    // Chaining events from one transformation to another.
    Processor processor = Processor.newInstance();

    Stylesheet stylesheet1 = processor.readStylesheet(new InputSource
("t1.xsl"));
    Transformation transform1 = stylesheet1.newTransformation();

    Stylesheet stylesheet2= processor.readStylesheet(new InputSource
("t2.xsl"));
    Transformation transform2 = stylesheet2.newTransformation();

    Stylesheet  stylesheet3 = processor.readStylesheet(new InputSource
("t3.xsl"));
    Transformation transform3= stylesheet3.newTransformation();

    SerializerFactory sfactory = SerializerFactory.getSerializerFactory
( "xml" );
    Serializer serializer = sfactory.makeSerializer(System.out);

    transform3.setContentHandler(serializer.asContentHandler());
    transform2.setParent(transform3);
    transform1.setParent(transform2);
    transform1.parse(new InputSource("foo.xml"));
    //=============================

  }

There's still more details to be dealt with, but in general I feel this is
on the right track... I'm hoping to go through one more round of revisions
(hopefully less radical than the past ones), then put it up to vote to have
an alpha release that people can try to implement to.

(See attached file: URIResolver.java)(See attached file: Examples.java)(See
attached file: NodeInputSource.java)(See attached file:
OutputProperties.java)(See attached file: Processor.java)(See attached
file: Result.java)(See attached file: SATException.java)(See attached file:
SATFactoryException.java)(See attached file: Serializer.java)(See attached
file: SerializerFactory.java)(See attached file: Stylesheet.java)(See
attached file: StylesheetHandler.java)(See attached file:
Transformation.java)(See attached file: DOMSerializer.java)

-scott


Mime
View raw message