TRAX: suggested revised examples

[Kay Michael <Mi...@icl.com>]

I've prepared below a revised set of examples that show how I think I would
like this API to look. Haven't done the work of retrofitting this to a set
of interface definitions.

The classes used here are:

Processor - a piece of software that can do transformations
Stylesheet - an object that defines a specific kind of transformation
InputProvider - an object able to deliver a source document or stylesheet as
a set of SAX events
Transformation - an activation of a Stylesheet
OutputProperties - a description of the desired characteristics and
destination of the output of the transformation; and after the
transformation, a description of the actual characteristics.
QName - a qualified Name

I haven't found any need to expose Result. I've exposed Serializer simply as
one of the properties in OutputProperties.

I haven't worried about what the names should be, though I'm personally
happy with these.

I've gone for a "push" pipeline model, because I don't think SAX2's "pull"
model meets our requirements. This is from painful experience of integrating
Saxon with FOP, etc.

There is of course some finessing that could be done to add extra methods
that default some of the arguments, e.g. a default OutputProperties.

Mike Kay


package org.xml.trax;


/**
 * Just some examples to show how the Transformation API for XML 
 * could be used.
 */
 
public class Examples
{
  public static void exampleSimple()
    throws TRAXException
  {  
    //=============================
    // Simple file transformation from file to output stream
    Processor processor = Processor.newInstance();

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

    OutputProperties oprops = new OutputProperties();
    oprops.setOutputStream(System.out);

    transform.process(new InputProvider("foo.xml"), oprops);

    String mime = oprops.getMediaType();
    //=============================
  }
  
  public static void exampleSAXOutput()
    throws TRAXException
  {  
    //=============================
    // Send the result of the Transformation to a user-supplied SAX2
ContentHandler;
    // also uses a different SAX Parser for the stylesheet

    Processor processor = Processor.newInstance();

    InputProvider style = new InputProvider();
    style.setInputSource(new InputSource("file:/c:/t1.xsl"));
    style.setXSLReader(new com.microstar.aelfred.XMLReader());

    Stylesheet stylesheet = processor.readStylesheet(style);
    Transformation transform = stylesheet.newTransformation();

    OutputProperties oprops = new OutputProperties();
    oprops.setContentHandler(new UserContentHandler());

    transform.process(new InputProvider("foo.xml"), oprops);
    //=============================
  }
  
  public static void exampleDOMInput()
    throws TRAXException
  {  
    //=============================
    // Get source input from a DOM Node
    Processor processor = Processor.newInstance();

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

    Document doc = // some document //

    OutputProperties oprops = new OutputProperties();
    oprops.setOutputStream(System.out);
    transform.process(new InputProvider(doc), oprops);
    //=============================
  }


  public static void exampleParam()
    throws TRAXException
  {  
    //=============================
    // Simple file transformation from file to output stream with parameters
    // and setting of output properties to override those in stylesheet
    Processor processor = Processor.newInstance();

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

    OutputProperties oprops = new OutputProperties();
    oprops.setOutputStream(System.out);
    oprops.setIndenting(true);
    oprops.setOverrideStylesheet(true);

    QName param = new QName("prefix:my-favorite-number",
"http://namespace.org/uri");
    transform.setParameter(param, new Double(93.7));
    transform.process(new InputProvider("foo.xml"), oprops);
    //=============================
  }
    
