📄 3_apis.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"><html><head><title>API Overview, Javasoft XML APIs</title><style type="text/css"></style><meta name="fileID" content="quickIntro"><meta name="keywords" content="XML"></head><body BGCOLOR="#ffffff"><table width="100%"> <tr> <td align=left> <a href="2_specs.html"><img src="../images/PreviousArrow.gif" width=26 height=26 align=bottom border=0 alt="Previous | "></a><ahref="4_design.html"><img src="../images/NextArrow.gif" width=26 height=26 align=bottom border=0 alt="Next | "></a><a href="../alphaIndex.html"><img src="../images/xml_IDX.gif" width=26 height=26 align=bottom border=0 alt="Index | "></a><a href="../TOC.html"><imgsrc="../images/xml_TOC.gif" width=26 height=26 align=bottom border=0 alt="TOC | "></a><a href="../index.html"><imgsrc="../images/xml_Top.gif" width=26 height=26 align=bottom border=0 alt="Top | "></a></td> <td align=right><strong><em><a href="index.html">Top</a></em></strong> <a href="../TOC.html#intro"><strong><em>Contents</em></strong></a> <a href="../alphaIndex.html"><strong><em>Index</em></strong></a> <a href="../glossary.html"><strong><em>Glossary</em></strong></a> </td> </tr></table><p> <center> <IMG SRC="../images/shoeline2.gif" ALIGN="BOTTOM" BORDER="0" WIDTH="202" HEIGHT="25" NATURALSIZEFLAG="3"> <IMG SRC="../images/shoeline2.gif" ALIGN="BOTTOM" BORDER="0" WIDTH="202" HEIGHT="25" NATURALSIZEFLAG="3"> </center><blockquote> <blockquote> <hr size=4> </blockquote></blockquote><p> <h2> 3. An Overview of the APIs</h2><table width="40%" border="1" align="right"> <tr> <td> <div align="center"><b><i>Link Summary</i></b></div> </td> </tr> <tr> <td> <dl> <dt><b><i>Local Links</i></b></dt> </dl> <ul> <li><a href="3_apis_addlSAX.html">Other SAX APIs</a></li> <li><a href="../index.html#XmlThread">The XML Thread</a></li> <li><a href="4_design.html">Designing an XML Data Structure</a></li> <li><a href="../sax/index.html">The Simple API for XML (SAX)</a></li> <li><a href="../dom/index.html">The Document Object Model (DOM)</a></li> <li><a href="../../../examples/index.html">Examples</a></li> </ul> <p><b><i>API References</i></b></p> <ul> <li><a href="../../api/javax/xml/parsers/SAXParserFactory.html">javax.xml.parsers.SAXParserFactory</a></li> <li><a href="../../api/javax/xml/parsers/DocumentBuilderFactory.html">javax.xml.parsers.DocumentBuilderFactory</a></li> <li><a href="../../api/javax/xml/parsers/DocumentBuilder.html">javax.xml.parsers.DocumentBuilder</a></li> <li><a href="../../api/org/xml/sax/Parser.html">org.xml.sax.Parser</a></li> <li><a href="../../api/internal/com/sun/xml/parser/package-summary.html">com.sun.xml.parser</a></li> <li><a href="../../api/org/xml/sax/HandlerBase.html">org.xml.sax.HandlerBase</a></li> <li><a href="../../api/org/xml/sax/helpers/package-summary.html">org.xml.sax.helpers</a></li> <li><a href="../../api/org/w3c/dom/package-summary.html">org.w3c.dom</a></li> <li><a href="../../api/org/w3c/dom/Document.html">org.w3c.dom.Document</a></li> <li><a href="../../api/internal/com/sun/xml/tree/package-summary.html">com.sun.xml.tree</a></li> <li><a href="../../api/internal/com/sun/xml/treediff/package-summary.html">com.sun.xml.treediff</a></li> <li><a href="../../api/internal/com/sun/xml/xhtml/package-summary.html">com.sun.xml.xhtml</a></li> </ul> <p><b><i>Glossary Terms</i></b></p> <dl> <dd><a href="../glossary.html#namespace">namespace</a>, <a href="../glossary.html#prolog">prolog</a>, <a href="../glossary.html#URL">URL</a>, <a href="../glossary.html#URN">URN</a>, <a href="../glossary.html#w3c">W3C</a> <a href="../glossary.html#prolog"></a> </dd> </dl> <dl> <dt> </dt> </dl> </td> </tr></table><p> This page gives you a map so you can find your way around JAXP and the associated XML APIs. <h3><a name="JAXP"></a>The JAXP APIs</h3><p>The JAXP APIs, contained in the <tt>jaxp.jar</tt> file, are comprised of the <code>javax.xml.parsers</code> package. That package contains two vendor-neutral factory classes: <a href="../../api/javax/xml/parsers/SAXParserFactory.html">SAXParserFactory</a> and <a href="../../api/javax/xml/parsers/DocumentBuilderFactory.html">DocumentBuilderFactory</a> that give you a SAX parser and a DocumentBuilder, respectively. The <a href="../../api/javax/xml/parsers/DocumentBuilder.html">DocumentBuilder</a>, in turn, creates DOM-compliant <a href="../../api/org/w3c/dom/Document.html">Document</a> object. <p>The factory APIs give you the ability to plug in an XML implementation offered by another vendor without changing your source code. The implementation you get depends on the setting of the <tt>javax.xml.parsers.SAXParserFactory</tt> and <tt>javax.xml.parsers.DocumentBuilderFactory</tt> system properties. The default values (unless overridden at runtime) point to Sun's reference implementations at <code>com.sun.xml</code>. <p>The remainder of this section shows how those APIs relate to each other in an application. As you read, watch for this logo: <img src="../images/sun.gif" width="62" height="29"> It identifies the parts of the discussion that deal exclusively with Sun's reference implementation.<h3><a name="overview"></a>An Overview of SAX and DOM</h3><p>As discussed in the previous section, the SAX and DOM APIs are defined by XML-DEV group and by the <a href="../glossary.html#w3c">W3C</a>, respectively. The libraries that define those APIs are included in the <tt>parser.jar</tt> file, which also contains Sun's reference implementation, Project X. <p>The "Simple API" for XML (SAX) is the event-driven, serial-access mechanism that does element-by-element processing. The API for this level reads and writes XML to a data repository or the Web. For server-side and high-performance apps, you will want to fully understand this level. But for many applications, a minimal understanding will suffice. <p>The DOM API is generally an easier API to use. It provides a relatively familiar tree structure of objects. You can use the DOM API to manipulate the hierarchy of application objects it encapsulates. The DOM API is ideal for interactive applications because the entire object model is present in memory, where it can be accessed and manipulated by the user. <p>On the other hand, constructing the DOM requires reading the entire XML structure and holding the object tree in memory, so it is much more CPU and memory intensive. For that reason, the SAX API will tend to be preferred for server-side applications and data filters that do not require an in-memory representation of the data. <h3><a name="SAX"></a>The SAX APIs</h3> <table align="right" width="40%" border="1"> <tr> <td><img src="images/sax-api.gif" width="384" height="471"></td> </tr> </table>The basic outline of a SAX parser is shown at right. First, the <code>SAXParserFactory</code> shown at the top generates an instance of the parser. <p>The XML text is shown coming in to the parser from the left. As the data is parsed, the parser invokes one of several callback methods defined by the interfaces <code>DocumentHandler</code>, <code>ErrorHandler</code>, <code>DTDHandler</code>, and <code>EntityResolver</code>. </p> <p>Here is a summary of the key SAX APIs: </p> <dl> <dt><code><b><a name="ParserFactory"></a>SAXParserFactory</b></code></dt> <dd>A <a href="../../api/javax/xml/parsers/SAXParserFactory.html">SAXParserFactory</a> object creates an instance of the parser determined by the system property, <code>javax.xml.parsers</code><tt>.SAXParserFactory</tt>.</dd> <dt><code><b><a name="Parser"></a>Parser</b></code></dt> <dd>The <a href="../../api/org/xml/sax/Parser.html"><code>org.xml.sax.Parser</code></a> interface defines methods like <code>setDocumentHandler</code> to set up event handlers and <code>parse(URL)</code> to actually do the parsing. This interface is implemented by the <code>Parser</code> and <code>ValidatingParser</code> classes in the <a href="../../api/internal/com/sun/xml/parser/package-summary.html"><code>com.sun.xml.parser</code></a> package.</dd> <dt> </dt> <dt><code><b><a name="DocumentHandler"></a>DocumentHandler</b></code></dt> <dd>Methods like <code>startDocument</code>, <code>endDocument</code>, <code>startElement</code>, and <code>endElement</code> are invoked when an XML tag is recognized. This interface also defines methods <code>characters</code> and <code>processingInstruction</code>, which are invoked when the parser encounters the text in an XML element or an inline processing instruction, respectively.</dd> <dt> </dt> <dt><code><b><a name="ErrorHandler"></a>ErrorHandler</b></code></dt> <dd>Methods <code>error</code>, <code>fatalError</code>, and <code>warning</code> are invoked in response to various parsing errors. The default error handler throws an exception for fatal errors and ignores other errors (including validation errors). That's one reason you need to know something about the SAX parser, even if you are using the DOM. Sometimes, the application may be able to recover from a validation error. Other times, it may need to generate an exception. To ensure the correct handling, you'll need to supply your own error handler to the parser.</dd> <dt> </dt> <dt><code><b><a name="DTDHandler"></a>DTDHandler</b></code></dt> <dd>Methods defined in this interface are invoked when processing definitions in a <a href="../glossary.html#DTD">DTD</a>. These methods are discussed in <a href="../sax/9_notatn.html">Using the DTDHandler and EntityResolver</a>. This interface is extended by the <tt>com.sun.java.xml</tt> interface <a href="../../api/internal/com/sun/xml/parser/DtdEventListener.html"><code>DtdEventListener</code></a>, which adds methods like <code>startDtd</code> and <code>endDtd</code>.</dd> <dt> </dt> <dt><code><b><a name="EntityResolver"></a>EntityResolver</b></code></dt> <dd>The <code>resolveEntity</code> method is invoked when the parser must identify data identified by a <a href="../glossary.html#URI">URI</a>. In most cases, a URI is simply a <a href="../glossary.html#URL">URL</a>, which specifies the location of a document, but in some cases the document may be identified by a <a href="../glossary.html#URN">URN</a> -- a <i>public identifier</i>, or name, that is unique in the web space. <a href="../glossary.html#URN"></a> The public identifier may be specified in addition to the URL. The <code>EntityResolver</code> can then use the public identifier instead of the URL to find the document, for example to access a local copy of the document if one exists.</dd> </dl> <p>A typical application provides a <code>DocumentHandler</code>, at a minimum. Since the default implementations of the interfaces ignore all inputs except for fatal errors, a robust implementation may want to provide an ErrorHandler to report more errors or report them differently. </p> <blockquote> <p><b><a name="HandlerBase"></a>Note:</b> The class <a href="../../api/org/xml/sax/HandlerBase.html"><code>org.xml.sax.HandlerBase</code></a> implements all of these interfaces with null methods, so you can override the methods for events you need to process and ignore the methods for other events.</p> </blockquote> <h4><a name="SaxPackages"></a>Packages</h4> <p>The SAX parser is defined in the following packages.</p> <table width="92%" border="1"> <tr> <td width="22%" height="25"><b><i>Package</i></b></td> <td width="78%" height="25"><b><i>Description</i></b></td> </tr> <tr> <td width="22%"><a href="../../api/org/xml/sax/package-summary.html">org.xml.sax</a> </td> <td width="78%">Defines the SAX interfaces. The name "<code>org.xml</code>" is the package prefix that was settled on by the group that defined the SAX API. This package also defines <code>HandlerBase</code> -- a default implementation of a base class for the various "handlers" defined by the interfaces, as well as an <code>InputSource</code> class, which encapsulates information that tells where the XML data is coming from.</td> </tr> <tr> <td width="22%"><a href="../../api/org/xml/sax/helpers/package-summary.html">org.xml.sax.helpers</a></td> <td width="78%"> <p>This package is part of SAX. It defines the <code>ParserFactory</code> class, which lets you acquire an instance of a parser either by specifying a name string or by using the value defined by the <code>org.xml.sax.parser</code> system property. This package also provides implementations for two other interfaces defined in <code>org.xml.sax</code>, but these classes are not needed when using Sun's Java XML SAX parsers.</p> </td> </tr> <tr> <td width="22%"><a href="../../api/javax/xml/parsers/package-frame.html">javax.xml.parsers</a></td> <td width="78%">Defines the <code>SAXParserFactory</code> class which returns the SAXParser. Also defines the <code>ParserConfigurationException</code> class for reporting errors.</td> </tr> <tr> <td width="22%"><a href="../../api/internal/com/sun/xml/parser/package-summary.html">com.sun.xml.parser</a></td> <td width="78%">Contains the Java XML parser (<code>com.sun.xml.parser.Parser</code>), validating parser (<code>com.sun.xml.parser.ValidatingParser</code>), and entity resolver. The fully qualified name of either parser can be sent to the parser factory to obtain an instance of that parser. The nonvalidating parser generates errors if a document is not well formed, and does some processing of the DTD (if present) but does not check to make sure that the document obeys all of the constraints defined by the DTD. The validating parser, on the other hand, checks to make sure that the document obeys all such constraints.</td> </tr> </table> <blockquote> <p><b>Technical Note: </b><br> All nonvalidating parsers are not created equal! Although a validating parser is required to process <i>all</i> external entities referenced from within the document, some of that processing is optional for a nonvalidating parser. With such a parser, an externally stored section of the DTD that is "included" in the current document using an entity reference might not be processed. In addition, a nonvalidating parser is not required to identify ignorable whitespace (although a validating parser must). In that case, whitespace ⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -