You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xalan.apache.org by sb...@locus.apache.org on 2000/06/20 18:30:28 UTC
cvs commit: xml-xalan/java/src/trax Examples.java Processor.java ProcessorException.java ProcessorFactoryException.java Result.java Templates.java TemplatesBuilder.java TransformException.java Transformer.java URIResolver.java package.html patterns.xml patterns.xsl trax.dfPackage trax.properties
sboag 00/06/20 09:30:26
Added: java/src/trax Examples.java Processor.java
ProcessorException.java
ProcessorFactoryException.java Result.java
Templates.java TemplatesBuilder.java
TransformException.java Transformer.java
URIResolver.java package.html patterns.xml
patterns.xsl trax.dfPackage trax.properties
Log:
no message
Revision Changes Path
1.1 xml-xalan/java/src/trax/Examples.java
Index: Examples.java
===================================================================
// Transformations for XML (TRaX)
// Copyright �2000 Lotus Development Corporation, Exoffice Technologies,
// Oracle Corporation, Michael Kay of International Computers Limited, Apache
// Software Foundation. All rights reserved.
package trax;
// Needed java classes
import java.io.InputStream;
import java.io.Reader;
import java.io.IOException;
// Needed SAX classes
import org.xml.sax.InputSource;
import org.xml.sax.SAXException;
import org.xml.sax.Parser;
import org.xml.sax.helpers.ParserAdapter;
// Needed DOM classes
import org.w3c.dom.Node;
// Needed Serializer classes
import org.apache.xml.serialize.OutputFormat;
import org.apache.xml.serialize.Serializer;
import org.apache.xml.serialize.SerializerFactory;
/**
* Some examples to show how the Simple API for Transformations
* could be used.
*
* @version Alpha
* @author <a href="mailto:scott_boag@lotus.com">Scott Boag</a>
*/
public class Examples
{
public static void main( String argv[] )
throws ProcessorException, ProcessorFactoryException,
TransformException, SAXException, IOException
{
exampleSimple("foo.xml", "foo.xsl");
}
/**
* Show the simplest possible transformation from system id to output stream.
* <pre>
Processor processor = Processor.newInstance("xslt");
Templates templates = processor.process(new InputSource("t1.xsl"));
Transformer transformer = templates.newTransformer();
transformer.transform(new InputSource("foo.xml"), new Result(System.out));
* </pre>
*/
public static void exampleSimple(String sourceID, String xslID)
throws ProcessorException, ProcessorFactoryException,
TransformException, SAXException, IOException
{
Processor processor = Processor.newInstance("xslt");
Templates templates = processor.process(new InputSource(xslID));
Transformer transformer = templates.newTransformer();
transformer.transform(new InputSource(sourceID), new Result(System.out));
}
/**
* Show the Transformer using SAX events in and SAX events out.
* <pre>
Processor processor = Processor.newInstance("xslt");
// Use the JAXP interface to get a SAX1 parser interface.
SAXParserFactory factory = SAXParserFactory.newInstance();
SAXParser saxparser = factory.newSAXParser();
Parser parser = saxparser.getParser();
// Have a Templates builder handle the parse events from the SAXParser's
// parse of an xslt file.
TemplatesBuilder templatesBuilder = processor.getTemplatesBuilder();
parser.setDocumentHandler(templatesBuilder);
parser.parse("t1.xsl");
Templates templates = templatesBuilder.getTemplates();
// Get a transformer instance for the templates.
Transformer transformer = templates.newTransformer();
// Set the result handling to be a serialization to System.out.
Serializer serializer = SerializerFactory.getSerializer( "xml" );
serializer.setOutputStream(System.out);
transformer.setContentHandler(serializer.asContentHandler());
// Is it my imagination, or is there no way to set the DeclHandler and
// the LexicalHandler, since there seems to be no way to get an
// XMLReader. This is a rather major problem. Hopefully, that will
// be fixed in the next round.
// Cause the transformation to occur by asking the parser to send
// the parse events from "foo.xsl" to the transformer.
parser.setDocumentHandler(transformer.getInputContentHandler());
parser.parse("foo.xml");
* </pre>
*/
/*
public static void exampleSAX2SAX()
throws SAXException, IOException // , ParserConfigurationException
{
Processor processor = Processor.newInstance("xslt");
// Use the JAXP interface to get a SAX1 parser interface.
SAXParserFactory factory = SAXParserFactory.newInstance();
SAXParser saxparser = factory.newSAXParser();
Parser parser = saxparser.getParser();
// Have a Templates builder handle the parse events from the SAXParser's
// parse of an xslt file.
TemplatesBuilder templatesBuilder = processor.getTemplatesBuilder();
parser.setDocumentHandler(templatesBuilder);
parser.parse("t1.xsl");
Templates templates = templatesBuilder.getTemplates();
// Get a transformer instance for the templates.
Transformer transformer = templates.newTransformer();
// Set the result handling to be a serialization to System.out.
Serializer serializer = SerializerFactory.getSerializer( "xml" );
serializer.setOutputStream(System.out);
transformer.setContentHandler(serializer.asContentHandler());
// Is it my imagination, or is there no way to set the DeclHandler and
// the LexicalHandler, since there seems to be no way to get an
// XMLReader. This is a rather major problem. Hopefully, that will
// be fixed in the next round.
// Cause the transformation to occur by asking the parser to send
// the parse events from "foo.xsl" to the transformer.
parser.setDocumentHandler(transformer.getInputContentHandler());
parser.parse("foo.xml");
}
*/
/**
* Show the Transformer using the JAXP interface for input.
* <pre>
Processor processor = Processor.newInstance("xslt");
// The transformer will use a SAX parser as it's reader.
SAXParserFactory factory = SAXParserFactory.newInstance();
SAXParser saxparser = factory.newSAXParser();
// Have a Templates builder handle the parse events from the SAXParser's
// parse of an xslt file.
TemplatesBuilder templatesBuilder = processor.getTemplatesBuilder();
saxparser.parse("t1.xsl", templatesBuilder);
Templates templates = templatesBuilder.getTemplates();
// Get a transformer instance for the templates.
Transformer transformer = templates.newTransformer();
// Set the result handling to be a serialization to System.out.
Serializer serializer = SerializerFactory.getSerializer( "xml" );
serializer.setOutputStream(System.out);
transformer.setContentHandler(serializer.asContentHandler());
// Is it my imagination, or is there no way to set the DeclHandler and
// the LexicalHandler, since there seems to be no way to get an
// XMLReader. This is a rather major problem. Hopefully, that will
// be fixed in the next round.
// Cause the transformation to occur by asking the parser to send
// the parse events from "foo.xsl" to the transformer.
saxparser.parse("foo.xml", transformer.getInputContentHandler());
* </pre>
*/
/*
public static void exampleJAXP2SAX2()
throws SAXException, IOException // , ParserConfigurationException
{
Processor processor = Processor.newInstance("xslt");
// The transformer will use a SAX parser as it's reader.
SAXParserFactory factory = SAXParserFactory.newInstance();
SAXParser saxparser = factory.newSAXParser();
// Have a Templates builder handle the parse events from the SAXParser's
// parse of an xslt file.
TemplatesBuilder templatesBuilder = processor.getTemplatesBuilder();
saxparser.parse("t1.xsl", templatesBuilder);
Templates templates = templatesBuilder.getTemplates();
// Get a transformer instance for the templates.
Transformer transformer = templates.newTransformer();
// Set the result handling to be a serialization to System.out.
Serializer serializer = SerializerFactory.getSerializer( "xml" );
serializer.setOutputStream(System.out);
transformer.setContentHandler(serializer.asContentHandler());
// Is it my imagination, or is there no way to set the DeclHandler and
// the LexicalHandler, since there seems to be no way to get an
// XMLReader. This is a rather major problem. Hopefully, that will
// be fixed in the next round.
// Cause the transformation to occur by asking the parser to send
// the parse events from "foo.xsl" to the transformer.
saxparser.parse("foo.xml", transformer.getInputContentHandler());
}
*/
/**
* Show the Transformer as a SAX2 XMLFilter/XMLReader. In this case
* the Transformer acts like a parser, and can in fact be polymorphicaly
* used in places where a SAX parser would be used.
* <pre>
Processor processor = Processor.newInstance("xslt");
Templates templates = processor.process(new InputSource("t1.xsl"));
Transformer transformer = templates.newTransformer();
// Set the result handling to be a serialization to System.out.
Serializer serializer = SerializerFactory.getSerializer( "xml" );
serializer.setOutputStream(System.out);
transformer.setContentHandler(serializer.asContentHandler());
// The transformer will use a SAX parser as it's reader.
SAXParserFactory factory = SAXParserFactory.newInstance();
SAXParser parser = factory.newSAXParser();
transformer.setParent(new ParserAdapter( parser.getParser() ));
// Now, when you call transformer.parse, it will set itself as
// the content handler for the parser object (it's "parent"), and
// will then call the parse method on the parser.
transformer.parse(new InputSource("foo.xml"));
* </pre>
*/
/*
public static void exampleXMLFilter()
throws SAXException, IOException// , ParserConfigurationException
{
Processor processor = Processor.newInstance("xslt");
Templates templates = processor.process(new InputSource("t1.xsl"));
Transformer transformer = templates.newTransformer();
// Set the result handling to be a serialization to System.out.
Serializer serializer = SerializerFactory.getSerializer( "xml" );
serializer.setOutputStream(System.out);
transformer.setContentHandler(serializer.asContentHandler());
// The transformer will use a SAX parser as it's reader.
SAXParserFactory factory = SAXParserFactory.newInstance();
SAXParser parser = factory.newSAXParser();
transformer.setParent(new ParserAdapter( parser.getParser() ));
// Now, when you call transformer.parse, it will set itself as
// the content handler for the parser object (it's "parent"), and
// will then call the parse method on the parser.
transformer.parse(new InputSource("foo.xml"));
}
*/
/**
* This example shows how to chain events from one Transformer
* to another transformer, using the Transformer as a
* SAX2 XMLFilter/XMLReader.
* <pre>
Processor processor = Processor.newInstance("xslt");
Templates stylesheet1 = processor.process(new InputSource("t1.xsl"));
Transformer transformer1 = stylesheet1.newTransformer();
Templates stylesheet2= processor.process(new InputSource("t2.xsl"));
Transformer transformer2 = stylesheet2.newTransformer();
Templates stylesheet3 = processor.process(new InputSource("t3.xsl"));
Transformer transformer3= stylesheet3.newTransformer();
// transformer1 will use a SAX parser as it's reader.
SAXParserFactory factory = SAXParserFactory.newInstance();
SAXParser parser = factory.newSAXParser();
transformer1.setParent(new ParserAdapter( parser.getParser() ));
// transformer2 will use transformer1 as it's reader.
transformer2.setParent(transformer1);
// transform3 will use transform2 as it's reader.
transformer3.setParent(transformer2);
// transform3 will output the events to the serializer.
Serializer serializer = SerializerFactory.getSerializer( "xml" );
serializer.setOutputStream(System.out);
transformer3.setContentHandler(serializer.asContentHandler());
// Now, when you call transformer3 to parse, it will set
// itself as the ContentHandler for transform2, and
// call transform2.parse, which will set itself as the
// content handler for transform1, and call transform1.parse,
// which will set itself as the content listener for the
// SAX parser, and call parser.parse(new InputSource("foo.xml")).
transformer3.parse(new InputSource("foo.xml"));
* </pre>
*/
/*
public static void exampleXMLFilterChain()
throws SAXException, IOException// , ParserConfigurationException
{
Processor processor = Processor.newInstance("xslt");
Templates stylesheet1 = processor.process(new InputSource("t1.xsl"));
Transformer transformer1 = stylesheet1.newTransformer();
Templates stylesheet2= processor.process(new InputSource("t2.xsl"));
Transformer transformer2 = stylesheet2.newTransformer();
Templates stylesheet3 = processor.process(new InputSource("t3.xsl"));
Transformer transformer3= stylesheet3.newTransformer();
// transformer1 will use a SAX parser as it's reader.
SAXParserFactory factory = SAXParserFactory.newInstance();
SAXParser parser = factory.newSAXParser();
transformer1.setParent(new ParserAdapter( parser.getParser() ));
// transformer2 will use transformer1 as it's reader.
transformer2.setParent(transformer1);
// transform3 will use transform2 as it's reader.
transformer3.setParent(transformer2);
// transform3 will output the events to the serializer.
Serializer serializer = SerializerFactory.getSerializer( "xml" );
serializer.setOutputStream(System.out);
transformer3.setContentHandler(serializer.asContentHandler());
// Now, when you call transformer3 to parse, it will set
// itself as the ContentHandler for transform2, and
// call transform2.parse, which will set itself as the
// content handler for transform1, and call transform1.parse,
// which will set itself as the content listener for the
// SAX parser, and call parser.parse(new InputSource("foo.xml")).
transformer3.parse(new InputSource("foo.xml"));
}
*/
/**
* Show how to transform a DOM tree into another DOM tree.
* This uses the javax.xml.parsers to parse an XML file into a
* DOM, and create an output DOM.
* <pre>
Processor processor = Processor.newInstance("xslt");
if(processor.getFeature("http://xml.org/trax/features/dom/input"))
{
Templates templates = processor.process(new InputSource("t1.xsl"));
Transformer transformer = templates.newTransformer();
DocumentBuilderFactory dfactory = DocumentBuilderFactory.newInstance();
DocumentBuilder docBuilder = dfactory.newDocumentBuilder();
org.w3c.dom.Node outNode = docBuilder.newDocument();
Node doc = docBuilder.parse(new InputSource("foo.xml"));
transformer.transformNode(doc, new Result(outNode));
}
else
{
throw new org.xml.sax.SAXNotSupportedException("DOM node processing not supported!");
}
* </pre>
*/
/*
public static void exampleDOM2DOM()
throws SAXException, IOException// , ParserConfigurationException
{
Processor processor = Processor.newInstance("xslt");
if(processor.getFeature("http://xml.org/trax/features/dom/input"))
{
Templates templates = processor.process(new InputSource("t1.xsl"));
Transformer transformer = templates.newTransformer();
DocumentBuilderFactory dfactory = DocumentBuilderFactory.newInstance();
DocumentBuilder docBuilder = dfactory.newDocumentBuilder();
org.w3c.dom.Node outNode = docBuilder.newDocument();
Node doc = docBuilder.parse(new InputSource("foo.xml"));
transformer.transformNode(doc, new Result(outNode));
}
else
{
throw new org.xml.sax.SAXNotSupportedException("DOM node processing not supported!");
}
}
*/
/**
* This shows how to set a parameter for use by the templates.
* <pre>
Processor processor = Processor.newInstance("xslt");
Templates templates = processor.process(new InputSource("t1.xsl"));
Transformer transformer = templates.newTransformer();
transformer.setParameter("my-param", "http://foo.com", "hello");
transformer.transform(new InputSource("foo.xml"), new Result(System.out));
* </pre>
*/
public static void exampleParam()
throws ProcessorException, ProcessorFactoryException,
TransformException, SAXException, IOException
{
Processor processor = Processor.newInstance("xslt");
Templates templates = processor.process(new InputSource("t1.xsl"));
Transformer transformer = templates.newTransformer();
transformer.setParameter("my-param", "http://foo.com" /* namespace */, "hello");
transformer.transform(new InputSource("foo.xml"), new Result(System.out));
}
/**
* Show how to override output properties.
* <pre>
Processor processor = Processor.newInstance("xslt");
Templates templates = processor.process(new InputSource("t1.xsl"));
OutputFormat oprops = templates.getOutputFormat();
oprops.setIndenting( true );
Transformer transformer = templates.newTransformer();
transformer.setOutputFormat(oprops);
transformer.transform(new InputSource("foo.xml"), new Result(System.out));
* </pre>
*/
public static void exampleOutputFormat()
throws ProcessorException, ProcessorFactoryException,
TransformException, SAXException, IOException
{
Processor processor = Processor.newInstance("xslt");
Templates templates = processor.process(new InputSource("t1.xsl"));
OutputFormat oprops = templates.getOutputFormat();
oprops.setIndenting( true );
Transformer transformer = templates.newTransformer();
transformer.setOutputFormat(oprops);
transformer.transform(new InputSource("foo.xml"), new Result(System.out));
}
/**
* Show how to get stylesheets that are associated with a given
* xml document via the xml-stylesheet PI (see http://www.w3.org/TR/xml-stylesheet/).
* <pre>
Processor processor = Processor.newInstance("xslt");
InputSource docSouce = new InputSource("foo.xml");
InputSource[] sources
= processor.getAssociatedStylesheets(docSouce, "text/xslt", null, null);
// Processor may remember it read the given document...
Templates templates = (null != sources) ?
processor.processMultiple(sources) :
processor.process(new InputSource("default.xsl"));
Transformer transformer = templates.newTransformer();
transformer.transform(docSouce, new Result(System.out));
* </pre>
*/
public static void exampleUseAssociated()
throws ProcessorException, ProcessorFactoryException,
TransformException, SAXException, IOException
{
Processor processor = Processor.newInstance("xslt");
InputSource docSouce = new InputSource("foo.xml");
InputSource[] sources
= processor.getAssociatedStylesheets(docSouce, "text/xslt", null, null);
// Processor may remember it read the given document...
Templates templates = (null != sources) ?
processor.processMultiple(sources) :
processor.process(new InputSource("default.xsl"));
Transformer transformer = templates.newTransformer();
transformer.transform(docSouce, new Result(System.out));
}
}
1.1 xml-xalan/java/src/trax/Processor.java
Index: Processor.java
===================================================================
// Transformations for XML (TRaX)
// Copyright �2000 Lotus Development Corporation, Exoffice Technologies,
// Oracle Corporation, Michael Kay of International Computers Limited, Apache
// Software Foundation. All rights reserved.
package trax;
import java.io.IOException;
import org.xml.sax.InputSource;
import org.xml.sax.SAXException;
import org.xml.sax.SAXNotSupportedException;
import org.xml.sax.SAXNotRecognizedException;
import org.xml.sax.XMLReader;
import org.xml.sax.ErrorHandler;
import org.w3c.dom.Node;
/**
* A particular transformation Processor is "plugged" into the platform via
* Processor in one of two ways: 1) as a platform default,
* and 2) through external specification by a system property named
* "org.xml.trax.Processor.[type]" obtained using
* java.lang.System.getProperty(). The [type] part of the property specifies
* the language to be used, for instance, "trax.processor.xslt" would
* specify an XSLT processor. This property (or platform default)
* names a class that is a concrete subclass of org.xml.trax.Processor.
* The subclass shall implement a public no-args constructor used by
* the base abstract class to create an instance of the factory using
* the newInstance() method.
*
* <p>The platform default is only used if no external implementation is
* available.</p>
*
* <h3>Open issues:</h3>
* <dl>
* <dt><h4>Separate Factory?</h4></dt>
* <dd>Should there be a separate ProcessorFactory class, to be
* more consistent with javax.xml.parsers.SAXParserFactory? Doing this
* would allow this class to be an interface instead of an abstract class.</dd>
* <dt><h4>Separate DOM Interface?</h4></dt>
* <dd>Should there be a separate DOMProcessor class, instead of
* having the processFromNode method?</dd>
* <dt><h4>XMLReader vs. Parser vs. SAXParser/DocumentBuilder</h4></dt>
* <dd>Currently the interfaces support XMLReader. Should this be
* javax.xml.parsers.SAXParser/javax.xml.parsers.DocumentBuilder?
* Or, perhaps just org.xml.sax.Parser?</dd>
* <dt><h4>XMLReader derivation?</h4></dt>
* <dd>Should this derive from XMLReader (in a similar way that Transformer
* derives from XMLFilter)?</dd>
* </dl>
*
* @version Alpha
* @author <a href="mailto:scott_boag@lotus.com">Scott Boag</a>
*/
public abstract class Processor
{
/**
* Set the name of the default concrete class to be used.
*/
private static String platformDefaultFactoryName = null;
/**
* Set the name of the default concrete class to be used.
* @param classname Full classname of concrete implementation
* of org.xml.trax.Processor.
*/
public static void setPlatformDefaultProcessor(String classname)
{
platformDefaultFactoryName = classname;
}
/**
* Obtain a new instance of a Processor object.
* @return Concrete instance of an Processor object.
*/
public static Processor newInstance(String type)
throws ProcessorFactoryException
{
Processor factory = null;
try
{
String factoryName = System.getProperty("trax.processor."+type);
if(null == factoryName)
factoryName = platformDefaultFactoryName;
if(null == factoryName)
throw new ProcessorFactoryException("Can't find system property trax.processor.xslt", null);
Class factoryClass = Class.forName(factoryName);
factory = (Processor)factoryClass.newInstance();
}
catch(java.lang.IllegalAccessException iae)
{
throw new ProcessorFactoryException("Transformation Processor can not be accessed!", iae);
}
catch(java.lang.InstantiationException ie)
{
throw new ProcessorFactoryException("Not able to create Transformation Processor!", ie);
}
catch(java.lang.ClassNotFoundException cnfe)
{
throw new ProcessorFactoryException("Transformation Processor not found!", cnfe);
}
return factory;
}
/**
* Process the source into a templates object.
*
* @param source An object that holds a URL, input stream, etc.
* @returns A Templates object capable of being used for transformation purposes.
* @exception SAXException May throw this if it needs to create a XMLReader,
* and XMLReaderFactory.createXMLReader() fails.
* @exception java.io.IOException An IO exception from the parser,
* possibly from a byte stream or character stream
* supplied by the application.
* @exception ProcessorException May throw this during the parse when it
* is constructing the Templates object and fails.
*/
public abstract Templates process(InputSource source)
throws ProcessorException, SAXException, IOException;
/**
* Process the stylesheet from a DOM tree, if the
* processor supports the "http://xml.org/trax/features/dom/input"
* feature.
*
* @param node A DOM tree which must contain
* valid transform instructions that this processor understands.
* @returns A Templates object capable of being used for transformation purposes.
*/
public abstract Templates processFromNode(Node node)
throws ProcessorException;
/**
* Process a series of inputs, treating them in import or cascade
* order. This is mainly for support of the getAssociatedStylesheets
* method, but may be useful for other purposes.
*
* @param sources An array of SAX InputSource objects.
* @returns A Templates object capable of being used for transformation purposes.
*/
public abstract Templates processMultiple(InputSource[] source)
throws ProcessorException;
/**
* Get InputSource specification(s) that are associated with the
* given document specified in the source param,
* via the xml-stylesheet processing instruction
* (see http://www.w3.org/TR/xml-stylesheet/), and that matches
* the given criteria. Note that it is possible to return several stylesheets
* that match the criteria, in which case they are applied as if they were
* a list of imports or cascades.
* <p>Note that DOM2 has it's own mechanism for discovering stylesheets.
* Therefore, there isn't a DOM version of this method.</p>
*
* <h3>Open issues:</h3>
* <dl>
* <dt><h4>Does the xml-stylesheet recommendation really support multiple stylesheets?</h4></dt>
* <dd>Mike Kay wrote: I don't see any support in the
* xml-stylesheet recommendation for this interpretation of what you should do
* if there's more than one match. Scott Boag replies: It's in the HTML references.
* But it's a bit subtle. We talked about this at the last XSL WG F2F, and people
* agreed to the multiple stylesheet stuff. I'll try and work out the specific
* references. Probably the xml-stylesheet recommendation needs to have a note
* added to it.</dd>
* </dl>
*
* @param media The media attribute to be matched. May be null, in which
* case the prefered templates will be used (i.e. alternate = no).
* @param title The value of the title attribute to match. May be null.
* @param charset The value of the charset attribute to match. May be null.
* @returns An array of InputSources that can be passed to processMultiple method.
*/
public abstract InputSource[] getAssociatedStylesheets(InputSource source,
String media,
String title,
String charset)
throws ProcessorException;
/**
* Get a TemplatesBuilder object that can process SAX
* events into a Templates object, if the processor supports the
* "http://xml.org/trax/features/sax/input" feature.
*
* <h3>Open issues:</h3>
* <dl>
* <dt><h4>Should Processor derive from org.xml.sax.ContentHandler?</h4></dt>
* <dd>Instead of requesting an object from the Processor class, should
* the Processor class simply derive from org.xml.sax.ContentHandler?</dd>
* </dl>
* @return A TemplatesBuilder object, or null if not supported.
* @exception May throw a ProcessorException if a TemplatesBuilder
* can not be constructed for some reason.
*/
public abstract TemplatesBuilder getTemplatesBuilder()
throws ProcessorException;
//======= CONFIGURATION METHODS =======
/**
* The XML reader to be used for the templates,
* and for the source documents if it is not set.
*/
private XMLReader reader;
/**
* Set an XML parser for the templates. This may also
* be used for the XML input for the source tree, if
* the setXMLReader method on the Transformation
* method is not set.
*/
public void setXMLReader(XMLReader reader)
{
this.reader = reader;
}
/**
* Get the XML parser used for the templates. This may also
* be used for the XML input for the source tree, if
* the setXMLReader method on the Transformation
* method is not set.
* @return Valid XMLReader object, or null if none has been set.
*/
public XMLReader getXMLReader()
{
return reader;
}
/**
* Look up the value of a feature.
*
* <p>The feature name is any fully-qualified URI. It is
* possible for an Processor to recognize a feature name but
* to be unable to return its value; this is especially true
* in the case of an adapter for a SAX1 Parser, which has
* no way of knowing whether the underlying parser is
* validating, for example.</p>
*
* <h3>Open issues:</h3>
* <dl>
* <dt><h4>Should getFeature be changed to hasFeature?</h4></dt>
* <dd>Keith Visco writes: Should getFeature be changed to hasFeature?
* It returns a boolean which indicated whether the "state"
* of feature is "true or false". I assume this means whether
* or not a feature is supported? I know SAX is using "getFeature",
* but to me "hasFeature" is cleaner.</dd>
* </dl>
*
* @param name The feature name, which is a fully-qualified
* URI.
* @return The current state of the feature (true or false).
* @exception org.xml.sax.SAXNotRecognizedException When the
* Processor does not recognize the feature name.
* @exception org.xml.sax.SAXNotSupportedException When the
* Processor recognizes the feature name but
* cannot determine its value at this time.
*/
public boolean getFeature (String name)
throws SAXNotRecognizedException, SAXNotSupportedException
{
throw new SAXNotRecognizedException(name);
}
/**
* Set the state of a feature.
*
* <p>The feature name is any fully-qualified URI. It is
* possible for an Processor to recognize a feature name but
* to be unable to set its value; this is especially true
* in the case of an adapter for a SAX1 Parser, which has
* no way of affecting whether the underlying parser is
* validating, for example.</p>
*
* @param name The feature name, which is a fully-qualified
* URI.
* @param state The requested state of the feature (true or false).
* @exception org.xml.sax.SAXNotRecognizedException When the
* Processor does not recognize the feature name.
* @exception org.xml.sax.SAXNotSupportedException When the
* Processor recognizes the feature name but
* cannot set the requested value.
*/
public void setFeature (String name, boolean value)
throws SAXNotRecognizedException, SAXNotSupportedException
{
throw new SAXNotRecognizedException(name);
}
private URIResolver resolver;
/**
* Set an object that will be used to resolve URIs used in
* xsl:import, etc. This will be used as the default for the
* transformation.
* @param resolver An object that implements the URIResolver interface,
* or null.
*/
public void setURIResolver(URIResolver resolver)
{
this.resolver = resolver;
}
/**
* Set an object that will be used to resolve URIs used in
* xsl:import, etc. This will be used as the default for the
* transformation.
* @param resolver An object that implements the URIResolver interface,
* or null.
*/
public URIResolver getURIResolver()
{
return resolver;
}
ErrorHandler errorHandler;
/**
* Allow an application to register an error event handler.
*
* <p>If the application does not register an error handler, all
* error events reported by the SAX parser will be silently
* ignored; however, normal processing may not continue. It is
* highly recommended that all SAX applications implement an
* error handler to avoid unexpected bugs.</p>
*
* <p>Applications may register a new or different handler in the
* middle of a parse, and the SAX parser must begin using the new
* handler immediately.</p>
*
* @param handler The error handler.
* @exception java.lang.NullPointerException If the handler
* argument is null.
* @see #getErrorHandler
*/
public void setErrorHandler (ErrorHandler handler)
{
if (handler == null) {
throw new NullPointerException("Null error handler");
}
errorHandler = handler;
}
/**
* Return the current error handler.
*
* @return The current error handler, or null if none
* has been registered.
* @see #setErrorHandler
*/
public ErrorHandler getErrorHandler ()
{
return errorHandler;
}
}
1.1 xml-xalan/java/src/trax/ProcessorException.java
Index: ProcessorException.java
===================================================================
// Transformations for XML (TRaX)
// Copyright �2000 Lotus Development Corporation, Exoffice Technologies,
// Oracle Corporation, Michael Kay of International Computers Limited, Apache
// Software Foundation. All rights reserved.
package trax;
import org.xml.sax.SAXParseException;
import org.xml.sax.Locator;
import org.xml.sax.helpers.LocatorImpl;
/**
* This exception serves as a root exception of TRaX exception, and
* is thrown in raw form when an exceptional condition occurs in the
* Processor object.
*
* <h3>Open issues:</h3>
* <dl>
* <dt><h4>Abstract exception root?</h4></dt>
* <dd>Should the root TRaX exception be abstract?</dd>
* <dt><h4>Derive from SAXException?</h4></dt>
* <dd>Keith Visco writes: I don't think these exceptions should extend
* SAXException, but could nest a SAXException if necessary.</dd>
* </dl>
*
* @version Alpha
* @author <a href="mailto:scott_boag@lotus.com">Scott Boag</a>
*/
public class ProcessorException extends SAXParseException
{
//////////////////////////////////////////////////////////////////////
// Constructors.
//////////////////////////////////////////////////////////////////////
/**
* Create a new ProcessorException from a message and a Locator.
*
* <p>This constructor is especially useful when an application is
* creating its own exception from within a DocumentHandler
* callback.</p>
*
* @param message The error or warning message.
* @param locator The locator object for the error or warning.
* @see org.xml.sax.Locator
* @see org.xml.sax.Parser#setLocale
*/
public ProcessorException (String message, Locator locator)
{
super(message, locator);
}
/**
* Wrap an existing exception in a ProcessorException.
*
* <p>This constructor is especially useful when an application is
* creating its own exception from within a DocumentHandler
* callback, and needs to wrap an existing exception that is not a
* subclass of SAXException.</p>
*
* @param message The error or warning message, or null to
* use the message from the embedded exception.
* @param locator The locator object for the error or warning.
* @param e Any exception
* @see org.xml.sax.Locator
* @see org.xml.sax.Parser#setLocale
*/
public ProcessorException (String message, Locator locator,
Exception e)
{
super( message, locator, e);
}
/**
* Wrap an existing exception in a ProcessorException.
*
* <p>This is used for throwing processor exceptions before
* the processing has started.</p>
*
* @param message The error or warning message, or null to
* use the message from the embedded exception.
* @param e Any exception
* @see org.xml.sax.Locator
* @see org.xml.sax.Parser#setLocale
*/
public ProcessorException (String message, Exception e)
{
super( "TRaX Processor Exception", new LocatorImpl(), e);
}
/**
* Create a new ProcessorException.
*
* <p>This constructor is most useful for parser writers.</p>
*
* <p>If the system identifier is a URL, the parser must resolve it
* fully before creating the exception.</p>
*
* @param message The error or warning message.
* @param publicId The public identifer of the entity that generated
* the error or warning.
* @param systemId The system identifer of the entity that generated
* the error or warning.
* @param lineNumber The line number of the end of the text that
* caused the error or warning.
* @param columnNumber The column number of the end of the text that
* cause the error or warning.
* @see org.xml.sax.Parser#setLocale
*/
public ProcessorException (String message, String publicId, String systemId,
int lineNumber, int columnNumber)
{
super(message, publicId, systemId, lineNumber, columnNumber);
}
/**
* Create a new ProcessorException with an embedded exception.
*
* <p>This constructor is most useful for parser writers who
* need to wrap an exception that is not a subclass of
* SAXException.</p>
*
* <p>If the system identifier is a URL, the parser must resolve it
* fully before creating the exception.</p>
*
* @param message The error or warning message, or null to use
* the message from the embedded exception.
* @param publicId The public identifer of the entity that generated
* the error or warning.
* @param systemId The system identifer of the entity that generated
* the error or warning.
* @param lineNumber The line number of the end of the text that
* caused the error or warning.
* @param columnNumber The column number of the end of the text that
* cause the error or warning.
* @param e Another exception to embed in this one.
* @see org.xml.sax.Parser#setLocale
*/
public ProcessorException (String message, String publicId, String systemId,
int lineNumber, int columnNumber, Exception e)
{
super(message, publicId, systemId, lineNumber, columnNumber, e);
}
}
1.1 xml-xalan/java/src/trax/ProcessorFactoryException.java
Index: ProcessorFactoryException.java
===================================================================
// Transformations for XML (TRaX)
// Copyright �2000 Lotus Development Corporation, Exoffice Technologies,
// Oracle Corporation, Michael Kay of International Computers Limited, Apache
// Software Foundation. All rights reserved.
package trax;
import org.xml.sax.SAXException;
/**
* The ProcessorFactoryException is a type of ProcessorException that
* is thrown when a configurable factory object can not
* be created.
*
* <h3>Open issues:</h3>
* <dl>
* <dt><h4>No open issues are known for this class</h4></dt>
* <dd></dd>
* </dl>
*
* @version Alpha
* @author <a href="mailto:scott_boag@lotus.com">Scott Boag</a>
*/
public class ProcessorFactoryException extends SAXException
{
/**
* Create a new ProcessorFactoryException from an existing exception.
*
* @param message The detail message.
* @param e The exception to be wrapped in a SAXException.
* @see org.xml.sax.SAXException
*
* @version Alpha
* @author <a href="mailto:scott_boag@lotus.com">Scott Boag</a>
*/
public ProcessorFactoryException (String message, Exception e)
{
super(message, e);
}
}
1.1 xml-xalan/java/src/trax/Result.java
Index: Result.java
===================================================================
// Transformations for XML (TRaX)
// Copyright �2000 Lotus Development Corporation, Exoffice Technologies,
// Oracle Corporation, Michael Kay of International Computers Limited, Apache
// Software Foundation. All rights reserved.
package trax;
import java.lang.String;
import java.io.OutputStream;
import java.io.Writer;
import org.w3c.dom.Node;
/**
* Acts as an holder for result tree specifications.
* <p>This class is modeled after the SAX InputSource class, except that it
* is for the Result target, and in addition to streams, and writers,
* it also can specify a DOM node to which nodes will be appended.</p>
*
* <h3>Open issues:</h3>
* <dl>
* <dt><h4>Should this be an interface?</h4></dt>
* <dd>Should this be an interface instead of a concrete class? The justification
* for it being a class is that it is just a bag of data, and contains no
* behavior of its own.</dd>
* </dl>
*
* @version Alpha
* @author <a href="mailto:scott_boag@lotus.com">Scott Boag</a>
*/
public class Result
{
/**
* Zero-argument default constructor.
*/
public Result ()
{
}
/**
* Create a new output target with a byte stream.
*
* @param byteStream The raw byte stream that will contain the document.
*/
public Result (OutputStream byteStream)
{
setByteStream(byteStream);
}
/**
* Create a new output target with a character stream.
*
* @param characterStream The character stream where the results will be written.
*/
public Result (Writer characterStream)
{
setCharacterStream(characterStream);
}
/**
* Create a new output target with a character stream.
*
* @param characterStream The character stream where the results will be written.
*/
public Result (Node n)
{
setNode(n);
}
/**
* Set the byte stream for this output target.
*
* @param byteStream A byte stream that will contain the result document.
*/
public void setByteStream (OutputStream byteStream)
{
this.byteStream = byteStream;
}
/**
* Get the byte stream for this output target.
*
* @return The byte stream, or null if none was supplied.
*/
public OutputStream getByteStream ()
{
return byteStream;
}
/**
* Set the character stream for this output target.
*
* @param characterStream The character stream that will contain
* the result document.
*/
public void setCharacterStream (Writer characterStream)
{
this.characterStream = characterStream;
}
/**
* Get the character stream for this output target.
*
* @return The character stream, or null if none was supplied.
*/
public Writer getCharacterStream ()
{
return characterStream;
}
/**
* Set the node that will contain the result nodes.
*/
public void setNode (Node node)
{
this.node = node;
}
/**
* Get the node that will contain the result nodes.
*/
public Node getNode ()
{
return node;
}
//////////////////////////////////////////////////////////////////////
// Internal state.
//////////////////////////////////////////////////////////////////////
private String fileName;
private OutputStream byteStream;
private String encoding;
private Writer characterStream;
private Node node;
}
1.1 xml-xalan/java/src/trax/Templates.java
Index: Templates.java
===================================================================
// Transformations for XML (TRaX)
// Copyright �2000 Lotus Development Corporation, Exoffice Technologies,
// Oracle Corporation, Michael Kay of International Computers Limited, Apache
// Software Foundation. All rights reserved.
package trax;
import org.apache.xml.serialize.OutputFormat;
/**
* The Templates object is the runtime representation of compiled
* transformation instructions. Templatess must be threadsafe for a given instance
* over multiple threads concurrently, and are generally meant to
* be used many multiple times for a given session.
*
* <h3>Open issues:</h3>
* <dl>
* <dt><h4>newTransformer</h4></dt>
* <dd>Is newTransformer the right way to create a transformer? The alternative might
* be to have a factory method in the Transformer class that takes as an argument
* a Templates object.</dd>
* </dl>
*
* @version Alpha
* @author <a href="mailto:scott_boag@lotus.com">Scott Boag</a>
*/
public interface Templates
{
/**
* Create a new transformation context for this Templates object.
*/
Transformer newTransformer();
/**
* Get the properties for xsl:output. The object returned will
* be a clone of the internal values, and thus it can be mutated
* without mutating the Templates object, and then handed in to
* the process method.
* @return A OutputProperties object that may be mutated.
*
* @see org.xml.serialize.OutputFormat
*/
OutputFormat getOutputFormat();
}
1.1 xml-xalan/java/src/trax/TemplatesBuilder.java
Index: TemplatesBuilder.java
===================================================================
// Transformations for XML (TRaX)
// Copyright �2000 Lotus Development Corporation, Exoffice Technologies,
// Oracle Corporation, Michael Kay of International Computers Limited, Apache
// Software Foundation. All rights reserved.
package trax;
/**
* This is a SAX ContentHandler that may be used to process SAX
* events into an Templates objects. This is an abstract class
* instead of an interface, so it can be a ContentHandler object,
* for passing into the JAXP SAXParser interface.
*
* <h3>Open issues:</h3>
* <dl>
* <dt><h4>Should Processor derive from org.xml.sax.ContentHandler?</h4></dt>
* <dd>Instead of requesting an object from the Processor class, should
* the Processor class simply derive from org.xml.sax.ContentHandler?</dd>
* <dt><h4>ContentHandler vs. ContentHandler</h4></dt>
* <dd>I don't think I would use ContentHandler at all, except that JAXP uses it.
* Maybe we should go back to using ContentHandler?</dd>
* </dl>
*/
public interface TemplatesBuilder extends org.xml.sax.ContentHandler
{
/**
* When this object is used as a ContentHandler or DocumentHandler, it will
* create a Templates object, which the caller can get once
* the SAX events have been completed.
* @return The stylesheet object that was created during
* the SAX event process, or null if no stylesheet has
* been created.
*
* @version Alpha
* @author <a href="mailto:scott_boag@lotus.com">Scott Boag</a>
*/
public Templates getTemplates()
throws TransformException;
/**
* Set the base ID (URL or system ID) for the stylesheet
* created by this builder. This must be set in order to
* resolve relative URLs in the stylesheet.
* @param baseID Base URL for this stylesheet.
*/
public void setBaseID(String baseID);
}
1.1 xml-xalan/java/src/trax/TransformException.java
Index: TransformException.java
===================================================================
// Transformations for XML (TRaX)
// Copyright �2000 Lotus Development Corporation, Exoffice Technologies,
// Oracle Corporation, Michael Kay of International Computers Limited, Apache
// Software Foundation. All rights reserved.
package trax;
import org.xml.sax.SAXParseException;
import org.xml.sax.Locator;
import org.xml.sax.helpers.LocatorImpl;
/**
* This simply subclasses the TransformException for the purposes
* of being able to be caught in a catch clause.
*
* <h3>Open issues:</h3>
* <dl>
* <dt><h4>No open issues are known for this class</h4></dt>
* <dd></dd>
* </dl>
*
* @version Alpha
* @author <a href="mailto:scott_boag@lotus.com">Scott Boag</a>
*/
public class TransformException extends SAXParseException
{
/**
* Create a new TransformException.
*
* @param message The error or warning message.
* @see org.xml.sax.SAXException
*/
public TransformException (String message)
{
super(message, new LocatorImpl());
}
/**
* Create a new TransformException wrapping an existing exception.
*
* @param e The exception to be wrapped in a SAXException.
* @see org.xml.sax.SAXException
*/
public TransformException (Exception e)
{
super("TRaX Transform Exception", new LocatorImpl(), e);
}
/**
* Wrap an existing exception in a TransformException.
*
* <p>This is used for throwing processor exceptions before
* the processing has started.</p>
*
* @param message The error or warning message, or null to
* use the message from the embedded exception.
* @param e Any exception
* @see org.xml.sax.Locator
* @see org.xml.sax.Parser#setLocale
*/
public TransformException (String message, Exception e)
{
super( "TRaX Transform Exception", new LocatorImpl(), e);
}
/**
* Create a new TransformException from a message and a Locator.
*
* <p>This constructor is especially useful when an application is
* creating its own exception from within a DocumentHandler
* callback.</p>
*
* @param message The error or warning message.
* @param locator The locator object for the error or warning.
* @see org.xml.sax.Locator
* @see org.xml.sax.Parser#setLocale
*/
public TransformException (String message, Locator locator)
{
super(message, locator);
}
/**
* Wrap an existing exception in a TransformException.
*
* <p>This constructor is especially useful when an application is
* creating its own exception from within a DocumentHandler
* callback, and needs to wrap an existing exception that is not a
* subclass of SAXException.</p>
*
* @param message The error or warning message, or null to
* use the message from the embedded exception.
* @param locator The locator object for the error or warning.
* @param e Any exception
* @see org.xml.sax.Locator
* @see org.xml.sax.Parser#setLocale
*/
public TransformException (String message, Locator locator,
Exception e)
{
super( message, locator, e);
}
/**
* Create a new TransformException.
*
* <p>This constructor is most useful for parser writers.</p>
*
* <p>If the system identifier is a URL, the parser must resolve it
* fully before creating the exception.</p>
*
* @param message The error or warning message.
* @param publicId The public identifer of the entity that generated
* the error or warning.
* @param systemId The system identifer of the entity that generated
* the error or warning.
* @param lineNumber The line number of the end of the text that
* caused the error or warning.
* @param columnNumber The column number of the end of the text that
* cause the error or warning.
* @see org.xml.sax.Parser#setLocale
*/
public TransformException (String message,
String publicId, String systemId,
int lineNumber, int columnNumber)
{
super(message, publicId, systemId, lineNumber, columnNumber);
}
/**
* Create a new TransformException with an embedded exception.
*
* <p>This constructor is most useful for parser writers who
* need to wrap an exception that is not a subclass of
* SAXException.</p>
*
* <p>If the system identifier is a URL, the parser must resolve it
* fully before creating the exception.</p>
*
* @param message The error or warning message, or null to use
* the message from the embedded exception.
* @param publicId The public identifer of the entity that generated
* the error or warning.
* @param systemId The system identifer of the entity that generated
* the error or warning.
* @param lineNumber The line number of the end of the text that
* caused the error or warning.
* @param columnNumber The column number of the end of the text that
* cause the error or warning.
* @param e Another exception to embed in this one.
* @see org.xml.sax.Parser#setLocale
*/
public TransformException (String message, String publicId, String systemId,
int lineNumber, int columnNumber, Exception e)
{
super(message, publicId, systemId, lineNumber, columnNumber, e);
}
}
1.1 xml-xalan/java/src/trax/Transformer.java
Index: Transformer.java
===================================================================
// Transformations for XML (TRaX)
// Copyright �2000 Lotus Development Corporation, Exoffice Technologies,
// Oracle Corporation, Michael Kay of International Computers Limited, Apache
// Software Foundation. All rights reserved.
package trax;
import org.xml.sax.InputSource;
import org.xml.sax.ErrorHandler;
import org.xml.sax.SAXNotRecognizedException;
import org.xml.sax.SAXNotSupportedException;
import org.xml.sax.XMLFilter;
import org.xml.sax.XMLReader;
import org.xml.sax.DocumentHandler;
import org.xml.sax.ContentHandler;
import org.xml.sax.ext.LexicalHandler;
import org.xml.sax.ext.DeclHandler;
import org.apache.xml.serialize.OutputFormat;
import org.w3c.dom.Node;
/**
* This object represents a Transformer, which is a SAX2 XMLFilter.
* An object of this class can not be used concurrently over multiple threads.
*
* <h3>Open issues:</h3>
* <dl>
* <dt><h4>Separate DOM Interface?</h4></dt>
* <dd>Should there be a separate DOMTransformer class, instead of
* having the transformNode method?</dd>
* <dt><h4>XMLFilter derivation?</h4></dt>
* <dd>There is some question in some people's mind whether or not
* the Transformer interface should extend XMLFilter.</dd>
* <dt><h4>XMLReader vs. Parser vs. SAXParser/DocumentBuilder</h4></dt>
* <dd>Currently the interfaces support XMLReader. Should this be
* javax.xml.parsers.SAXParser/javax.xml.parsers.DocumentBuilder?
* Or, perhaps just org.xml.sax.Parser?</dd>
* <dt><h4>ContentHandler is entitled to expect a well-formed tree</h4></dt>
* <dd>Mike Kay: The output of XSLT is a well-balanced tree, or to put it
* another way, a well-formed external general parsed entity, but it is not in
* general a well-formed XML document. Specifically, it can have multiple
* elements and text nodes as children of the root. It's quite possible to feed
* such a tree into a SAX ContentHandler, but to do so breaks the implicit
* contract that the tree will be well-formed, and I have certainly encountered
* SAX ContentHandlers (or DocumentHandlers) that break if you try to do this
* (FOP is an example). This is one of those awful cases where it's difficult
* to provide the right solution for the 95% of people who want to generate
* well-formed output without falling over in the other 5% of cases. In Saxon
* I've been moving in the direction of allowing the ContentHandler itself to
* declare that it is prepared to accept well-balanced (but ill-formed) input.
* </dd>
* </dl>
*
* @version Alpha
* @author <a href="mailto:scott_boag@lotus.com">Scott Boag</a>
*/
public interface Transformer extends XMLFilter
{
/**
* Process the source tree to SAX parse events.
* @param xmlSource The input for the source tree.
*/
public void transform( InputSource xmlSource)
throws TransformException;
/**
* Process the source tree to the output result.
* @param xmlSource The input for the source tree.
* @param outputTarget The output source target.
*/
public void transform( InputSource xmlSource, Result outputTarget)
throws TransformException;
/**
* Process the source node to the output result, if the
* processor supports the "http://xml.org/trax/features/dom/input"
* feature.
* @param node The input source node, which can be any valid DOM node.
* @param outputTarget The output source target.
*/
public void transformNode( Node node, Result outputTarget)
throws TransformException;
/**
* Process the source node to to SAX parse events, if the
* processor supports the "http://xml.org/trax/features/dom/input"
* feature.
* @param node The input source node, which can be any valid DOM node.
*/
public void transformNode( Node node )
throws TransformException;
/**
* Get a SAX2 ContentHandler for the input.
* @return A valid ContentHandler, which should never be null, as
* long as getFeature("http://xml.org/trax/features/sax/input")
* returns true.
* <h3>Open issues:</h3>
* <dl>
* <dt><h4>ContentHandler vs. ContentHandler</h4></dt>
* <dd>I don't think I would use ContentHandler at all, except that JAXP uses it.
* Maybe we should go back to using ContentHandler?</dd>
* </dl>
*/
ContentHandler getInputContentHandler();
/**
* Get a SAX2 DeclHandler for the input.
* @return A valid DeclHandler, which should never be null, as
* long as getFeature("http://xml.org/trax/features/sax/input")
* returns true.
*/
DeclHandler getInputDeclHandler();
/**
* Get a SAX2 LexicalHandler for the input.
* @return A valid LexicalHandler, which should never be null, as
* long as getFeature("http://xml.org/trax/features/sax/input")
* returns true.
*/
LexicalHandler getInputLexicalHandler();
/**
* Set the output properties for the transformation. These
* properties will override properties set in the templates
* with xsl:output.
*
* @see org.xml.serialize.OutputFormat
*/
void setOutputFormat(OutputFormat oformat);
/**
* Set a parameter for the templates.
* @param name The name of the parameter.
* @param namespace The namespace of the parameter.
* @value The value object. This can be any valid Java object
* -- it's up to the processor to provide the proper
* coersion to the object, or simply pass it on for use
* in extensions.
*/
void setParameter(String name, String namespace, Object value);
/**
* Reset the parameters to a null list.
*/
void resetParameters();
/**
* Set an object that will be used to resolve URIs used in
* document(), etc.
* @param resolver An object that implements the URIResolver interface,
* or null.
*/
void setURIResolver(URIResolver resolver);
/**
* Set an XML parser for the source tree. Note that if
* Transformer.setXMLReader is not called, the parser set
* with Processor.setXMLReader will be used.
*/
public void setXMLReader(XMLReader reader);
/**
* Get the XML parser used for the source tree. Note that
* if Transformer.setXMLReader is not called, the parser set
* with Processor.setXMLReader will be used.
*/
public XMLReader getXMLReader();
}
1.1 xml-xalan/java/src/trax/URIResolver.java
Index: URIResolver.java
===================================================================
// Transformations for XML (TRaX)
// Copyright �2000 Lotus Development Corporation, Exoffice Technologies,
// Oracle Corporation, Michael Kay of International Computers Limited, Apache
// Software Foundation. All rights reserved.
package trax;
import java.io.IOException;
import org.xml.sax.InputSource;
import org.w3c.dom.Node;
/**
* An interface that can be called by the processor to for turning the
* URIs used in document() and xsl:import etc into an InputSource or a
* Node if the processor supports the "http://xml.org/trax/features/dom/input" feature.
*
* <h3>Open issues:</h3>
* <dl>
* <dt><h4>resolveURItoDOMTree</h4></dt>
* <dd>Surely it's the URIResolver that
* knows it wants to supply a DOM node to satisfy the URI, how is the processor
* supposed to know this? Perhaps it would be better to have
* URIResolver.getURItype() which returns "inputSource" or "DOM Node", and the
* processor then calls resolveURI() or resolveURItoNode() as appropriate?
* (It's still not a very pretty design, it doesn't extend nicely to return
* another source of SAX events, e.g. an SQL query).</dd>
* </dl>
*
* @version Alpha
* @author <a href="mailto:scott_boag@lotus.com">Scott Boag</a>
*/
public interface URIResolver
{
/**
* This will be called by the processor when it encounters
* an xsl:include, xsl:import, or document() function.
*
* @param base The base URI that should be used.
* @param uri Value from an xsl:import or xsl:include's href attribute,
* or a URI specified in the document() function.
* @returns a InputSource that can be used to process the resource.
*/
public InputSource resolveURI (String base, String uri)
throws TransformException, IOException;
/**
* This will be called by the processor when it encounters
* an xsl:include, xsl:import, or document() function, if it needs
* a DOM tree.
*
* @param base The base URI that should be used.
* @param uri Value from an xsl:import or xsl:include's href attribute,
* or a URI specified in the document() function.
* @returns a DOM node that represents the resolution of the URI to a tree.
*/
public Node resolveURIToDOMTree (String base, String uri)
throws TransformException, IOException;
}
1.1 xml-xalan/java/src/trax/package.html
Index: package.html
===================================================================
<!-- CVS $Revision: 1.1 $ $Date: 2000/06/20 16:30:17 $ -->
<html>
<title>Transformations for XML (TRaX).</title>
<body>
<p/>
<p>Defines an interface for processing transformation instructions,
performing tree transformations via a transformer, and sending the
result to SAX handlers, and interfacing to a {@link org.xml.serialize.Serializer} if needed.<p>
<dl>
<dt><b>Version: </b></dt><dd>Alpha, 0.5, March 20, 2000</dd>
<dt><b>Author: </b></dt><dd><a href="mailto:scott_boag@lotus.com">Scott Boag</a>
<dd>(with help from Keith Visco, Mike Kay, Oracle, Assaf Arkin, and many others).</dd>
<dt><b>Goals: </b></dt><dd>
<ul>
<li>Define a vendor-neutral and language-neutral interface for tree
transformations that will allow an application to use any implementation.</li>
<li>Support SAX 1, SAX 2, DOM Level 1, and the {@link org.xml.serialize.Serializer} interfaces.</li>
<li>Provide a good model for concurent and optimized transformations.</li>
<li>Provide a reasonable model for incremental processing.</li>
<li>Provide a reasonable model for passing data from the calling application
to the transformation.</li>
</ul>
</dd>
</dl>
<h3>Usage Examples</h3>
<p>See <a href="org/xml/trax/Examples.html#method_detail">Examples Page</a></p>
<h3>The TRaX Interfaces</h3>
<p>A TRaX {@link org.xml.trax.Processor} is an object that processes transformation
instructions, or {@link org.xml.trax.Templates}. The {@link org.xml.trax.Templates} provide
{@link org.xml.trax.Transformer}s, which transforms a source tree into a result tree.</p>
<p>To use the TRaX interface, you create an {@link org.xml.trax.Processor}, which can
provide {@link org.xml.trax.Templates}
from a variety of sources. The {@link org.xml.trax.Templates} object
provides a {@link org.xml.trax.Transformer}. The {@link org.xml.trax.Transformer} processes the
{@link org.xml.sax.InputSource} according to the
{@link org.xml.trax.Templates}, parameters, and
{@link org.xml.serialize.OutputFormat} properties.</p>
<p>To create a {@link org.xml.trax.Processor}, you call the factory interface on
the {@link org.xml.trax.Processor} class. The {@link org.xml.trax.Processor} is
"plugged" into the platform in one of two
ways: 1) as a platform default, and 2) through external specification by a
system property named "org.xml.trax.Processor.[type]"
obtained using java.lang.System.getProperty(). The [type] part of the property specifies
the language to be used, for instance, "org.xml.trax.Processor.xslt" would
specify an XSLT processor.</p>
<p>Both the {@link org.xml.trax.Processor} and the {@link org.xml.trax.Transformer}
objects let you ask about particular features
that the processor supports. You can do this using SAX style getFeature/setFeature
methods. For instance, some processors may not support DOM trees as a method of
input. In this case, it is wise to first ask the {@link org.xml.trax.Transformer}
if it supports the "http://xml.org/trax/features/dom/input" feature.
Those methods that may be optional are clearly documented in the method headers.</p>
<p>The {@link org.xml.trax.Processor}'s primary purpose is to process transformation
instructions, such as
an XSLT stylesheet, into a threadsafe {@link org.xml.trax.Templates} object.
The {@link org.xml.trax.Processor} can get these
instructions from either a SAX {@link org.xml.sax.InputSource}, or from a DOM tree.
The {@link org.xml.trax.Processor}
can also return a list of {@link org.xml.sax.InputSource}s from a XML document
that are specified via
the xml-stylesheet instruction. These {@link org.xml.sax.InputSource}s can
then be handed in to a
process instruction to create a {@link org.xml.trax.Templates} object.</p>
<p>The {@link org.xml.trax.Templates} object is a bag of instructions
that tells the {@link org.xml.trax.Transformer} how to
transform a source tree. It is meant to be thread safe for use in multiple threads
at the same time. At this time there are only two methods on the {@link org.xml.trax.Templates}
object. newTransformer() creates a {@link org.xml.trax.Transformer} object that is
associated with the {@link org.xml.trax.Templates} object. getOutputFormat() allows
you to get a {@link org.xml.serialize.OutputFormat} object which you may then modify
and hand in to the {@link org.xml.trax.Transformer} object.</p>
<p>The {@link org.xml.trax.Transformer} object represents a single transform. You can only
use the Transformer object in a single thread at a time. You can pass parameters to the
{@link org.xml.trax.Transformer} object, which will then be used from within the
transform. You can also set the OutputFormat, which will override the properties
obtained from the owning {@link org.xml.trax.Templates} object. The primary method on
the {@link org.xml.trax.Templates} object is transform(...), which takes as input a
SAX {@link org.xml.sax.InputSource}. But there are a couple of other ways to cause a
transformation to occur. You can use the transformNode(...) method to transform a DOM
node. You can also obtain SAX parse event handler interfaces, such as {@link org.xml.sax.DocumentHandler},
which can then be used as SAX event catchers. A {@link org.xml.trax.Transformer} is
also a SAX {@link org.xml.sax.XMLFilter}. An XML filter is like an XML reader/parser,
except that it obtains its events from another XML reader rather than a primary source like
an XML document or database. Useing the {@link org.xml.trax.Transformer} as a
{@link org.xml.sax.XMLFilter} is one method to use to chain or pipe transformations.
It also allows you to use a {@link org.xml.sax.XMLFilter} polymorphicaly as a
{@link org.xml.sax.XMLReader}.</p>
<p>The output of a transformation is specified via a {@link org.xml.trax.Result} object.
This is very much like a {@link org.xml.sax.InputSource}, except that it allows you
to specify OutputStreams, Writers, or DOM Nodes. To specify SAX output, simply use
the {@link org.xml.sax.XMLReader} methods (since the {@link org.xml.trax.Transformer}
is also a {@link org.xml.sax.XMLReader}), and call the transform() method that takes
only an input source. </p>
<h3>Design Patterns</h3>
<p><img src="org/xml/trax/trax.gif"></p>
<p>For more detailed information on the patterns see the <a href="org\xml\trax\patterns.html">Design Patterns Document</a></p>
<p>For open design issues, see the class and method headers.</p>
</body>
</html>
1.1 xml-xalan/java/src/trax/patterns.xml
Index: patterns.xml
===================================================================
<patterns module="TRaX">
<pattern>
<pattern-name>Processor</pattern-name>
<intent>Serve as a vendor neutral Processor interface for XSLT processors and
similar processors.</intent>
<responsibilities>Serve as a factory for a concrete implementation of
an Processor, serve as a factory for Templates objects, and
manage processor specific features.</responsibilities>
<thread-safety>Processors can not run concurrently.</thread-safety>
</pattern>
<pattern>
<pattern-name>Templates</pattern-name>
<intent>The run time representation of the transformation instructions.</intent>
<responsibilities>Acts as a data bag for transformation instructions, act as
a factory for Transformers.</responsibilities>
<thread-safety>Threadsafe concurrently over multiple threads once
construction is complete.</thread-safety>
</pattern>
<pattern>
<pattern-name>TemplatesBuilder</pattern-name>
<intent>An event handler for parse events that specify the transformation instructions.</intent>
<responsibilities>Handle parse events, and build a Templates object.</responsibilities>
<thread-safety>Only safe one instance per thread.</thread-safety>
</pattern>
<pattern>
<pattern-name>Transformer</pattern-name>
<intent>Act as a per-thread execution context for transformations, act as an interface
for performing the transformation.</intent>
<thread-safety>Only safe one instance per thread.</thread-safety>
<notes>The Transformer is bound to the Templates object that created it.</notes>
</pattern>
<pattern>
<pattern-name>URIResolver</pattern-name>
<intent>An interface that can be called by the processor to for turning the
URIs used in document(), xsl:import, etc. into an InputSource.</intent>
<responsibilities>Returns an InputSource or NodeInputSource,
given a URI.</responsibilities>
<thread-safety>Needs to be threadsafe concurrently over multiple
threads.</thread-safety>
</pattern>
<pattern>
<pattern-name>Result</pattern-name>
<potential-alternate-name>ResultTarget</potential-alternate-name>
<intent>Serve as a single object for multiple types of output, so there can
be simple process method signatures.</intent>
<responsibilities>Act as simple data holder for output stream, DOM node,
ContentHandler, etc.</responsibilities>
<thread-safety>Threadsafe concurrently over multiple threads for read-only,
must be synchronized for edit.</thread-safety>
</pattern>
<pattern>
<pattern-name>NodeInputSource</pattern-name>
<intent>Serve as a single vendor-neutral object for multiple types of
input. Primarily useful as a return for objects that may need to
return DOM nodes, as well as streams, etc.</intent>
<responsibilities>Act as simple data holder for System IDs, DOM nodes,
streams, etc.</responsibilities>
<thread-safety>Threadsafe concurrently over multiple threads for read-only,
must be synchronized for edit.</thread-safety>
</pattern>
<pattern>
<pattern-name>ProcessorException</pattern-name>
<intent>Need specific processor exception that can be caught by a catch
clause.</intent>
<responsibilities>Same as for SAXException.</responsibilities>
<thread-safety>Instance per thread.</thread-safety>
</pattern>
<pattern>
<pattern-name>ProcessorFactoryException</pattern-name>
<intent>Need specific processor factory exception that can be caught by a catch
clause.</intent>
<responsibilities>Same as for SAXException.</responsibilities>
<thread-safety>Instance per thread.</thread-safety>
</pattern>
<pattern>
<pattern-name>TransformException</pattern-name>
<intent>Need specific transform exception that can be caught by a catch
clause.</intent>
<responsibilities>Same as for SAXException.</responsibilities>
<thread-safety>Instance per thread.</thread-safety>
</pattern>
</patterns>
1.1 xml-xalan/java/src/trax/patterns.xsl
Index: patterns.xsl
===================================================================
<?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:output method="html"/>
<xsl:template match="patterns">
<HTML>
<TITLE>Design Patterns: <xsl:value-of select="@module"/></TITLE>
<BODY>
<H1>Design Patterns: <xsl:value-of select="@module"/></H1>
<img src="trax.gif"/>
<xsl:for-each select="pattern">
<HR/>
<xsl:for-each select="pattern-name">
<H2><xsl:value-of select="."/></H2>
</xsl:for-each>
<DL>
<xsl:apply-templates select="*"/>
</DL>
</xsl:for-each>
</BODY>
</HTML>
</xsl:template>
<xsl:template match="pattern-name"/>
<xsl:template match="intent">
<DT>Intent</DT>
<DD><xsl:value-of select="."/></DD>
</xsl:template>
<xsl:template match="responsibilities">
<DT>Responsibilities</DT>
<DD><xsl:value-of select="."/></DD>
</xsl:template>
<xsl:template match="thread-safety">
<DT>Thread-safety</DT>
<DD><xsl:value-of select="."/></DD>
</xsl:template>
<xsl:template match="*">
<DT><xsl:value-of select="name(.)"/></DT>
<DD><xsl:value-of select="."/></DD>
</xsl:template>
</xsl:stylesheet>
1.1 xml-xalan/java/src/trax/trax.dfPackage
Index: trax.dfPackage
===================================================================
package iddj4c6wt02wac6wt9uel;
/**
@version 2.0
@physicalPackage
@__modelType diagram
*/
class diagram {
}/**
@__tags
@shapeType ClassDiagram
*/
class __tags {
}/**
@__options
*/
class __options {
}/**
@__positions
*/
class __positions {
}
1.1 xml-xalan/java/src/trax/trax.properties
Index: trax.properties
===================================================================
#
# $Revision: 1.1 $ $Date: 2000/06/20 16:30:18 $
#
# Note: This properties file is provided for illustrative purposes
# only and is not part of the interface definition.
# This properties file is located in the implementation JAR
# and different implementations will specify different
# implementation classes and output methods.
#
#
# Lis the methods supported by this implementation
#
serialize.methods=xml,html,xhtml,text,wml:wml
#
# Use the Xalan serializer implementation for the default XSLT processor
#
trax.processor.xslt=org.apache.xalan.processor.StylesheetProcessor