Java JAXP and XSL Transformations (XSLT), Getting Started

Baldwin provides a brief review of XSL Transformations, shows you how to create and use an identity Transformer object to display a DOM tree on the screen and write it into an output XML file, and how to write exception handlers that provide meaningful information in the event of parser errors and exceptions.

Published:  November 18, 2003
By Richard G. Baldwin

Java Programming Notes # 2202

• Preface
• General Background Information on XSLT
• Preview
• Discussion and Sample Code
• Run the Program
• Summary
• What's Next?
• Complete Program Listings

What is JAXP?

As the name implies, the Java API for XML Processing (JAXP) is an API designed to help you write programs for processing XML documents.  JAXP is very important for many reasons, not the least of which is the fact that it is a critical part of the Java Web Services Developer Pack (Java WSDP).

This is the second lesson in a series designed to initially help you understand how to use JAXP, and to eventually help you understand how to use the Java WSDP.

The first lesson was entitled Java API for XML Processing (JAXP), Getting Started.

What is XML?

Viewing tip

You may find it useful to open another copy of this lesson in a separate browser window.  That will make it easier for you to scroll back and forth among the different listings and figures while you are reading about them.

Supplementary material

I recommend that you also study the other lessons in my extensive collection of online Java tutorials.  You will find those lessons published at Gamelan.com.  However, as of the date of this writing, Gamelan doesn't maintain a consolidated index of my Java tutorial lessons, and sometimes they are difficult to locate there.  You will find a consolidated index at www.DickBaldwin.com.

General Background Information on XSLT

Rendering XML documents

As of this writing, to my knowledge, Microsoft IE is the only widely-used web browser that has the ability to do a good job of rendering XML documents.  IE can render XML documents using either Cascading Style Sheets (CSS) or XSL.  Thus, IE provides a good vehicle for testing XSLT files that you intend to use with JAXP.

For purposes of this lesson, the W3C is a governing body that has published many important documents on XSL and XSLT, two of which will be referenced later in this document.

According to the W3C, XSL is a language for expressing stylesheets. It consists of two parts:

1. A language for transforming XML documents, and
2. An XML vocabulary for specifying formatting semantics.

Again, according to the W3C,

"An XSL stylesheet specifies the presentation of a class of XML documents by describing how an instance of the class is transformed into an XML document that uses the formatting vocabulary."

Separating content from presentation

As you are probably aware by now, one of the primary virtues of XML is the ability to separate content from presentation.

In other words, an XML document contains structured information, but does not provide any hints as to how that information should be rendered for the benefit of a consumer.

According to the W3C, 

"This specification defines the syntax and semantics of XSLT, which is a language for transforming XML documents into other XML documents.

XSLT is designed for use as part of XSL, which is a stylesheet language for XML. In addition to XSLT, XSL
includes an XML vocabulary for specifying formatting. XSL specifies the styling of an XML document by using XSLT to describe how the document is transformed into another XML document that uses the formatting vocabulary.

XSLT is also designed to be used independently of XSL. However, XSLT is not intended as a completely general-purpose XML transformation language. Rather it is designed primarily for the kinds of transformations that are needed when XSLT is used as part of XSL."

Transforming XML to other formats

Because an HTML document can be represented as an XML document, XSLT can be used to transform XML documents into HTML documents.  This makes it possible to render the information contained in an XML document using a common HTML Web browser.  Thus, one useful way to view the contents of an XML document is to transform it into an HTML document and view it using a standard Web browser.

Where does the transformation take place?

When transforming information from an XML document for rendering on an HTML browser, the transformation can take place anywhere between the XML document and the browser.

Transforming on the server

For example, an XSLT engine could be written in Java and run as a servlet, or it could be written as a JavaBeans component and accessed from a scriptlet in a JavaServer page (JSP).

Transforming at the browser

Or, the transformation could be performed at the browser.  For example, Microsoft IE can be used for this purpose.

Preview

A tree structure in memory

As you learned in the previous lesson, a DOM parser can be used to create a tree structure in memory that represents an XML document.  In Java, that tree structure is encapsulated in an object of the interface type Document.  Document and its superinterface Node declare numerous methods.  As is always the case, classes that implement Document must provide concrete definitions of those methods.

Many operations are possible

Thus, given an object of type Document, there are many methods that can be invoked on the object to perform a variety of operations.  For example, it is possible to move nodes from one location in the tree to another location in the tree, thus rearranging the structure of the XML document represented by the Document object.  It is also possible to delete nodes, and to insert new nodes.  As you saw in the sample program in the previous lesson, it is also possible to recursively traverse the tree, extracting information about the nodes along the way.

I showed you ...

In the previous lesson, I showed you how to:

• Use JAXP, DOM, and an input XML file to create a Document object that represents the XML file.
• Recursively traverse the DOM tree, gathering information about each node in the tree along the way.
• Use the information about the nodes to create a new XML file that represents the Document object.

The things that you learned in the previous lesson about traversing the tree structure and gathering information about each node in the tree will serve you well in the future.  However, if all you need to do is to write an output XML file that represents a DOM tree, there is an easier way to do that using XSLT.  That is the primary topic of this lesson.

Nothing fancy intended

The sample program that I will explain in this lesson is not intended to do anything fancy.  It is intended simply to introduce you to the use of XSLT to transform DOM objects in Java programs.

(You could, of course, use the program to operate on other XML files of your own design.)

• Create a Document object using JAXP, DOM, and an input XML file.
• Create an identity XSL Transformer object.
• Use the identity Transformer object to display the XML represented by the Document object on the Standard Output Device.
• Use the identity Transformer object to write the XML represented by the Document object into an output file.
• Provide meaningful output in the case of a parser error.

