| ============================================================ |
| README FILE FOR THE SUN XSLT COMPILER API |
| Preview Version 5 |
| February, 2001 |
| ============================================================ |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| ============================================================ |
| |
| The Sun XSLT Compiler (XSLTC) is a Java-based tool for |
| compiling XSL stylesheets into extremely lightweight and |
| portable Java byte code. The Sun XSLTC Java Runtime environment |
| can then process XML files against these compiled stylesheets |
| (Translets) to generate any manner of output per the style- |
| sheet instructions. |
| |
| CONTENTS OF THIS DOCUMENT: |
| 1. HOW TO INCLUDE TRANSLETS IN YOUR APPLICATIONS |
| 2. FULL CODE EXAMPLE 1, (uses a SAX DocumentHandler). |
| 3. COMPILING AND RUNNING THE EXAMPLE |
| 4. FULL CODE EXAMPLE 2, (uses DefaultSAXOutputHandler). |
| 5. APPENDIX (TextOut and DefaultSAXOutputHandler) |
| |
| |
| |
| |
| 1. HOW TO INCLUDE TRANSLETS IN YOUR APPLICATIONS |
| --------------------------------------------------------------------- |
| |
| Translets implement the interface com.sun.xslt.Translet |
| that you will find in the src directory. |
| |
| public interface Translet { |
| public void transform(DOM document, TransletOutputHandler handler) |
| throws TransletException; |
| |
| public void transform(DOM document, TransletOutputHandler[] handlers) |
| throws TransletException; |
| |
| public void transform(DOM document, NodeIterator iterator, |
| TransletOutputHandler handler) throws |
| TransletException; |
| |
| public Object addParameter(String name, Object value); |
| |
| public void buildKeys(DOM document, NodeIterator iterator, |
| TransletOutputHandler handler, int root) throws |
| TransletException; |
| |
| public String getOutputEncoding(); |
| } |
| |
| The Translet takes a DOMImpl object (created from an input XML document), |
| as input and transforms it. The results of the transformation are |
| sent to an event-based output handler that implements the |
| com.sun.xslt.TransletOutputHandler interface : |
| |
| |
| public interface com.sun.xslt.TransletOutputHandler { |
| public void startDocument() throws TransletException; |
| public void endDocument() throws TransletException; |
| public void characters(char[] characters, int offset, int length) |
| throws TransletException; |
| public void startElement(String elementName) throws TransletException; |
| public void endElement(String elementName) throws TransletException; |
| public void attribute(String attributeName, String attributeValue) |
| throws TransletException; |
| public void comment(String comment) throws TransletException; |
| public void processingInstruction(String target, String data) |
| throws TransletException; |
| public void setType(int type); |
| public void setIndent(boolean indent); |
| public boolean setEscaping(boolean escape) throws TransletException; |
| public void insertCdataElement(String elementName); |
| } |
| |
| |
| You create an instance of the class that implements the Translet interface |
| using Java reflection: |
| |
| Class clazz = Class.forName("classname"); |
| Translet translet = (Translet) clazz.newInstance(); |
| |
| where "classname" is the name of the class generated by XSLTC. |
| In order to execute a transformation, both a document and a SAX-like |
| handler (TransletOutputHandler) are needed. |
| A document instance can be created with the aid of SAX-complaint XML parser. |
| For example, using Sun's parser you would write, |
| |
| import com.sun.xslt.dom.DOMImpl; |
| import com.sun.xml.parser.Parser; |
| import com.sun.xml.parser.Resolver; |
| |
| // Create new instances of DOM and Parser |
| DOMImpl dom = new DOMImpl(); |
| Parser parser = new Parser(); |
| |
| // Set a SAX handler to build a DOM tree |
| parser.setDocumentHandler(dom.getBuilder()); |
| |
| // Parse the document and build a DOM tree |
| InputSource input = new InputSource( |
| new FileReader("xmlfile.xml")); |
| parser.parse(input); |
| |
| In this example a document is parsed from a file, but it is also |
| possible to parse a document from a URI by writing, |
| |
| parser.parse("http://.../xmlfile.xml"); |
| |
| To transform the input XML document, a call is made to the translet's |
| transform() method. In order to do its work, the transform() method |
| takes two arguments, (1) the DOMImpl object created from parsing |
| the input XML document, and (2) an output handler. The output handler |
| must implement the org.xml.sax.DocumentHandler interface. You |
| have the option of: (1) writing your own class that implements |
| DocumentHandler, or (2) using our default class |
| 'com.sun.xslt.runtime.DefaultSAXOutputHandler' instead. |
| The source code for our DefaultSAXOutputHandler is included |
| in this package in the com/sun/xslt/runtime directory. |
| This is a change from the previous releases of |
| our compiler API. If you wanted to create your own |
| output handler in previous releases, you would have write a class that |
| implemented the interface TransletOutputHandler. This change was made |
| so that users could more easily plug in any SAX compliant output |
| handler. To plug in the SAX compliant output handler, |
| (whether it is a user written class or our DefaultSAXOutputHandler) |
| into the transform() method, it must be wrapped in a |
| TextOutput object first. |
| |
| The Translet.transform() method may also take an array of output handlers. |
| In this case the transformation will be able to select which handler |
| to send output to by using the extension element <translet:output port="n"> |
| where 'n' is a 0-based index in the array of output handlers. |
| |
| Lets take a look at the code needed to carry out both of the options |
| for passing the SAX output handler to the translet's transform() method: |
| |
| (1) You would write your own output handler that implements |
| the org.xml.sax.DocumentHandler interface, pass this class |
| into our com.sun.xslt.runtime.TextOutput class which itself |
| implements the TransletOutputHandler interface. |
| |
| (2) You would create an instance of the default SAX output handler, |
| com.sun.xslt.runtime.DefaultSAXOutputHandler, pass this |
| instance into our com.sun.xslt.runtime.TextOutput class which |
| itself implements the TransletOutputHandler interface. |
| |
| |
| In option (1), we want to use a SAX compliant output handler that we write |
| ourselves. In this case we create our Handler class, which implements |
| org.xml.sax.DocumentHandler: |
| |
| import org.xml.sax.DocumentHandler; |
| |
| // user supplied SAX Handler: |
| class Handler implements DocumentHandler { |
| public void startDocument() throws SAXException {} |
| |
| public void endDocument() throws SAXException {} |
| |
| public void characters(char[] characters, int offset, int length) |
| throws SAXException |
| { |
| System.out.println(new String(characters, offset, length)); |
| } |
| public void startElement(String elementName, AttributeList attrs) |
| throws SAXException {} |
| public void endElement(String elementName) throws SAXException {} |
| public void setDocumentLocator(Locator loc) {} |
| public void ignorableWhitespace(char[] characters, int offset, int length) |
| throws SAXException {} |
| public void processingInstruction(String target, String data) |
| throws SAXException {} |
| } |
| |
| Now before we pass our handler to the transform() method, we wrap it |
| in a TextOutput object (which implements the TransletOutputHandler |
| interface for us). Then given the instantiated translet class, |
| the transform method could be called as: |
| |
| import com.sun.xslt.runtime.TextOutput; |
| |
| DOMImpl dom; |
| ... |
| Handler saxHandler; |
| TextOutput textOutput; |
| try { |
| saxHandler = new Handler(); |
| textOutput = new TextOutput(saxHandler); |
| translet.transform(dom, textOutput); |
| } catch (TransletException e){ |
| ... |
| } catch (IOException e){ |
| ... |
| } |
| |
| |
| By using the TextOutput wrapper class, one can also control the character |
| encoding. The TextOutput class has an additional constructor that takes |
| the DocumentHandler and a String that describes the encoding, for example |
| 'textOutput' could have been created as: |
| |
| textOutput = new TextOutput(saxHandler, "utf-8"); |
| |
| Finally, option (2) is much like option (1) except you do not have |
| to write your own DocumentHandler. We provide one by default. To use the |
| default one, instantiate 'com.sun.xslt.runtime.DefaultSAXOutputHandler' |
| rather than instantiating your own class (such as Handler above): |
| |
| import com.sun.xslt.runtime.DefaultSAXOutputHandler; |
| import com.sun.xslt.runtime.TextOutput; |
| |
| DefaultSAXOutputHandler defhandlr; |
| try { |
| defhandlr = new DefaultSAXOutputHandler(System.out, "utf-8"); |
| translet.transform(dom, new TextOutput(defhandlr)); |
| } catch (TransletException e){ |
| ... |
| } catch (IOException e){ |
| ... |
| } |
| |
| For a quick reference to the TextOutput and DefaultSAXOutputHandler |
| constructors available, see the Appendix. |
| |
| In the following sections, full code examples are shown. |
| |
| Finally, if you want the transformation results in the DOM form: |
| |
| DOM result = new DOM(); |
| translet.transform(dom, result.getOutputDomBuilder()); |
| |
| If the compiled stylesheet requires the values of global |
| parameters to be set, you should call addParameter() before |
| calling the transform() method. |
| |
| |
| 2. FULL CODE EXAMPLE 1, XsltApp.java, uses a SAX DocumentHandler. |
| This example corresponds to option (1) in discussion above. |
| ------------------------------------------------------------------ |
| import java.io.FileReader; |
| import java.io.IOException; |
| import com.sun.xslt.dom.DOMImpl; |
| import com.sun.xslt.runtime.TextOutput; |
| import com.sun.xslt.Translet; |
| import com.sun.xslt.TransletException; |
| import com.sun.xml.parser.Parser; |
| import org.xml.sax.AttributeList; |
| import org.xml.sax.DocumentHandler; |
| import org.xml.sax.InputSource; |
| import org.xml.sax.Locator; |
| import org.xml.sax.SAXException; |
| |
| |
| // Create a SAX Output Handler |
| class Handler implements DocumentHandler { |
| public void startDocument() throws SAXException {} |
| |
| public void endDocument() throws SAXException {} |
| |
| public void characters(char[] characters, int offset, int length) |
| throws SAXException |
| { |
| System.out.println(new String(characters, offset, length)); |
| } |
| |
| public void startElement(String elementName, AttributeList attrs) |
| throws SAXException {} |
| |
| public void endElement(String elementName) throws SAXException {} |
| |
| public void setDocumentLocator(Locator loc) {} |
| |
| public void ignorableWhitespace(char[] characters, int offset, int length) |
| throws SAXException {} |
| |
| public void processingInstruction(String target, String data) |
| throws SAXException {} |
| |
| } |
| |
| public class XsltApp { |
| public static void main(String[] args){ |
| XsltApp app = new XsltApp(); |
| app.run(args); |
| } |
| |
| public void run(String[] args){ |
| if(args.length != 2){ |
| usage(); |
| } |
| String inputFileName = args[0]; |
| String transletName = args[1]; |
| |
| DOMImpl dom = new DOMImpl(); |
| Parser parser = new Parser(); |
| parser.setDocumentHandler(dom.getBuilder()); |
| InputSource input = null; |
| try { |
| input = new InputSource(new FileReader(inputFileName)); |
| } catch( java.io.FileNotFoundException e){ |
| System.err.println("File " + inputFileName + " not found"); |
| System.exit(1); |
| } |
| |
| try { |
| parser.parse(input); |
| } catch (org.xml.sax.SAXException e){ |
| System.err.println("Error: " + e); |
| System.exit(1); |
| } catch (IOException e){ |
| System.err.println("Error: " + e); |
| System.exit(1); |
| } |
| |
| Class transletPluggable = null; |
| try { |
| transletPluggable = Class.forName(transletName); |
| } catch (java.lang.ClassNotFoundException e){ |
| System.err.println("Error: " + e); |
| System.exit(1); |
| } |
| |
| Translet translet = null; |
| try { |
| translet = (Translet)transletPluggable.newInstance(); |
| } catch (java.lang.Exception e){ |
| System.err.println("Error instantiating pluggable translet"); |
| System.exit(1); |
| } |
| |
| Handler saxHandler; |
| TextOutput textOutput; |
| try { |
| saxHandler = new Handler(); |
| textOutput = new TextOutput(saxHandler, "utf-8"); |
| translet.transform(dom, textOutput); |
| } catch (TransletException e){ |
| System.err.println("Error: " + e); |
| System.exit(1); |
| } catch (IOException e){ |
| System.err.println("Error: " + e); |
| System.exit(1); |
| } |
| } |
| |
| public void usage(){ |
| System.out.println("Usage: \n" + |
| " xsltapp <xml_file> <translet_name>\n\n" + |
| " where <file> is xml source (e.g. play.xml). \n" + |
| " and <translet_name> is java class (e.g. play1). \n" |
| ); |
| System.exit(1); |
| } |
| } |
| |
| |
| |
| 3. COMPILING AND RUNNING THE EXAMPLE: |
| --------------------------------------------------------------------- |
| |
| To compile the example above, assuming you unpacked the code |
| into the directory /tmp: |
| |
| javac -classpath "/tmp/xsltc/lib/xml.jar:/tmp/xsltc/lib/BCEL.jar:/tmp/xsltc |
| /lib/xsltcrt.jar" XsltApp.java |
| |
| To run the example on xml document 'play.xml' and stylesheet 'play1.xsl': |
| |
| (1) compile the stylesheet: |
| xsltc play1.xsl |
| |
| this will produce the translet 'play1.class'. |
| |
| (2) run the translet with the XsltApp demo: |
| |
| java -classpath /tmp/xsltc/lib/xsltcrt.jar:/tmp/xsltc/lib/xml.jar:. XsltApp play |
| .xml play1 |
| |
| |
| |
| 4. FULL CODE EXAMPLE 2, DefaultRun.java |
| This example corresponds to option (2) in the discussion above. |
| ------------------------------------------------------------------ |
| See the source file for the class 'com.sun.xslt.runtime.DefaultRun', |
| which is included in the src directory. It uses the |
| 'DefaultSAXOutputHandler' approach. |
| |
| |
| |
| |
| 5. APPENDIX |
| ------------------------------------------------------------------ |
| |
| TextOutput |
| ---------- |
| |
| package com.sun.xslt.runtime; |
| |
| public final class TextOutput implements TransletOutputHandler { |
| public TextOutput(DocumentHandler handler) throws IOException; |
| public TextOutput(DocumentHandler handler, String encoding) throws |
| IOException; |
| } |
| |
| |
| DefaultSAXOutputHandler |
| ----------------------- |
| package com.sun.xslt.runtime; |
| |
| public class DefaultSAXOutputHandler implements DocumentHandler{ |
| public DefaultSAXOutputHandler(Writer writer) throws IOException; |
| public DefaultSAXOutputHandler(OutputStream out, String encoding) |
| throws IOException; |
| public DefaultSAXOutputHandler(String filename, String encoding) |
| throws IOException; |
| ... |
| } |
| |
| |
| |
| ------------------------------------------------------------ |
| END OF README |