  public static void exampleSAXInput()
    throws TRAXException
  {  
    //=============================
    // Transformation in which the application supplies input in the form of
a stream of
    // SAX events
    
    Processor processor = Processor.newInstance();

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

    OutputProperties oprops = new OutputProperties();
    oprops.setOutputStream(System.out);
    oprops.setIndenting(true);
    oprops.setOverrideStylesheet(true);
    transform.setOutputProperties(oprops);

    ContentHandler ch = transform.asContentHandler();
    ch.startDocument();
    ch.startElement("a", emptyAttributeList);
    ch.endElement("a");
    ch.endDocument();

    //=============================
  }
    
    
  public static void exampleChaining()
    throws TRAXException
  {  
    //=============================
    // Chaining events from one transformation to another.
    
    Processor processor = Processor.newInstance();

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

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

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

    OutputProperties oprops1 = new OutputProperties();
    transform1.setOutputProperties(oprops1);
    oprops1.setContentHandler(transform2.asContentHandler());

    OutputProperties oprops2 = new OutputProperties();
    transform2.setOutputProperties(oprops2);
    oprops2.setContentHandler(transform3.asContentHandler());

    OutputProperties oprops3 = new OutputProperties();
    transform3.setOutputProperties(oprops3);
    oprops3.setOutputStream(System.out);
  }

  public static void exampleAssociated()
    throws TRAXException
  {  
    //=============================
    // Transform a document using the stylesheet identified in its source
    Processor processor = Processor.newInstance();

    InputProvider source = new InputProvider("source.xml");
    InputProvider style = processor.getAssociatedStylesheet(source);

    Stylesheet stylesheet = processor.readStylesheet(style);
    Transformation transform = stylesheet.newTransformation();

    OutputProperties oprops = new OutputProperties();
    oprops.setOutputStream(System.out);

    transform.process(source, oprops);

    String mime = oprops.getMediaType();
    //=============================
  }

  public static void exampleEmbedded()
    throws TRAXException
  {  
    //=============================
    // Transform a document using the stylesheet identified and embedded 
    // in its source
    Processor processor = Processor.newInstance();

    InputProvider source = new InputProvider("source.xml");
    InputProvider style = processor.getAssociatedStylesheet(source);
	// no difference: the fact that it's embedded doesn't need to be
visible!

    Stylesheet stylesheet = processor.readStylesheet(style);
    Transformation transform = stylesheet.newTransformation();

    OutputProperties oprops = new OutputProperties();
    oprops.setOutputStream(System.out);

    transform.process(source, oprops);

    String mime = oprops.getMediaType();
    //=============================
  }

  public static void exampleSerializer()
    throws TRAXException
  {  
    //=============================
    // Use a different serializer from the processor's default one
    Processor processor = Processor.newInstance();

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

    OutputProperties oprops = new OutputProperties();
    oprops.setSerializer(new MyFavoriteSerializer());
    oprops.setOutputStream(System.out);

    transform.process(new InputProvider("foo.xml"), oprops);

    String mime = oprops.getMediaType();
    //=============================
  }

}

Re: Proposal for Serializer API

[Wong Kok Wai <wo...@pacific.net.sg>]

Hi Arkin,

My 2 cents comments on your Method class:

1) Maybe should rename the Method class to something else in order not to confuse
with java.lang.ref.Method. I prefer "MIMEType".
2) Why the differentiation between XML and XHTML?
3) Currently, it is declared final, how do I add RTF for example?
4) Using String does not allow range checking. For example, I can pass an invalid
String to setMethod of OutputFormat. Why not declare all the statics as Method
objects?

Proposal for Serializer API

[Assaf Arkin <ar...@exoffice.com>]

The purpose of the serializer API is to enable SAX events and DOM
documents to be written into a document. The serializer API allows any
implementation supporting any number of output formats (XML, HTML, PDF,
PNG, etc).

Originally this API was named serializer since it serializes a DOM
document into the output document, and is consistent with the term
'serializer' that XML and DOM specifications will refer to.

The serializer API assumes that a serializer implementation will exist,
whether or not an XSLT processor implementation exists, hence my
proposal to place it in a separate package. It does not assume, however,
that any given serializer implementation will be available.

Four output methods are defined by default (XML, HTML, XHTML, TEXT), so
implementations are encouraged to support all four.


The serializer API defines the following interfaces:

* SerializerFactory -- a way to acquire a new serializer for a given
output method

* Serializer --  a way to set the output format and output stream for a
serializer, and a way obtain a DocumentHandler (SAX1), ContentHandler
(SAX2) or DOMSerializer (DOM L1) for serializing

