Appendix B. JAXP API Reference

This appendix summarizes Version 1.1 of the Java API for XML Processing (JAXP).[58] JAXP provides a standard way for Java programs to interact with XML parsers and XSLT processors and is freely available from http://java.sun.com/xml. JAXP also includes classes and interfaces for DOM and SAX; these are not listed here.

[58] Before transformation support was added, JAXP stood for "Java API for XML Parsing."

The biggest changes from JAXP 1.0 to JAXP 1.1 are support for level 2 of DOM and SAX, as well as an entirely new plugability layer for performing transformations. JAXP 1.1 also refines the algorithm used for locating implementation classes for the three supported plugability layers. This algorithm is discussed in Chapter 5, "XSLT Processing with Java", in the "Introduction to JAXP 1.1" section.

Package: javax.xml.parsers

The classes in this package support parsing using Simple API for XML (SAX) 2 and Document Object Model (DOM) Level 2. These classes do not perform the actual parsing work; instead, they delegate to plugable parser implementations such as Apache's Crimson or Xerces.

DocumentBuilder

Instances of this class define an API for parsing XML from a variety of input sources, as well as for creating new DOM Document objects from scratch. The DocumentBuilder instance should be obtained from the DocumentBuilderFactory instance. Once an instance has been obtained, the newDocument( ) method can be used to construct new DOM Document objects without resorting to the implementation of specific code.

public abstract class DocumentBuilder {
    protected DocumentBuilder( );
    public abstract DOMImplementation getDOMImplementation( );
    public abstract boolean isNamespaceAware( );
    public abstract boolean isValidating( );
    public abstract Document newDocument( );
    public Document parse(InputStream is, String systemId)
        throws SAXException, IOException;
    public Document parse(String uri)
        throws SAXException, IOException;
    public Document parse(File f)
        throws SAXException, IOException;
    public abstract Document parse(InputSource is)
        throws SAXException, IOException;
    public Document parse(InputStream is)
        throws SAXException, IOException;
    public abstract void setEntityResolver(EntityResolver er);
    public abstract void setErrorHandler(ErrorHandler eh);
}

DocumentBuilderFactory

This class allows instances of DocumentBuilder to be constructed using a factory pattern, insulating application code from specific DOM implementations. Various methods in this class allow programs to specify which features the parser will support. If these features are not available, the newDocumentBuilder( ) throws a ParserConfigurationException. The various accessor methods, such as isNamespaceAware( ), do not indicate whether the underlying parser actually supports a given feature. Instead, these methods indicate whether the application configured those features on this DocumentBuilderFactory instance. Before using this class, call the newInstance( ) method to create an instance of it. This object is then used to construct an instance of DocumentBuilder using the newDocumentBuilder( ) method.

public abstract class DocumentBuilderFactory {
    protected DocumentBuilderFactory( );
    public abstract Object getAttribute(String name)
        throws IllegalArgumentException;
    public boolean isCoalescing( );
    public boolean isExpandEntityReferences( );
    public boolean isIgnoringComments( );
    public boolean isIgnoringElementContentWhitespace( );
    public boolean isNamespaceAware( );
    public boolean isValidating( );
    public abstract DocumentBuilder newDocumentBuilder( )
        throws ParserConfigurationException;
    public static DocumentBuilderFactory newInstance( );
    public abstract void setAttribute(String name, Object value)
        throws IllegalArgumentException;
    public void setCoalescing(boolean coalescing);
    public void setExpandEntityReferences(boolean expandEntityRef);
    public void setIgnoringComments(boolean ignoreComments);
    public void setIgnoringElementContentWhitespace(boolean whitespace);
    public void setNamespaceAware(boolean awareness);
    public void setValidating(boolean validating);
}

FactoryConfigurationError

This indicates that the class for a parser factory could not be located or instantiated. If this error occurs, something is not installed correctly on the system. Refer to Chapter 5, "XSLT Processing with Java" for information on the algorithm that JAXP uses to locate parser implementations.

public class FactoryConfigurationError
        extends Error {
    public FactoryConfigurationError(String msg);
    public FactoryConfigurationError(Exception e);
    public FactoryConfigurationError(Exception e, String msg);
    public FactoryConfigurationError( );
    public Exception getException( );
    public String getMessage( );
}

ParserConfigurationException

According to the API specification, represents "a serious configuration error." Generally, this means that the factory cannot provide a parser with the requested features. For instance, a programmer may ask for a namespace-aware parser, but the only parser available does not support namespaces.[59]

