JAXP

JAXP, the Java API for XML Processing, is a fairly complete set of APIs for processing XML with Java. It is bundled with Java 1.4 and later, and available as a separate extension for Java 1.2 and later. (All pieces except TrAX should run in Java 1.1 and later.) Most current XML parsers for Java support JAXP including Crimson, Ælfred, Xerces, Piccolo, and the Oracle XML Parser for Java. JAXP incorporates SAX and DOM by reference. In addition it adds the Transformations API for XML (TrAX) and some factory classes for locating a parser and building new documents in memory. This section covers those factory classes, all of which are in the javax.xml.parsers package.

As well as adopting DOM and SAX into the core Java API, JAXP adds a few factory classes to fill some holes in these APIs and enable Java programmers to write completely parser-independent code.

javax.xml.parsers

The one major new invention in JAXP that was not based on previous standards was a series of abstract factory classes in the javax.xml.parsers package. These allow a Java program to obtain a DOM parser, a SAX1 Parser, or a DOMImplementation in a parser-independent fashion. The SAX1 factories are now obsolete, but the DOM factories are still quite useful.

DocumentBuilder

The DocumentBuilder class is an abstract factory used to create new DOM Document and DOMImplementation objects. As well as creating new instances from scratch, DocumentBuilder can also read a document from an InputStream, Reader, File, SAX InputSource, or a URI.

package javax.xml.parsers;

public abstract class DocumentBuilder  {

  protected DocumentBuilder();

  public Document          newDocument();
  public DOMImplementation getDOMImplementation();

  public Document parse(InputStream in) 
   throws SAXException, IOException;
  public Document parse(InputStream in, String systemID)
   throws SAXException, IOException;
  public Document parse(String uri) 
   throws SAXException, IOException;
  public Document parse(File f)
   throws SAXException, IOException;
  public Document parse(InputSource in) 
   throws SAXException, IOException;

  public boolean  isNamespaceAware();
  public boolean  isValidating();
  public void     setEntityResolver(EntityResolver resolver);
  public void     setErrorHandler(ErrorHandler handler);

}

DocumentBuilderFactory

The DocumentBuilderFactory class is an abstract factory used to create new DocumentBuilder objects. You should always call setNamespaceAware(true) before calling newInstance(true).

package javax.xml.parsers;

public abstract class DocumentBuilderFactory  {

  protected DocumentBuilderFactory();

  public static DocumentBuilderFactory newInstance() 
   throws FactoryConfigurationError;
  public DocumentBuilder newDocumentBuilder() 
   throws ParserConfigurationException;

  public void    setNamespaceAware(boolean awareness);
  public void    setValidating(boolean validating);
  public void    setIgnoringElementContentWhitespace(
   boolean ignoreWhitespace);
  public void    setExpandEntityReferences(
   boolean expandEntities);
  public void    setIgnoringComments(boolean ignoreComments);
  public void    setCoalescing(boolean coalescing);
  public boolean isNamespaceAware();
  public boolean isValidating();
  public boolean isIgnoringElementContentWhitespace();
  public boolean isExpandEntityReferences();
  public boolean isIgnoringComments();
  public boolean isCoalescing();
  public void    setAttribute(String name, Object value) 
   throws IllegalArgumentException;
  public Object  getAttribute(String name)
   throws IllegalArgumentException;

}

Different vendors provide different implementations of this abstract class. Java chooses the one to use based on the following conditions in order of preference:

  1. The value of the javax.xml.parsers.DocumentBuilderFactory Java system property

  2. The value of the javax.xml.parsers.DocumentBuilderFactory property specified in the lib/jaxp.properties properties file in the JRE directory

  3. The first value found in a META-INF/services/javax.xml.parsers.DocumentBuilderFactory file in the JAR files available to the runtime

  4. The platform default (org.apache.crimson.jaxp.DocumentBuilderFactoryImpl in Sun’s JDK 1.4).

SAXParser

SAXParser is an obsolete class for locating SAX 1 parsers and parsing documents. It’s been replaced by the org.xml.sax.helpers.XMLReaderFactory class in SAX2.

package javax.xml.parsers;

public abstract class SAXParser  {

  protected SAXParser();

  public void parse(InputStream in, HandlerBase handler) 
   throws SAXException, IOException;
  public void parse(InputStream in, HandlerBase handler, 
   String systemID) throws SAXException, IOException;
  public void parse(InputStream in, DefaultHandler handler) 
   throws SAXException, IOException;
  public void parse(InputStream in, DefaultHandler handler, 
   String systemID) throws SAXException, IOException;
  public void parse(String uri, HandlerBase handler) 
   throws SAXException, IOException;
  public void parse(String uri, DefaultHandler handler) 
   throws SAXException, IOException;
  public void parse(File f, HandlerBase handler) 
   throws SAXException, IOException;
  public void parse(File f, DefaultHandler handler)
   throws SAXException, IOException;
  public void parse(InputSource in, HandlerBase handler) 
   throws SAXException, IOException;
  public void parse(InputSource in, DefaultHandler handler) 
   throws SAXException, IOException;

  public Parser    getParser() throws SAXException;
  public XMLReader getXMLReader() throws SAXException;
  public boolean   isNamespaceAware();
  public boolean   isValidating();
  public void      setProperty(String name, Object value) 
   throws SAXNotRecognizedException, SAXNotSupportedException;
  public Object    getProperty(String name)
   throws SAXNotRecognizedException, SAXNotSupportedException;

}

SAXParserFactory

SAXParserFactory is an obsolete class for building and configuring SAXParser objects in an implementation independent fashion. The concrete subclass to load is read from the javax.xml.parsers.SAXParserFactory Java system property. This class has been replaced by the org.xml.sax.helpers.XMLReaderFactory class in SAX2, and there's little reason to use it any more.

package javax.xml.parsers;

public abstract class SAXParserFactory  {

  protected SAXParserFactory();

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

}

Exceptions and Errors

The javax.xml.parsers package includes one error and one exception, representing the things that can go wrong when loading a parser or a DOM implementation. Either one is normally a symptom of class path problems.

ParserConfigurationException

A ParserConfigurationException signals that a factory is unable to load and instantiate a parser class.

package javax.xml.parsers;

public class ParserConfigurationException extends Exception {

  public ParserConfigurationException();
  public ParserConfigurationException(String message);

}
FactoryConfigurationError

A FactoryConfigurationError signals that Java is unable to load and instantiate the concrete factory class. This is normally a symptom of class path problems.

package javax.xml.parsers;

public class FactoryConfigurationError extends Error {

  public FactoryConfigurationError();
  public FactoryConfigurationError(String message);
  public FactoryConfigurationError(Exception e);
  public FactoryConfigurationError(Exception e, String message);

  public String    getMessage();
  public Exception getException();

}

Copyright 2001, 2002 Elliotte Rusty Haroldelharo@metalab.unc.eduLast Modified June 03, 2002
Up To Cafe con Leche