Book HomeJava and XML, 2nd Edition

A.3. JAXP 1.1

JAXP provides an abstraction layer over the process of getting a vendor's implementation of a SAX or DOM parser, as well as providing transformations in a vendor-neutral way.

A.3.1. Package: javax.xml.parsers

This is the single package used in JAXP, and details the classes needed for the JAXP abstraction and pluggability layer over XML parsing.

A.3.1.1. DocumentBuilder

This class is the wrapper over an underlying parser implementation class. It allows parsing to occur in a vendor-neutral way.

public abstract class DocumentBuilder {
    public Document parse(InputStream stream)
        throws SAXException, IOException, IllegalArgumentException;
    public Document parse(InputStream stream, String systemID)
        throws SAXException, IOException, IllegalArgumentException;
    public Document parse(String uri)
        throws SAXException, IOException, IllegalArgumentException;
    public Document parse(File file)
        throws SAXException, IOException, IllegalArgumentException;
    public abstract Document parse(InputSource source)
        throws SAXException, IOException, IllegalArgumentException;

    public abstract Document newDocument( );
    public abstract boolean isNamespaceAware( );
    public abstract boolean isValidating( );
    public abstract void setEntityResolver(EntityResolver er);
    public abstract void setErrorHandler(ErrorHandler eh);
    public DOMmplementation getDOMImplementation( );
}

A.3.1.2. DocumentBuilderFactory

This class is the factory used to create instances of the DocumentBuilder class, and allows namespace and validation features to be set for the production of those instances.

public abstract class DocumentBuilderFactory {
    public static DocumentBuilderFactory newInstance( );
    public abstract DocumentBuilder newDocumentBuilder( )
        throws ParserConfigurationException;

    public void setAttribute(String name, Object value);
    public void setCoalescing(boolean coalescing);
    public void setExpandEntityReferences(boolean expand);
    public void setIgnoringComments(boolean ignoreComments);
    public void setIgnoringElementContentWhitespace(boolean ignoreWhitespace);
    public void setNamespaceAware(boolean aware);
    public void setValidating(boolean validating);

    public boolean isCoalescing( );
    public boolean isExapandEntityReferences( );
    public boolean isIgnoringComments( );
    public boolean isIgnoreingElementContentWhitespace( );
    public boolean isNamespaceAware( );
    public boolean isValidating( );
    public Object getAttribute(String name);
}

A.3.1.3. FactoryConfigurationError

This defines an Error that is thrown if a factory instance cannot be created.

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

A.3.1.4. ParserConfigurationException

This defines an Exception that is thrown if a parser is requested but cannot be constructed with the specified validation and namespace-awareness settings.

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

A.3.1.5. SAXParser

This class is the wrapper over an underlying SAX 1.0/2.0 parser implementation class, and allows parsing to occur in a vendor-neutral way. It essentially has a pair of each method: one for SAX 1.0, and one for SAX 2.0.

public abstract class SAXParser {
    public void parse(InputStream stream, HandlerBase base)
        throws SAXException, IOException, IllegalArgumentException;
    public void parse(InputStream stream, HandlerBase base, String systemID)
        throws SAXException, IOException, IllegalArgumentException;
    public void parse(String uri, HandlerBase base)
        throws SAXException, IOException, IllegalArgumentException;
    public void parse(File file, HandlerBase base)
        throws SAXException, IOException, IllegalArgumentException;
    public void parse(InputSource source, HandlerBase base)
        throws SAXException, IOException, IllegalArgumentException;

    public void parse(InputStream stream, DefaultHandler dh)
        throws SAXException, IOException, IllegalArgumentException;
    public void parse(InputStream stream, DefaultHandler dh, String systemID)
        throws SAXException, IOException, IllegalArgumentException;
    public void parse(String uri, DefaultHandler dh)
        throws SAXException, IOException, IllegalArgumentException;
    public void parse(File file, DefaultHandler dh)
        throws SAXException, IOException, IllegalArgumentException;
    public void parse(InputSource source, DefaultHandler dh)
        throws SAXException, IOException, IllegalArgumentException;

    public Parser getParser( ) throws SAXException;
    public XMLReader getXMLReader( ) throws SAXException;

    public Object getProperty(String name);
    public void setProperty(String name, Object value);
    public boolean isNamespaceAware( );
    public boolean isValidating( );
}

A.3.1.6. SAXParserFactory

This class is the factory used to create instances of the SAXParser class, and allows namespace and validation features to be set for the production of those instances.

public abstract class SAXParserFactory {
    public static SAXParserFactory newInstance( );
    public SAXParser newSAXParser( )
        throws ParserConfigurationException, SAXException;

    public void setNamespaceAware(boolean aware);
    public void setValidating(boolean validating);
    public void setFeature(String name, boolean value);
    public boolean isNamespaceAware( );
    public boolean isValidating( );
    public boolean getFeature(String name);
}

