JAXP | Processing XML with Javaв„ў: A Guide to SAX, DOM, JDOM, JAXP, and TrAX

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.) JAXP is supported by most current XML parsers for Java, 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 to enable Java programmers to write completely parser-independent code.

javax.xml.parsers

The one major innovation in JAXP not based on previous standards is a series of abstract factory classes in the javax.xml.parsers package. These enable 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 remain 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 read a document from an InputStream , Reader , File , SAX InputSource , or 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; }

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

The value of the javax.xml.parsers.DocumentBuilderFactory Java system property
The value of the javax.xml.parsers.DocumentBuilderFactory property specified in the lib/jaxp.properties properties file in the JRE directory
The first value found in a META-INF/services/javax.xml.parsers.DocumentBuilderFactory file in the JAR files available to the runtime
The platform default ( org.apache.crimson.jaxp.DocumentBuilderFactoryImpl in Sun's JDK 1.4)

SAXParser

SAXParser is an obsolete class for locating SAX1 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 anymore.

 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, to represent the things that can go wrong when loading a parser or a DOM implementation. Either one is normally a symptom of class path problems.

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  (); }

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  ); }