<?xml version="1.0" encoding="iso-8859-1"?>
<?xml-stylesheet href="../make-menu.xsl" type="text/xsl"?><html>
<head>
<this-is section="sourcedocs" page="jaxpsources" subpage=""/>
<!--
Generated at 2011-12-09T20:47:22.916Z--><title>Saxonica: XSLT and XQuery Processing: JAXP Source Types</title>
<meta name="coverage" content="Worldwide"/>
<meta name="copyright" content="Copyright Saxonica Ltd"/>
<meta name="title" content="Saxonica: XSLT and XQuery Processing: JAXP Source Types"/>
<meta name="robots" content="noindex,nofollow"/>
<link rel="stylesheet" href="../saxondocs.css" type="text/css"/>
</head>
<body class="main">
<h1>JAXP Source Types</h1>
<p><i>This section is relevant to the Java platform only.</i></p>
<p>When a user application invokes Saxon via the Java API, then a source document is supplied as an
instance of the JAXP <code>Source</code> class. This is true whether invoking an XSLT transformation,
an XQuery query, or a free-standing XPath expression. The <code>Source</code> class
is essentially a marker interface. The <code>Source</code>
that is supplied must be a kind of <code>Source</code> that Saxon recognizes.</p>
<p>Saxon recognizes the three kinds of <code>Source</code> defined in JAXP: a <code>StreamSource</code>,
a <code>SAXSource</code>, and a <code>DOMSource</code>. </p>
<div class="boxed"
style="border: solid thin; background-color: #B1CCC7; padding: 2px">Note that the Xerces DOM implementation is not thread-safe, even for read-only access. Never use
a <code>DOMSource</code> in several threads concurrently, unless you have checked that the DOM
implementation you are using is thread-safe.</div>
<p>Saxon also accepts input from an <code>XMLStreamReader</code> (<code>javax.xml.stream.XMLStreamReader</code>), that is
a StAX pull parser as defined in JSR 173. This is achieved by creating an instance of <a class="bodylink" href="../javadoc/net/sf/saxon/pull/StaxBridge.html"><code>net.sf.saxon.pull.StaxBridge</code></a>,
supplying the <code>XMLStreamReader</code> using the <code>setXMLStreamReader()</code> method, and wrapping the
<code>StaxBridge</code> object in an instance of <a class="bodylink" href="../javadoc/net/sf/saxon/pull/PullSource.html"><code>net.sf.saxon.pull.PullSource</code></a>, which implements the JAXP
<code>Source</code> interface and can be used in any Saxon method that expects a <code>Source</code>. Saxon has been validated
with two StAX parsers: the Zephyr parser from Sun (which is supplied as standard with JDK 1.6), and the open-source Woodstox parser
from Tatu Saloranta. In my experience, Woodstox is the more reliable of the two. However, there is no immediate benefit in using
a pull parser to supply Saxon input rather than a push parser; the main use case for using an <code>XMLStreamReader</code> is when
the data is supplied from some source other than parsing of lexical XML.</p>
<p>Nodes in Saxon's implementation of the XPath data model are represented by the interface
<a class="bodylink" href="../javadoc/net/sf/saxon/om/NodeInfo.html"><code>NodeInfo</code></a>. A <code>NodeInfo</code> is itself a <code>Source</code>, which means
that any method in the API that requires a source object will accept any implementation of
<code>NodeInfo</code>. As discussed in the next section, implementations of <code>NodeInfo</code>
are available to wrap DOM, DOM4J, JDOM, or XOM nodes, and in all cases these wrapper objects can be used
wherever a <code>Source</code> is required.</p>
<p>Saxon also provides a class <a class="bodylink" href="../javadoc/net/sf/saxon/lib/AugmentedSource.html"><code>net.sf.saxon.lib.AugmentedSource</code></a> which implements the <code>Source</code>
interface. This class encapsulates one of the standard <code>Source</code> objects, and allows additional processing
options to be specified. These options include whitespace handling, schema and DTD validation, XInclude processing,
error handling, choice of XML parser, and choice of Saxon tree model.</p>
<p>Saxon allows additional <code>Source</code> types to be supported by registering a <a class="bodylink" href="../javadoc/net/sf/saxon/lib/SourceResolver.html"><code>SourceResolver</code></a>
with the <a class="bodylink" href="../javadoc/net/sf/saxon/Configuration.html"><code>Configuration</code></a> object. The task of a <code>SourceResolver</code> is to convert a
<code>Source</code> that Saxon does not recognize into a <code>Source</code> that it does recognize.
For example, this may be done by building the document tree in memory and returning the <a class="bodylink" href="../javadoc/net/sf/saxon/om/NodeInfo.html"><code>NodeInfo</code></a>
object representing the root of the tree.</p>
<table width="100%">
<tr>
<td>
<p align="right"><a class="nav" href="thirdparty.xml">Next</a></p>
</td>
</tr>
</table>
</body>
</html>