[59] XSLT processing requires namespace-aware XML parsers.

public class ParserConfigurationException
        extends Exception {
    public ParserConfigurationException(String msg);
    public ParserConfigurationException( );
}

SAXParser

This class defines a wrapper around an underlying SAX parser implementation. It was part of JAXP 1.0 and supports both SAX 1 and SAX 2 features. If possible, programmers should avoid methods that use HandlerBase, because this is a deprecated SAX 1 interface. Instead, use the methods that deal with DefaultHandler.

public abstract class SAXParser {
    protected SAXParser( );
    public abstract Parser getParser( )
        throws SAXException;
    public abstract Object getProperty(String name)
        throws SAXNotRecognizedException, SAXNotSupportedException;
    public abstract XMLReader getXMLReader( )
        throws SAXException;
    public abstract boolean isNamespaceAware( );
    public abstract boolean isValidating( );
    public void parse(InputStream is, DefaultHandler dh, String systemId)
        throws SAXException, IOException;
    public void parse(InputStream is, DefaultHandler p1)
        throws SAXException, IOException;
    public void parse(InputStream is, HandlerBase hb, String systemId)
        throws SAXException, IOException;
    public void parse(File f, HandlerBase hb)
        throws SAXException, IOException;
    public void parse(InputStream is, HandlerBase hb)
        throws SAXException, IOException;
    public void parse(String uri, HandlerBase hb)
        throws SAXException, IOException;
    public void parse(InputSource is, HandlerBase hb)
        throws SAXException, IOException;
    public void parse(InputSource is, DefaultHandler dh)
        throws SAXException, IOException;
    public void parse(String systemId, DefaultHandler dh)
        throws SAXException, IOException;
    public void parse(File f, DefaultHandler dh)
        throws SAXException, IOException;
    public abstract void setProperty(String name, Object value)
        throws SAXNotRecognizedException, SAXNotSupportedException;
}

SAXParserFactory

This class defines a factory for creating instances of SAX parsers. Before creating these instances, use the setFeature( ) method to define which parsing features are required of the parser to be created. See http://www.megginson.com/SAX/Java/features.html for a list of core SAX 2 features.

public abstract class SAXParserFactory {
    protected SAXParserFactory( );
    public abstract boolean getFeature(String name)
        throws ParserConfigurationException, SAXNotRecognizedException,
        SAXNotSupportedException;
    public boolean isNamespaceAware( );
    public boolean isValidating( );
    public static SAXParserFactory newInstance( );
    public abstract SAXParser newSAXParser( )
        throws ParserConfigurationException, SAXException;
    public abstract void setFeature(String name, boolean value)
        throws ParserConfigurationException, SAXNotRecognizedException,
        SAXNotSupportedException;
    public void setNamespaceAware(boolean awareness);
    public void setValidating(boolean validating);
}

Package: javax.xml.transform

This package defines an API for performing transformations. Although these are common XSLT transformations, the API is flexible enough to support other transformation technologies. Like the javax.xml.parsers package, the classes and interfaces in this package hide vendor-specific implementation code. JAXP 1.1 ships with Xalan as its reference implementation for transformations; different processors can be plugged in.

ErrorListener

This interface allows applications to implement custom error handling. If an error listener is not registered, errors are written to System.err. More details on this interface can be found in Chapter 9, "Development Environment, Testing, and Performance".

public interface ErrorListener {
    void error(TransformerException exception)
        throws TransformerException;
    void fatalError(TransformerException exception)
        throws TransformerException;
    void warning(TransformerException exception)
        throws TransformerException;
}

OutputKeys

These are constant definitions for legal output property settings on the Transformer interface. They map directly to the legal attributes for the <xsl:output> element. Programmatically specified output properties take priority over output properties specified in the XSLT stylesheet.

public class OutputKeys {
    public static final String CDATA_SECTION_ELEMENTS = "cdata-section-elements";
    public static final String DOCTYPE_PUBLIC = "doctype-public";
    public static final String DOCTYPE_SYSTEM = "doctype-system";
    public static final String ENCODING = "encoding";
    public static final String INDENT = "indent";
    public static final String MEDIA_TYPE = "media-type";
    public static final String METHOD = "method";
    public static final String OMIT_XML_DECLARATION = "omit-xml-declaration";
    public static final String STANDALONE = "standalone";
    public static final String VERSION = "version";
}

Result

This is a common interface for classes that produce a transformation result. DOMResult, SAXResult, and StreamResult are implementing classes. The two constants in this interface are used when specifying whether output escaping is performed, as discussed in section 16.4 of the XSLT specification at http://www.w3.org/TR/xslt. The system id is optional but can be helpful when displaying error messages or warnings.

public interface Result {
    public static final String PI_DISABLE_OUTPUT_ESCAPING =
        "javax.xml.transform.disable-output-escaping";
    public static final String PI_ENABLE_OUTPUT_ESCAPING =
       "javax.xml.transform.enable-output-escaping";
    String getSystemId( );
    void setSystemId(String systemId);
}

Source

This is a generic interface implemented by DOMSource, SAXSource, and StreamSource. The system id is particularly important for Source because it allows the processor to resolve relative URI references within the XML and XSLT inputs.[60]

[60] URI references are found in elements such as <xsl:import> and <xsl:include>.

public interface Source {
    String getSystemId( );
    void setSystemId(String systemId);
}

SourceLocator

Instances of this interface are useful when reporting locations of error messages and warnings. Application programmers retrieve SourceLocator instances from TransformerException's getLocator( ) method.

public interface SourceLocator {
    int getColumnNumber( );
    int getLineNumber( );
    String getPublicId( );
    String getSystemId( );
}

Templates

These instances represent "compiled" transformation instructions. Whether a particular XSLT processor actually compiles stylesheets is implementation-dependent. However, Templates objects are guaranteed to be thread-safe. This makes them ideal for servlet environments, where it is desirable to parse an XSLT stylesheet once then cache it in memory as a Templates object. The output properties are a read-only representation of the <xsl:output> stylesheet element.

public interface Templates {
    Properties getOutputProperties( );
    Transformer newTransformer( )
        throws TransformerConfigurationException;
}

Transformer

Instances of this class perform one or more transformations. Although Transformer objects can be reused, they are not thread-safe and therefore cannot be used concurrently. Output property names are defined by the OutputKeys class and map to the <xsl:output> stylesheet element. Parameters, on the other hand, are stylesheet parameters and map to top-level <xsl:param> elements. The getParameter() method returns only parameters that have been programmatically set.

public abstract class Transformer {
    protected Transformer( );
    public abstract void clearParameters( );
    public abstract ErrorListener getErrorListener( );
    public abstract Properties getOutputProperties( );
    public abstract String getOutputProperty(String name)
        throws IllegalArgumentException;
    public abstract Object getParameter(String name);
    public abstract URIResolver getURIResolver( );
    public abstract void setErrorListener(ErrorListener listener)
        throws IllegalArgumentException;
    public abstract void setOutputProperties(Properties oformat)
        throws IllegalArgumentException;
    public abstract void setOutputProperty(String name, String value)
        throws IllegalArgumentException;
    public abstract void setParameter(String name, Object value);
    public abstract void setURIResolver(URIResolver resolver);
    public abstract void transform(Source xmlSource, Result outputTarget)
        throws TransformerException;
}

TransformerConfigurationException

This exception indicates a serious problem and may occur when an XSLT stylesheet has syntax errors that prevent instantiation of a Transformer instance. This class can wrap around other exceptions. For example, an underlying parser exception may be wrapped by an instance of this class.

public class TransformerConfigurationException
        extends TransformerException {
    public TransformerConfigurationException(String msg);
    public TransformerConfigurationException(Throwable e);
    public TransformerConfigurationException(String msg, Throwable e);
    public TransformerConfigurationException(String msg, SourceLocator locator);
    public TransformerConfigurationException(String msg, SourceLocator locator,
        Throwable e);
    public TransformerConfigurationException( );
}

TransformerException

This is a general-purpose exception that occurs during transformation. If an ErrorListener is registered, the processor should try to report exceptions there first. Otherwise, exceptions are written to System.err. The quality of error messages varies widely across different XSLT processors. This class can wrap around other exceptions.

public class TransformerException
        extends Exception {
    public TransformerException(String msg, Throwable e);
    public TransformerException(String msg, SourceLocator locator);
    public TransformerException(Throwable e);
    public TransformerException(String msg);
    public TransformerException(String msg, SourceLocator locator, Throwable e);
    public Throwable getCause( );
    public Throwable getException( );
    public String getLocationAsString( );
    public SourceLocator getLocator( );
    public String getMessageAndLocation( );
    public synchronized Throwable initCause(Throwable cause);
    public void printStackTrace(PrintStream ps);
    public void printStackTrace(PrintWriter pw);
    public void printStackTrace( );
    public void setLocator(SourceLocator locator);
}