public class Xslt01{ public static void main(String argv[]){ if (argv.length != 2){ System.err.println( "usage: java Xslt01 fileIn fileOut"); System.exit(0); }//end if Listing 1

1. Create a DocumentBuilderFactory object
2. Use the DocumentBuilderFactory object to create a DocumentBuilder object
3. Use the parse method of the DocumentBuilder object to create a Document object

try{ DocumentBuilderFactory docBuildFactory = DocumentBuilderFactory.newInstance(); DocumentBuilder parser = docBuildFactory.newDocumentBuilder(); Document document = parser.parse( new File(argv[0])); Listing 2

"Defines a factory API that enables applications to obtain a parser that produces DOM object trees from XML documents."

"Defines the API to obtain DOM Document instances from an XML document."

(In Listing 2, the parse method is passed a reference to a File object that represents the input XML file.)

(The reference is returned as type Document, not as the name of the class from which the object was actually instantiated.   Because Document extends Node, that object could also be treated as type Node when appropriate.)

"The Document interface represents the entire HTML or XML document. Conceptually, it is the root of the document tree, and provides the primary access to the document's data."

1. Create a TransformerFactory object by invoking the static newInstance method of the TransformerFactory class.
2. Invoke the newTransformer method on the TransformerFactory object.

//Get a TransformerFactory object TransformerFactory xformFactory = TransformerFactory.newInstance(); //Get an XSL Transformer object Transformer transformer = xformFactory.newTransformer(); Listing 3

(This lesson does not discuss Templates objects.  That is a topic for a future lesson.)

"An instance of this abstract class can transform a source tree into a result tree.

An instance of this class can be obtained with the TransformerFactory.newTransformer method. This instance may then be used to process XML from a variety of sources and write the transformation output to a variety of sinks."

public abstract void transform(
                           Source xmlSource,
                           Result outputTarget)
                    throws TransformerException

Process the source tree to the output result. 

Parameters:
xmlSource - The input for the source tree.
outputTarget - The output target.

Figure 1

1. A reference to an object of type Source
2. A reference to an object of type Result

"An object that implements this interface contains the information needed to act as source input (XML source or transformation instructions)."

(Note that the reference to transformation instructions in the above quotation is a reference to the input parameter to the second overloaded version of the newTransformer method discussed earlier.  Again, I will show you how to use this version in a future lesson.)

"Acts as a holder for a transformation Source tree in the form of a Document Object Model (DOM) tree."

"An object that implements this interface contains the information needed to build a transformation result tree."

• A StreamResult object that points to the Standard Output Device (typically the screen).
• A StreamResult object that points to the output file.

"Acts as an holder for a transformation result, which may be XML, plain Text, HTML, or some other form of markup."

DOMSource source = new DOMSource(document); Listing 4

StreamResult scrResult = new StreamResult(System.out); Listing 5

transformer.transform(source, scrResult); Listing 6

<?xml version="1.0" encoding="UTF-8"?>
<bookOfPoems>
  <poem PoemNumber="1" DumAtr="dum val">
    <line>Roses are red,</line>
    <line>Violets are blue.</line>
    <line>Sugar is sweet,</line>
    <line>and so are you.</line>
  </poem>
  <?processor ProcInstr="Dummy"?>
  <!--Comment-->
  <poem PoemNumber="2" DumAtr="dum val">
    <line>Roses are pink,</line>
    <line>Dandelions are yellow,</line>
    <line>If you like Java,</line>
    <line>You are a good fellow.</line>
  </poem>
</bookOfPoems>

Figure 2

(Recall that in the previous lesson, I used a separate statement to write the XML declaration into the output file before beginning the process of writing data in the output file based on data in the DOM tree.)

1. Get an output stream for the output XML file.
2. Get a StreamResult object that points to the output file.
3. Transform the DOMSource object to text in the output file.

PrintWriter outStream = new PrintWriter( new FileOutputStream(argv[1])); StreamResult fileResult = new StreamResult(outStream); transformer.transform(source, fileResult); }//end try block Listing 7

<?xml version="1.0" encoding="UTF-8"?>
<bookOfPoems>
  <poem PoemNumber="1" DumAtr="dum val">
    <line>Roses are red,</line>
    <line>Violets are blue.</line>
    <line>Sugar is sweet,</line>
    <line>and so are you.</line>
  </poem>
  <?processor ProcInstr="Dummy"?>
  <!--Comment-->
  <poem PoemNumber="2" DumAtr="dum val">
    <line>Roses are pink,</line>
    <line>Dandelions are yellow,</line>
    <line>If you like Java,</line>
    <line>You are a good fellow.</line>
  </poem>
</bookOfPoems>

Figure 3

• parser.parse(new File(argv[0]) throws SAXException if any parse errors occur.
• docBuildFactory.newDocumentBuilder() throws ParserConfigurationException if a DocumentBuilder cannot be created which satisfies the configuration requested.
• xformFactory.newTransformer() throws TransformerConfigurationException - May throw this during the parse when it is constructing the Templates object and fails.
• transformer.transform(source, scrResult) throws TransformerException if an unrecoverable error occurs during the course of the transformation.
• transformer.transform(source, fileResult) throws TransformerException if an unrecoverable error occurs during the course of the transformation.
• TransformerFactory.newInstance() throws TransformerFactoryConfigurationError if the implementation is not available or cannot be instantiated.
• DocumentBuilderFactory.newInstance() throws FactoryConfigurationError if the implementation is not available or cannot be instantiated. 

(A general Exception catch block is provided to handle those errors and exceptions for which specific catch blocks are not provided.)

"Encapsulate a general SAX error or warning. ... This class can contain basic error or warning information from either the XML parser or the application: a parser writer or application writer can subclass it to provide additional functionality. SAX handlers may throw this exception or any exception subclassed from it.

If the application needs to pass through other types of exceptions, it must wrap those exceptions in a SAXException or an exception derived from a SAXException.

If the parser or application needs to include information about a specific location in an XML document, it should use the SAXParseException subclass."

"Encapsulate an XML parse error or warning. ... This exception will include information for locating the error in the original XML document."

catch(SAXParseException saxEx){ System.err.println("\nSAXParseException"); System.err.println("Public ID: " + saxEx.getPublicId()); System.err.println("System ID: " + saxEx.getSystemId()); System.err.println("Line: " + saxEx.getLineNumber()); System.err.println("Column:" + saxEx.getColumnNumber()); System.err.println(saxEx.getMessage()); Exception ex = saxEx; if(saxEx.getException() != null){ ex = saxEx.getException(); System.err.println(ex.getMessage());} }//end catch Listing 8

SAXParseException
Public ID: null
System ID: file:C:/jnk/Xslt01bad.xml
Line: 7
Column:-1
Next character must be ">" terminating 
element "line".

Figure 4

(My interpretation of this situation is that the parser considered the error to be before the first character in line 7 instead of at the end of line 6.  The error because apparent to the parser when it encountered the left angle bracket for a new start tag without the previous end tag having been properly terminated with a right angle bracket.)

Figure 5 Parsing error as per Internet Explorer

I encourage you to copy the code and XML data from Listings 9, 10, and 11 into your text editor.  Compile the program and execute it.  Experiment with it, making changes, and observing the results of your changes.

Summary

In this second lesson on Java JAXP, I began by providing a brief review of XSL and XSL Transformations (XSLT).

Then I showed you how to create an identity Transformer object, and how to use that object to:

• Display a DOM tree structure on the screen in XML format.
• Write the contents of a DOM tree structure into an output XML file.

Following that, I showed you how to write exception handlers that provide meaningful information in the event of errors and exceptions, with particular emphasis on parser errors and exceptions.

What's Next?

In the next lesson, I will show you how to write a program to display a DOM tree on the screen in a format that is much easier to interpret than raw XML code.

/*File Xslt01.java Copyright 2003 R.G.Baldwin This is a modification of the program named Dom02.java that was discussed in an earlier lesson. The program was modified to use an identity XSLT transform to format the output XML file in place of a call to Dom02Writer. This results in a much simpler program. The program was also modified to display the output XML on the Standard Output Device. The program was also modified to provide meaningful output in the event of an error. This program shows you how to: 1. Create a Document object using JAXP, DOM, and an input XML file. 2. Create an identity XSL Transformer object. 3. Use the identity XSL Transformer object to display the XML represented by the Document object on the Standard Output Device. 3. Use the identity XSL Transformer object to write the XML represented by the Document object into an output file. The input XML file name is provided by the user as the first command-line argument. The output XML file name is provided by the user as the second command-line argument. The program instantiates a DOM parser object based on JAXP. The parser is configured in the default non-validating configuration. The program uses the parse() method of the parser object to parse an XML file specified on the command line. The parse method returns an object of type Document that represents the parsed XML file. Then the program gets a TransformerFactory object and uses that object to get a default identity Transformer object capable of performing a copy of the source to the result. Then the program uses the Document object to get a DOMSource object that acts as a holder for a transformation Source tree in the form of a Document Object Model (DOM) tree. Then the program gets a StreamResult object that points to the standard output device. This object acts as a holder for a transformation result. Then the program uses the Transformer object, the DOMSource object, and the StreamResult object to transform the DOM tree to text and display it on the standard output device. Then the program gets another StreamResult object that points to an output file, transforms the DOM tree to text, and writes it into the output file. The program catches a variety of different types of errors and exceptions and provides meaningful output in the event of an error or exception. Tested using SDK 1.4.2 and WinXP with two differentan XML files. The XML file named Xslt01.xml is well formed, and reads as follows: <?xml version="1.0"?> <bookOfPoems> <poem PoemNumber="1" DumAtr="dum val"> <line>Roses are red,</line> <line>Violets are blue.</line> <line>Sugar is sweet,</line> <line>and so are you.</line> </poem> <?processor ProcInstr="Dummy"?> <!--Comment--> <poem PoemNumber="2" DumAtr="dum val"> <line>Roses are pink,</line> <line>Dandelions are yellow,</line> <line>If you like Java,</line> <line>You are a good fellow.</line> </poem> </bookOfPoems> The XML file named Xslt01bad.xml is not well formed and reads as follows: <?xml version="1.0"?> <bookOfPoems> <poem PoemNumber="1" DumAtr="dum val"> <line>Roses are red,</line> <!--Following line missing > --> <line>Violets are blue.</line <line>Sugar is sweet,</line> <line>and so are you.</line> </poem> <?processor ProcInstr="Dummy"?> <!--Comment--> <poem PoemNumber="2" DumAtr="dum val"> <line>Roses are pink,</line> <line>Dandelions are yellow,</line> <line>If you like Java,</line> <line>You are a good fellow.</line> </poem> </bookOfPoems> This file is purposely missing a right angle bracket in the closing tag of a line element, and is used to test for parser errors. When processing the well formed XML file, the program produces the following text on the Standard Output Device: <?xml version="1.0" encoding="UTF-8"?> <bookOfPoems> <poem PoemNumber="1" DumAtr="dum val"> <line>Roses are red,</line> <line>Violets are blue.</line> <line>Sugar is sweet,</line> <line>and so are you.</line> </poem> <?processor ProcInstr="Dummy"?> <!--Comment--> <poem PoemNumber="2" DumAtr="dum val"> <line>Roses are pink,</line> <line>Dandelions are yellow,</line> <line>If you like Java,</line> <line>You are a good fellow.</line> </poem> </bookOfPoems> When processing the well formed XML file, the program produces an output XML file that reads as follows: <?xml version="1.0" encoding="UTF-8"?> <bookOfPoems> <poem PoemNumber="1" DumAtr="dum val"> <line>Roses are red,</line> <line>Violets are blue.</line> <line>Sugar is sweet,</line> <line>and so are you.</line> </poem> <?processor ProcInstr="Dummy"?> <!--Comment--> <poem PoemNumber="2" DumAtr="dum val"> <line>Roses are pink,</line> <line>Dandelions are yellow,</line> <line>If you like Java,</line> <line>You are a good fellow.</line> </poem> </bookOfPoems> When processing the bad XML file, the program aborts with the following error message on the standard error device: SAXParseException Public ID: null System ID: file:C:/jnk/Xslt01bad.xml Line: 7 Column:-1 Next character must be ">" terminating element "line". Note that I manually inserted line breaks into the error message above to force it to fit into this narrow publication format. ************************************************/ import javax.xml.parsers.DocumentBuilderFactory; import javax.xml.parsers.DocumentBuilder; import org.w3c.dom.Document; import javax.xml.parsers.FactoryConfigurationError; import javax.xml.parsers.ParserConfigurationException; import org.xml.sax.SAXException; import org.xml.sax.SAXParseException; import javax.xml.transform.Transformer; import javax.xml.transform.TransformerFactory; import javax.xml.transform.TransformerException; import javax.xml.transform. TransformerConfigurationException; import javax.xml.transform.dom.DOMSource; import javax.xml.transform.stream.StreamResult; import java.io.File; import java.io.PrintWriter; import java.io.FileOutputStream; public class Xslt01 { public static void main(String argv[]){ if (argv.length != 2){ System.err.println( "usage: java Xslt01 fileIn fileOut"); System.exit(0); }//end if try{ //Get a factory object for DocumentBuilder // objects with default configuration. DocumentBuilderFactory docBuildFactory = DocumentBuilderFactory.newInstance(); //Get a DocumentBuilder (parser) object DocumentBuilder parser = docBuildFactory.newDocumentBuilder(); //Parse the XML input file to create a // Document object that represents the // input XML file. Document document = parser.parse( new File(argv[0])); //Get a TransformerFactory object TransformerFactory xformFactory = TransformerFactory.newInstance(); //Get an XSL Transformer object Transformer transformer = xformFactory.newTransformer(); //Get a DOMSource object that represents // the Document object DOMSource source = new DOMSource(document); //Get a StreamResult object that points to // the screen. Then transform the DOM // sending XML to the screen. StreamResult scrResult = new StreamResult(System.out); transformer.transform(source, scrResult); //Get an output stream for the output XML // file. PrintWriter outStream = new PrintWriter( new FileOutputStream(argv[1])); //Get a StreamResult object that points to // the output file. Then transform the DOM // sending XML to to the file StreamResult fileResult = new StreamResult(outStream); transformer.transform(source, fileResult); }//end try block catch(SAXParseException saxEx){ System.err.println("\nSAXParseException"); System.err.println("Public ID: " + saxEx.getPublicId()); System.err.println("System ID: " + saxEx.getSystemId()); System.err.println("Line: " + saxEx.getLineNumber()); System.err.println("Column:" + saxEx.getColumnNumber()); System.err.println(saxEx.getMessage()); Exception ex = saxEx; if(saxEx.getException() != null){ ex = saxEx.getException(); System.err.println(ex.getMessage());} }//end catch catch(SAXException saxEx){ //This catch block may not be reachable. System.err.println("\nParser Error"); System.err.println(saxEx.getMessage()); Exception ex = saxEx; if(saxEx.getException() != null){ ex = saxEx.getException(); System.err.println(ex.getMessage());} }//end catch catch(ParserConfigurationException parConEx){ System.err.println( "\nParser Config Error"); System.err.println(parConEx.getMessage()); }//end catch catch(TransformerConfigurationException transConEx){ System.err.println( "\nTransformer Config Error"); System.err.println( transConEx.getMessage()); Throwable ex = transConEx; if(transConEx.getException() != null){ ex = transConEx.getException(); System.err.println(ex.getMessage());} }//end catch catch(TransformerException transEx){ System.err.println( "\nTransformation error"); System.err.println(transEx.getMessage()); Throwable ex = transEx; if(transEx.getException() != null){ ex = transEx.getException(); System.err.println(ex.getMessage());} }//end catch} catch(Exception e){ e.printStackTrace(System.err); }//end catch }// end main() }// class Xslt01 Listing 9

<?xml version="1.0"?> <bookOfPoems> <poem PoemNumber="1" DumAtr="dum val"> <line>Roses are red,</line> <line>Violets are blue.</line> <line>Sugar is sweet,</line> <line>and so are you.</line> </poem> <?processor ProcInstr="Dummy"?> <!--Comment--> <poem PoemNumber="2" DumAtr="dum val"> <line>Roses are pink,</line> <line>Dandelions are yellow,</line> <line>If you like Java,</line> <line>You are a good fellow.</line> </poem> </bookOfPoems> Listing 10

<?xml version="1.0"?> <bookOfPoems> <poem PoemNumber="1" DumAtr="dum val"> <line>Roses are red,</line> <!--Following line missing > --> <line>Violets are blue.</line <line>Sugar is sweet,</line> <line>and so are you.</line> </poem> <?processor ProcInstr="Dummy"?> <!--Comment--> <poem PoemNumber="2" DumAtr="dum val"> <line>Roses are pink,</line> <line>Dandelions are yellow,</line> <line>If you like Java,</line> <line>You are a good fellow.</line> </poem> </bookOfPoems> Listing 11

Copyright 2003, Richard G. Baldwin.  Reproduction in whole or in part in any form or medium without express written permission from Richard Baldwin is prohibited.

About the author

Richard has participated in numerous consulting projects, and he frequently provides onsite training at the high-tech companies located in and around Austin, Texas.  He is the author of Baldwin's Programming Tutorials, which has gained a worldwide following among experienced and aspiring programmers. He has also published articles in JavaPro magazine.

Richard holds an MSEE degree from Southern Methodist University and has many years of experience in the application of computer technology to real-world problems.

Baldwin@DickBaldwin.com

-end-