A.3.2. Package: javax.xml.transform

This is the package used in JAXP for transforming XML documents. It allows these transformations to be pluggable and vendor-neutral, provided they use the TrAX (Transformations API for XML) interfaces defined here.

A.3.2.1. ErrorListener

This interface is analogous to ErrorHandler in SAX, and provides error notification for transformations. Implement it in your own applications using TrAX.

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

A.3.2.2. OutputKeys

This class is just a holder for several static constants used in the rest of the TrAX API.

public class OutputKeys {
    public static final String CDATA_SECTION_ELEMENTS;
    public static final String DOCTYPE_PUBLIC;
    public static final String DOCTYPE_SYSTEM;
    public static final String ENCODING;
    public static final String INDENT;
    public static final String MEDIA_TYPE;
    public static final String METHOD;
    public static final String OMIT_XML_DECLARATION;
    public static final String STANDALONE;
    public static final String VERSION;
}

A.3.2.3. Result

This interface provides for output of XML transformations. Default implementations of this interface are provided in the JAXP javax.xml.transform.* packages.

public interface Result {
    public static final String PI_DISABLE_OUTPUT_ESCAPING;
    public static final String PI_ENABLE_OUTPUT_ESCAPING;

    public String getSystemId( );
    public void setSystemId( );
}

A.3.2.4. Source

This interface provides for input of XML transformations. Default implementations of this interface are provided in the JAXP javax.xml.transform.* packages.

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

A.3.2.5. SourceLocator

This interface is analogous to the SAX Locator interface, and details location information about an input to TrAX. Like ErrorListener, it's most useful in error handling and reporting.

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

A.3.2.6. Templates

This interface is provided to perform a means of optimal transformations using the same stylesheet. Its only methods allow for generation of Transformer instances, and viewing its current set of output properties.

public interface Tempaltes {
    public Properties getOutputProperties( );
    public Transformer newTransformer( );
}

A.3.2.7. Transformer

This is the core (abstract) class for providing XML transformation facilities through TrAX and JAXP. In addition to setting the various properties and objects on the interface, you can perform the actual transformation with the transform( ) method.

public class Transformer {
    public void setErrorListener(ErrorListener errorListener);
    public ErrorListener getErrorListener( );
    public void setURIResolver(URIResolver resolver);
    public URIResolver getURIResolver( );

    public void setOutputProperties(Properties properties);
    public Properties getOutputProperties( );
    public void setOutputProperty(String name, String value);
    public String getOutputProperty(String name);
    public void clearParmaters( );
    public void setParameter(String name, String value);
    public Object getParameter(String name);

    public void transform(Source xmlSource, Result outputTarget);
}

A.3.2.8. TransformerFactory

This is the other "half" of the transformation engine in JAXP. You can specify the stylesheet to use for transformation, and then obtain new instances of a Transformer instance. You can also use this to generate a new Templates object for multiple transformations using the same stylesheet.

public class TransformerFactory {
    public TransformerFactory newInstance( );
    public Transformer newTemplates(Source stylesheet);
    public Transformer newTransformer(Source stylesheet);
    public Transformer newTransformer( );

    public Source getAssociatedStylesheet(Source source, String media, 
                                          String title, String charset);
    public ErrorListener getErrorListener( );
    public void setErrorListener(ErrorListener errorListener);
    public URIResolver getURIResolver( );
    public void setURIResolver(URIResolver uriResolver);
    public Object getAttribute(String name);
    public void setAttribute(String name, String value);
    public boolean getFeature(String name);
}

A.3.2.9. URIResolver

This is the interface responsible for URI resolution, and is analogous to the SAX EntityResolver interface.

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

A.3.3. Package: javax.xml.transform.dom

This package provides two classes: DOMResult and DOMSource . These are implementations of the Result and Source interfaces, and are used when DOM trees should be the input and output of a transformation. Because these are simple implementation classes, their methods are not detailed here; however, their usage is covered in detail in Chapter 9, "JAXP".

A.3.4. Package: javax.xml.transform.sax

This package provides two classes: SAXResult and SAXSource. These are implementations of the Result and Source interfaces, and are used when SAX events should be the input and output of a transformation. Because these are simple implementation classes, their methods are not detailed here; however, their usage is covered in detail in Chapter 9, "JAXP".

A.3.5. Package: javax.xml.transform.stream

This package provides two classes: StreamResult and StreamSource. These are implementations of the Result and Source interfaces, and are used when I/O streams should be the input and output of a transformation. Because these are simple implementation classes, their methods are not detailed here; however, their usage is covered in detail in Chapter 9, "JAXP".



Library Navigation Links

Copyright © 2002 O'Reilly & Associates. All rights reserved.