TransformerFactory

This defines a portable way to access different TransformerFactory instances and is the key abstraction that masks differences between XSLT processors from different vendors.

public abstract class TransformerFactory {
    protected TransformerFactory( );
    public abstract Source getAssociatedStylesheet(Source source, String media,
        String title, String charset) throws TransformerConfigurationException;
    public abstract Object getAttribute(String name)
        throws IllegalArgumentException;
    public abstract ErrorListener getErrorListener( );
    public abstract boolean getFeature(String name);
    public abstract URIResolver getURIResolver( );
    public static TransformerFactory newInstance( )
        throws TransformerFactoryConfigurationError;
    public abstract Templates newTemplates(Source source)
        throws TransformerConfigurationException;
    public abstract Transformer newTransformer(Source source)
        throws TransformerConfigurationException;
    public abstract Transformer newTransformer( )
        throws TransformerConfigurationException;
    public abstract void setAttribute(String name, Object value)
        throws IllegalArgumentException;
    public abstract void setErrorListener(ErrorListener listener)
        throws IllegalArgumentException;
    public abstract void setURIResolver(URIResolver resolver);
}

TransformerFactoryConfigurationError

This error is typically seen when a transformer factory class cannot be instantiated. This is a good indicator of CLASSPATH problems.

public class TransformerFactoryConfigurationError
        extends Error {
    public TransformerFactoryConfigurationError(String msg);
    public TransformerFactoryConfigurationError(Exception e);
    public TransformerFactoryConfigurationError(Exception e, String msg);
    public TransformerFactoryConfigurationError( );
    public Exception getException( );
    public String getMessage( );
}

URIResolver

In most cases, the JAXP provides a URIResolver instance. By creating a custom implementation, however, applications can define how relative URI references in XSLT stylesheets are resolved. For instance, the URIResolver defines how <xsl:include href="header.xslt"/> locates header.xslt.

public interface URIResolver {
    Source resolve(String href, String base)
        throws TransformerException;
}

Package: javax.xml.transform.dom

This package defines how to perform transformations using DOM.

DOMLocator

This interface allows applications to locate the DOM node where an error occurs. Since TransformerException returns instances of SourceLocator, applications must downcast to obtain DOMLocator objects.

public interface DOMLocator
        extends SourceLocator {
    Node getOriginatingNode( );
}

DOMResult

This class allows transformation results to be stored in a DOM tree. If the default constructor is used, the XSLT processor creates a DOM Document node. Otherwise, applications can specify a DOM Document, DocumentFragment, or Element node as the constructor parameter.

The FEATURE constant is used with TransformerFactory.getFeature( ) to determine if the factory supports DOMResult.

public class DOMResult
        implements Result {
    public static final String FEATURE = 
        "http://javax.xml.transform.dom.DOMResult/feature";
    public DOMResult(Node node);
    public DOMResult(Node node, String systemId);
    public DOMResult( );
    public Node getNode( );
    public String getSystemId( );
    public void setNode(Node node);
    public void setSystemId(String systemId);
}

DOMSource

This class allows a DOM tree to be used as an input source. In practice, the node parameter is usually an instance of a DOM Document. However, XSLT processors may also support any other type of DOM Node. The system id is still important for resolving relative URI references.

public class DOMSource
        implements Source {
    public static final String FEATURE =
        "http://javax.xml.transform.dom.DOMSource/feature";
    public DOMSource(Node node);
    public DOMSource(Node node, String systemId);
    public DOMSource( );
    public Node getNode( );
    public String getSystemId( );
    public void setNode(Node node);
    public void setSystemId(String systemId);
}

Package: javax.xml.transform.sax

This package defines how to perform transformations using SAX. Example usages can be found in Chapter 5, "XSLT Processing with Java".

SAXResult

This class makes it possible to emit SAX events as the result of a transformation. The ContentHandler parameter receives these events.

public class SAXResult
        implements Result {
    public static final String FEATURE =
        "http://javax.xml.transform.sax.SAXResult/feature";
    public SAXResult(ContentHandler handler);
    public SAXResult( );
    public ContentHandler getHandler( );
    public LexicalHandler getLexicalHandler( );
    public String getSystemId( );
    public void setHandler(ContentHandler handler);
    public void setLexicalHandler(LexicalHandler handler);
    public void setSystemId(String systemId);
}

