<?xml version="1.0" encoding="iso-8859-1"?>
<?xml-stylesheet href="../../make-menu.xsl" type="text/xsl"?><html>
<head>
<this-is section="changes" page="s90" subpage="oldapi90"/>
<!--
Generated at 2011-12-09T20:47:22.916Z--><title>Saxonica: XSLT and XQuery Processing: Changes to existing APIs</title>
<meta name="coverage" content="Worldwide"/>
<meta name="copyright" content="Copyright Saxonica Ltd"/>
<meta name="title"
content="Saxonica: XSLT and XQuery Processing: Changes to existing APIs"/>
<meta name="robots" content="noindex,nofollow"/>
<link rel="stylesheet" href="../../saxondocs.css" type="text/css"/>
</head>
<body class="main">
<h1>Changes to existing APIs</h1>
<p>The behavior of <code>configuration.buildDocument()</code> has changed for cases where the supplied <code>Source</code>
object is a tree. In particular, if it is a <code>DOMSource</code> then the DOM Document node will normally be wrapped
in a Saxon wrapper object rather than being copied to a TinyTree. This has the effect of reinstating the pre-8.9
behaviour of methods in the XPath API that are given a DOMSource as an argument; the XPath expressions will now return
nodes in the original DOM tree rather than copies of these nodes.</p>
<p>Support for DOM Level 2 implementations has been reinstated; however Saxon no longer attempts to detect whether the
DOM supports level 3 interfaces; instead, when a Level 2 DOM implementation is used, the configuration setting
<code>config.setDOMLevel(2)</code> must be used. (Saxon now has compile-time references to DOM level 3 methods, but
will not call such methods if this configuration setting is in force.)</p>
<p>The class <code>StaticQueryContext</code> has been split into two: user-facing methods used to initialize the context
for a query are still in <code>StaticQueryContext</code>, but methods intended for system use, which update the context
as declarations in the query prolog are parsed, have been moved to a new class <code>QueryModule</code>. The class
<code>StaticQueryContext</code> no longer implements the <code>StaticContext</code> interface.</p>
<p>As part of the above change, some methods on <code>StaticQueryContext</code> have been dropped. This notably includes
the method <code>declareVariable()</code> which never worked in a satisfactory way because the variable was not reusable
across multiple queries. External variables should always be declared from the query prolog.</p>
<p>A new factory method <code>Configuration.makeConfiguration()</code> is available. This creates a schema-aware configuration
if Saxon-SA is installed and licensed, otherwise it creates a non-schema-aware configuration. This option is useful for
applications that want to take advantage of the enhanced Saxon-SA optimizer in cases where it is available, but do not
otherwise depend on Saxon-SA functionality.</p>
<p>A new method on <code>Configuration</code> is introduced to copy a <code>Configuration</code>. The main motivation for this
is to eliminate the high cost of repeatedly checking the Saxon-SA license key in applications that create many separate
Configurations.</p>
<p>The rule that all documents used within a single query, transformation, or XPath expression must be built using the
same <code>Configuration</code> has been relaxed slightly, so the requirement is only that they must be "compatible" Configurations,
which means in practice that they must use the same <code>NamePool</code> and <code>DocumentNumberAllocator</code>.
Although the rule has been
relaxed slightly, it is also now enforced on a number of interfaces where previously no checking took place (which could
lead to unpredictable failures later). This applies in particular to XPath APIs.</p>
<p>A new option is available in the <code>Configuration</code> to indicate that calls to the <code>doc()</code>
or <code>document()</code> functions with constant string arguments should be evaluated when a query or
stylesheet is compiled, rather than at run-time. This option is intended for use when a reference or lookup
document is used by all queries and transformations. Using this option has a number of effects: (a) the
URI is resolved using the compile-time URIResolver rather than the run-time URIResolver; (b) the document
is loaded into a document pool held by the <code>Configuration</code>, whose memory is released only when
the <code>Configuration</code> itself ceases to exist; (c) all queries and transformations using this
document share the same copy; (d) any updates to the document that occur between compile-time and run-time
have no effect. The option is selected by using <code>Configuration.setConfigurationProperty()</code>\
or <code>TransformerFactory.setAttribute()</code> with the property name <code>FeatureKeys.PRE_EVALUATE_DOC_FUNCTION</code>.
This option is not available from the command line because it has no useful effect with a single-shot
compile-and-run interface.</p>
<p>A convenience method <code>QueryResult.serialize(NodeInfo node)</code> has been provided, allowing
a node to be serialized as XML; the result is returned as a String.</p>
<p>There is also a convenience method <code>Navigator.getAttributeValue(NodeInfo node, String uri, String localName)</code>
making it easier for Java applications to get an attribute of an element.</p>
<p>In the <code>NodeInfo</code> interface, the rules for the <code>copy()</code> method have changed so that
when an element is copied, its namespaces must be output without duplicates (or without a declaration being
cancelled by an undeclaration). The method no longer relies on the recipient removing such duplicates.</p>
<p>The method <code>NodeInfo#sendNamespaceDeclarations</code> has been deleted.</p>
<p>The class <code>NameTest</code> has a new constructor taking a URI and local name as strings, making it easier
to construct a <code>NameTest</code> for use in calls to <code>iterateAxis()</code>. In addition, the abstract class
<code>NodeTest</code> now has only one abstract method, making it easier to write a user-defined implementation of
<code>NodeTest</code> for filtering the nodes returned by <code>iterateAxis()</code>.</p>
<p>Methods that construct or convert atomic values no longer return ValidationErrorValue in the event of a failure.
There were a couple of problems with this mechanism: although it was designed to eliminate the costs of throwing an
exception, it failed to take into account the cost of creating the exception before throwing it, which is surprisingly
expensive as it involves capturing a stack trace. Secondly, the mechanism wasn't type safe as it didn't force callers to
check the return value for an error. These methods (and a number of others) now return a <code>ConversionResult</code>
which is essentially a union type of <code>AtomicValue</code> and <code>ValidationFailure</code>. Code calling these
methods therefore has to consciously cast the result to <code>AtomicValue</code>, preferably after checking that the
result is not a <code>ValidationFailure</code>.</p>
<p>The two exception classes <code>StaticError</code> and <code>DynamicError</code> are no longer used: instead, their
common base class <code>XPathExpression</code> is now a concrete class and is used to represent both static and dynamic
errors. It includes a field to distinguish the two cases, though in fact there is very little code that cares about the
difference (the only time the difference is significant is when dynamic errors occur during early compile-time evaluation
of constant subexpressions). Any application code that contains a catch for <code>StaticError</code> or <code>DynamicError</code>
should be changed to catch <code>XPathException</code> instead. Since nearly all API methods declared "throws XPathException"
already, this is unlikely to be a major issue.</p>
<p>There has been some tidying up of methods on the <code>AtomicValue</code> class, especially methods for converting
values between types and for setting the type label.</p>
<p class="subhead">The .NET API</p>
<p>In the .NET API, the class <code>XsltCompiler</code> now has an overload of the <code>Compile()</code> method that takes input
from a <code>TextReader</code> (for example, a <code>StringReader</code>).</p>
<p>The class <code>XdmAtomicValue</code> now has a static factory method that constructs an "external object", that is,
an XPath wrapper around a .NET object. This can be passed as a parameter to a stylesheet or query and used as an
argument to extension functions.</p>
<p>The class <code>TextWriterDestination</code> (despite its name, which is unchanged) now wraps any <code>XmlWriter</code>.
It was previously restricted to wrap an <code>XmlTextWriter</code>.</p>
<p class="subhead">The XQJ API</p>
<p>Saxon's implementation of the XQuery API for Java (XQJ) (jsr-225) has been upgraded to conform to the version 0.9
specifications released on 12 June 2007. The specifications can be downloaded at <a href="http://jcp.org/en/jsr/detail?id=225" class="bodylink">http://jcp.org/en/jsr/detail?id=225</a>.
There are some incompatibilities: applications will need to be changed, though probably not extensively.</p>
<p>Please note that this API is still a draft, and Saxon's implementation will change when the specifications change.</p>
<table width="100%">
<tr>
<td>
<p align="right"><a class="nav" href="pull90.xml">Next</a></p>
</td>
</tr>
</table>
</body>
</html>