* OutputFormat -- basic set of output format properties based on
xsl:output. Implementations may use an extended class with additional
properties (e.g. indentation level, line separator, etc)

* Method -- a list of the four common output method names. Additional
methods should follow the uri:name pattern.

* QName -- QNames are used for CDATA and non-escaping elements

An implementation could roll all three serializers (SAX1, SAX2, DOM)
into one, or provide different implementations through the Serializer
interface.


By definition a Serializer is reusable. By changing the output
stream/output format, the same serializer can be used over and over.
However, a serializer is not multi-threaded -- it can only serialize one
document at any given time.

Currently there is no way to control namespace behavior. The serializer
will use the prefix/uris providers in the DOM/SAX events.


An XSLT processor may choose to use a serializer implementation, provide
a serializer implementation, or use it's internal mechanisms and ignore
this package all together. However, by supporting OutputFormat, the XSLT
processor allows the following to happen:

* A stylesheet is read using the XSLT processor and the OutputFormat is
returned to the application

* A document is transformed using the XSLT processor, and the resulting
document (DOM or SAX) is returned to the application

* The application performs further processing on the document, caching,
filtering, etc

* The application sends the document (DOM or SAX) to a serializer using
the OutputFormat read from the stylesheet

Comments?

arkin



-- 
----------------------------------------------------------------------
Assaf Arkin                                           www.exoffice.com
CTO, Exoffice Technologies, Inc.                        www.exolab.org

Proposal for Serializer API

[Assaf Arkin <ar...@exoffice.com>]

The purpose of the serializer API is to enable SAX events and DOM
documents to be written into a document. The serializer API allows any
implementation supporting any number of output formats (XML, HTML, PDF,
PNG, etc).

Originally this API was named serializer since it serializes a DOM
document into the output document, and is consistent with the term
'serializer' that XML and DOM specifications will refer to.

The serializer API assumes that a serializer implementation will exist,
whether or not an XSLT processor implementation exists, hence my
proposal to place it in a separate package. It does not assume, however,
that any given serializer implementation will be available.

Four output methods are defined by default (XML, HTML, XHTML, TEXT), so
implementations are encouraged to support all four.


The serializer API defines the following interfaces:

* SerializerFactory -- a way to acquire a new serializer for a given
output method

* Serializer --  a way to set the output format and output stream for a
serializer, and a way obtain a DocumentHandler (SAX1), ContentHandler
(SAX2) or DOMSerializer (DOM L1) for serializing

* OutputFormat -- basic set of output format properties based on
xsl:output. Implementations may use an extended class with additional
properties (e.g. indentation level, line separator, etc)

* Method -- a list of the four common output method names. Additional
methods should follow the uri:name pattern.

* QName -- QNames are used for CDATA and non-escaping elements

An implementation could roll all three serializers (SAX1, SAX2, DOM)
into one, or provide different implementations through the Serializer
interface.


By definition a Serializer is reusable. By changing the output
stream/output format, the same serializer can be used over and over.
However, a serializer is not multi-threaded -- it can only serialize one
document at any given time.

Currently there is no way to control namespace behavior. The serializer
will use the prefix/uris providers in the DOM/SAX events.


An XSLT processor may choose to use a serializer implementation, provide
a serializer implementation, or use it's internal mechanisms and ignore
this package all together. However, by supporting OutputFormat, the XSLT
processor allows the following to happen:

* A stylesheet is read using the XSLT processor and the OutputFormat is
returned to the application

* A document is transformed using the XSLT processor, and the resulting
document (DOM or SAX) is returned to the application

* The application performs further processing on the document, caching,
filtering, etc

* The application sends the document (DOM or SAX) to a serializer using
the OutputFormat read from the stylesheet

Comments?

arkin



-- 
----------------------------------------------------------------------
Assaf Arkin                                           www.exoffice.com
CTO, Exoffice Technologies, Inc.                        www.exolab.org