SAXSource

This allows output from a SAX parser to be fed into an XSLT processor for transformation. It is also used to build Templates or Transformer objects using TransformerFactory.

public class SAXSource
        implements Source {
    public static final String FEATURE =
        "http://javax.xml.transform.sax.SAXSource/feature";
    public SAXSource(XMLReader reader, InputSource inputSource);
    public SAXSource(InputSource inputSource);
    public SAXSource( );
    public InputSource getInputSource( );
    public String getSystemId( );
    public XMLReader getXMLReader( );
    public void setInputSource(InputSource inputSource);
    public void setSystemId(String systemId);
    public void setXMLReader(XMLReader reader);
    public static InputSource sourceToInputSource(Source source);
}

SAXTransformerFactory

This is a subclass of TransformerFactory that adds SAX-specific methods. To create an instance of this class, create a TransformerFactory instance and downcast if transFact.getFeature(SAXTransformerFactory.FEATURE) returns true.

public abstract class SAXTransformerFactory
        extends TransformerFactory {
    public static final String FEATURE =
        "http://javax.xml.transform.sax.SAXTransformerFactory/feature";
    public static final String FEATURE_XMLFILTER =
        "http://javax.xml.transform.sax.SAXTransformerFactory/feature/xmlfilter";
    protected SAXTransformerFactory( );
    public abstract TemplatesHandler newTemplatesHandler( )
        throws TransformerConfigurationException;
    public abstract TransformerHandler newTransformerHandler(Templates templates)
        throws TransformerConfigurationException;
    public abstract TransformerHandler newTransformerHandler( )
        throws TransformerConfigurationException;
    public abstract TransformerHandler newTransformerHandler(Source src)
        throws TransformerConfigurationException;
    public abstract XMLFilter newXMLFilter(Templates templates)
        throws TransformerConfigurationException;
    public abstract XMLFilter newXMLFilter(Source src)
        throws TransformerConfigurationException;
}

TemplatesHandler

This acts as a SAX 2 ContentHandler, which receives SAX events as a document is parsed. Once parsing is complete, it returns a Templates object. Instances are constructed using SAXTransformerFactory.

public interface TemplatesHandler
        extends ContentHandler {
    String getSystemId( );
    Templates getTemplates( );
    void setSystemId(String systemId);
}

TransformerHandler

Instances of this interface receive SAX events and produce Transformer objects once parsing is complete. Instances are constructed using SAXTransformerFactory.

public interface TransformerHandler
        extends ContentHandler, LexicalHandler, DTDHandler {
    String getSystemId( );
    Transformer getTransformer( );
    void setResult(Result result)
        throws IllegalArgumentException;
    void setSystemId(String systemId);
}

Package: javax.xml.transform.stream

This package defines how to perform transformations using Java I/O streams.

StreamResult

This allows transformation results to be sent to a File, Writer, or OutputStream.

public class StreamResult
        implements Result {
    public static final String FEATURE =
        "http://javax.xml.transform.stream.StreamResult/feature";
    public StreamResult(OutputStream outputStream);
    public StreamResult(Writer writer);
    public StreamResult(String systemId);
    public StreamResult(File f);
    public StreamResult( );
    public OutputStream getOutputStream( );
    public String getSystemId( );
    public Writer getWriter( );
    public void setOutputStream(OutputStream outputStream);
    public void setSystemId(File f);
    public void setSystemId(String systemId);
    public void setWriter(Writer writer);
}

StreamSource

This supports input from a URL, File, Reader, or InputStream. The system id is used to resolve relative URLs in the XML and XSLT.

public class StreamSource
        implements Source {
    public static final String FEATURE = 
        "http://javax.xml.transform.stream.StreamSource/feature";
    public StreamSource(InputStream inputStream);
    public StreamSource(InputStream inputStream, String systemId);
    public StreamSource(Reader reader);
    public StreamSource(Reader reader, String systemId);
    public StreamSource(String systemId);
    public StreamSource(File f);
    public StreamSource( );
    public InputStream getInputStream( );
    public String getPublicId( );
    public Reader getReader( );
    public String getSystemId( );
    public void setInputStream(InputStream inputStream);
    public void setPublicId(String systemId);
    public void setReader(Reader reader);
    public void setSystemId(File f);
    public void setSystemId(String systemId);
}