Project

Profile

Help

How to connect?
Download (32.2 KB) Statistics
| Branch: | Revision:

he / src / userdoc / xpath-api.xml @ d9cb5c62

1
<?xml version="1.0" encoding="utf-8"?>
2
<article id="xpath-api" title="Using XPath">
3
   <h1>Using XPath</h1>
4

    
5

    
6
   <p>This section describes how to use Saxon as a Java class library for XPath processing, without
7
      making any use of XSLT stylesheets. It includes information on the XPath API, and the API for
8
      the Saxon implementation of the XPath object model. On other pages you will find the <a
9
         class="bodylink" href="/using-xsl/embedding">API for XSLT transformation</a>, the <a
10
         class="bodylink" href="/using-xquery/api-query">API for running XQuery</a>, and the <a
11
         class="bodylink" href="/schema-processing/validation-api">API for Schema
12
      validation.</a></p>
13

    
14
   <p>For information about the different ways of loading source documents, see <a class="bodylink"
15
         href="/sourcedocs">Handling XML Documents</a>.</p>
16

    
17
   <p>Saxon supports three Java APIs for XPath processing, as follows:</p>
18
   <ul>
19
      <li>
20
         <p>The preferred interface for XPath processing is Saxon's <strong>s9api</strong> interface
21
            ("snappy"), which also supports XSLT and XQuery processing, schema validation, and other
22
            Saxon functionality in an integrated set of interfaces. This is described at <a
23
               class="bodylink" href="s9api-xpath">Evaluating XPath Expressions using s9api</a>.
24
         </p>
25
      </li>
26
      <li>
27
         <p>The JAXP API is a (supposedly) standard API defined in Java 5. Saxon implements this
28
            interface. Details of Saxon's implementation are described at <a class="bodylink"
29
               href="jaxp-xpath">JAXP XPath API</a>. Note that there are some extensions and other
30
            variations in the Saxon implementation. Some of the extensions to this interface are
31
            provided because Saxon supports XPath 2.0 (and higher), whereas JAXP 1.3 is designed
32
            primarily for XPath 1.0; some are provided because Saxon supports multiple object
33
            models, not only DOM; some are for backwards compatibility; and some are provided to
34
            allow applications a finer level of control if required.</p>
35
      </li>
36
      <li>
37
         <p>For historical reasons Saxon continues to support a legacy XPath API in package <a
38
               class="javalink" href="net.sf.saxon.sxpath">net.sf.saxon.sxpath</a>. This is
39
            documented only in the Javadoc specifications. It is a lower-level API, so as well as
40
            being retained for backwards compatibility, it may also be appropriate for applications
41
            that require a very intimate level of integration with Saxon internals.</p>
42
      </li>
43
   </ul>
44
   
45
   <p>Saxon allows XPath expressions to be evaluated either against its own native tree models of
46
      XML (the tiny tree and linked tree), and also against trees built using the DOM, JDOM, JDOM2,
47
      DOM4J, XOM, or AXIOM tree models. (It's also possible to build adapters for other tree models,
48
      though this is not for the faint-hearted.)</p>
49
   <section id="s9api-xpath" title="Evaluating XPath Expressions using s9api">
50
      <h1>Evaluating XPath Expressions using s9api</h1>
51

    
52

    
53
      <p>The s9api interface is a custom-designed API for Saxon, allowing integrated access to all
54
         Saxon's XML processing capabilities in a uniform way, taking advantage of the type safety
55
         offered by generics in Java 5.</p>
56

    
57
      <p>You can evaluate an XPath expression using the s9api interface in a number of ways, for
58
         instance as follows:</p>
59
      <ol>
60
         <li>
61
            <p>Create a <a class="javalink" href="net.sf.saxon.s9api.Processor">Processor</a> and
62
               set any global configuration options on the <code>Processor</code>.</p>
63
         </li>
64
         <li>
65
            <p>Build the source document by calling <code>newDocumentBuilder()</code> to create a
66
               document builder, setting appropriate options, and then calling the
67
                  <code>build()</code> method. This returns an <a class="javalink"
68
                  href="net.sf.saxon.s9api.XdmNode">XdmNode</a> which can be supplied as the context
69
               item to the XPath expression.</p>
70
         </li>
71
         <li>
72
            <p>Call <code>newXPathCompiler()</code> to create an <a class="javalink"
73
                  href="net.sf.saxon.s9api.XPathCompiler">XPathCompiler</a>, and set any options
74
               that are local to a specific compilation (notably declaring namespace prefixes that
75
               are used in the XPath expression).</p>
76
         </li>
77
         <li>
78
            <p>Call the <code>compile()</code> method to compile an expression. The result is an <a
79
                  class="javalink" href="net.sf.saxon.s9api.XPathExecutable">XPathExecutable</a>,
80
               which can be used as often as you like in the same thread or in different
81
               threads.</p>
82
         </li>
83
         <li>
84
            <p>To evaluate the expression, call the <code>load()</code> method on the
85
                  <code>XPathExecutable</code>. This creates an <a class="javalink"
86
                  href="net.sf.saxon.s9api.Processor">XPathSelector</a>. The
87
                  <code>XPathSelector</code> can be serially reused, but it must not be shared
88
               across multiple threads. Set any options required for the specific XPath execution
89
               (for example, the initial context node, the values of any variables referenced in the
90
               expression), and then call one of the methods <code>iterator()</code>,
91
               <code>evaluate()</code>, or <code>evaluateSingle()</code> to execute the XPath
92
               expression.</p>
93
         </li>
94
         <li>
95
            <p>Because the <code>XPathSelector</code> is an <code>Iterable</code>, it is possible to
96
               iterate over the results directly using the Java 5 "for-each" construct.</p>
97
         </li>
98
         <li>
99
            <p>The result of an XPath expression is in general an <a class="javalink"
100
                  href="net.sf.saxon.s9api.XdmValue">XdmValue</a>, representing a value as defined
101
               in the XDM data model (that is, a sequence of nodes and/or atomic values). Subclasses
102
               of <code>XdmValue</code> include <a class="javalink"
103
                  href="net.sf.saxon.s9api.XdmItem">XdmItem</a>, <a class="javalink"
104
                  href="net.sf.saxon.s9api.XdmNode">XdmNode</a>, and <a class="javalink"
105
                  href="net.sf.saxon.s9api.XdmAtomicValue">XdmAtomicValue</a>, and these relate
106
               directly to the corresponding concepts in XDM. Various methods are available to
107
               translate between this model and native Java data types.</p>
108
         </li>
109
      </ol>
110

    
111
      <p>The <a class="javalink" href="net.sf.saxon.s9api.XPathCompiler">XPathCompiler</a> also has
112
         compile-and-go methods <code>evaluate()</code> and <code>evaluateSingle()</code> to execute
113
         an expression directly without going through an explicit compilation process. This provides
114
         a simpler approach if the expression is only evaluated once. The <code>XPathCompiler</code>
115
         also has the option of caching compiled expressions, so that if the same expression is
116
         evaluated repeatedly, the compiled form of the expression is re-used.</p>
117

    
118
      <p>Examples of the use of s9api to evaluate XPath expressions are included in the
119
            <code>saxon-resources</code> file, see module <code>S9APIExamples.java</code>.</p>
120
      
121
      <aside>
122
         <p>From Saxon 9.9, additional methods exploiting the Java 8 Streams API become
123
         available to navigate directly from <code>XdmNode</code> instances. In many cases these
124
         will be faster and more convenient than navigation using XPath. For example, instead
125
         of executing the XPath expression <code>.//chapter[@title='Introduction']</code>
126
         to find a specific element within a document, it is possible to use the Java expression
127
         <code>node.select(descendant("chapter").where(eq(attribute("title"),"Introduction)")).asNode()</code>.</p>
128
      </aside>
129
   </section>
130
   <section id="xdm-values" title="Representation of XDM values">
131
      <h1>Representation of XDM values</h1>
132
      
133
      <p>Values returned by XPath expressions in the s9api interface are represented as instances of the
134
         class <code java="net.sf.saxon.s9api.XdmValue">net.sf.saxon.s9api.XdmValue</code>.
135
      The <code>XdmValue</code> class is also used to supply parameters to stylesheets and transformations,
136
      and to return the results of XSLT or XQuery evaluation.</p>
137
      
138
      <p>The subclasses of <code>XdmValue</code> directly reflect the XDM model:</p>
139
      
140
      <samp><![CDATA[XdmValue (any sequence)
141
   XdmItem (any single item, that is, a sequence of length one)
142
      XdmNode (any node)
143
      XdmAtomicValue (any atomic value)
144
      XdmFunctionItem (a function item)
145
         XdmMap (a map)
146
         XdmArray (an array)
147
      XdmExternalObject (an item that encapsulates a Java or .NET object)   
148
   XdmEmptySequence (a sequence containing no items)      
149
]]></samp>
150
      
151
      <p>These objects are generally immutable.</p>
152
      
153
      <p>A variety of methods are provided to convert between these classes and "ordinary" Java equivalents. For example
154
      an <code>XdmAtomicValue</code> can be constructed directly from a Java <code>boolean</code>, <code>String</code>, <code>long</code>, 
155
         <code>BigDecimal</code>, or <code>Instant</code> (inter alia), and methods such as <code>getBooleanValue()</code>
156
      and <code>getStringValue()</code> are available to convert in the other direction.</p>
157
      
158
      <p>As an alternative to use of XPath, the <code>select()</code> method on <code>XdmValue</code> provides powerful
159
      navigation capability around XDM trees. The <code>select()</code> method takes as argument a
160
         <code java="net.sf.saxon.s9api.streams.Step">Step</code> (which is
161
         a function from one node to related nodes) and returns an <code
162
            java="net.sf.saxon.s9api.streams.XdmStream">XdmStream</code> of nodes as a result. There
163
         is a library (<code java="net.sf.saxon.s9api.streams.Steps">Steps</code>)
164
      of <code>Step</code> functions corresponding to all the XPath axes, and the results of applying a <code>Step</code>
165
         can be filtered using predicates: there is also a library (<code
166
            java="net.sf.saxon.s9api.streams.Predicates">Predicates</code>) of commonly-used
167
         <code>Predicate</code>s.</p>
168
      
169
      <p>For example, if <code>root</code> is a document node, then <code>root.select(descendant("p")).asXdmValue()</code>
170
      selects all the descendant elements with local name "p" in the form of an <code>XdmValue</code>.</p>
171
      
172
      <p>The <code java="net.sf.saxon.s9api.XdmNode">XdmNode</code> class in this hierarchy is implemented as a wrapper around the lower-level <code>NodeInfo</code>
173
      interface which provides more detailed access to information associated with nodes. The <code>NodeInfo</code> interface
174
      is designed primarily for internal use within Saxon, whereas <code>XdmNode</code> is designed for application use.</p>
175
   </section>
176
   <section id="jaxp-xpath" title="JAXP XPath API">
177
      <h1>JAXP XPath API</h1>
178

    
179

    
180
      <p>Saxon implements the JAXP 1.3 API for executing XPath expressions as defined in package
181
            <code>java.xml.xpath</code>, which is a standard part of the Java class library since
182
         JDK 1.5.</p>
183
      
184
      <aside>This is no longer the preferred API for executing XPath expressions from Java. The main reason
185
         is that it was designed with XPath 1.0 in mind; it has proved difficult to extend it to handle the
186
         vastly greater capabilities of XPath 2.0 or XPath 3.1. In addition, the types used for supplying
187
         parameters and returning results in JAXP provide a very low level of type safety. This can make
188
         applications hard to debug.
189
      </aside>
190
         
191
      <p>Three sample applications using this API are available: they are called
192
            <code>XPathExample.java</code>, <code>XPathExampleSA.java</code>, and
193
            <code>ApplyXPathJAXP.java</code>, and can be found in the <code>samples/java</code>
194
         directory after downloading the <code>saxon-resources</code> archive.</p>
195

    
196
      <p>To run the <code>XPathExample.java</code> application, see the instructions in <a
197
            class="bodylink" href="/samples/shakespeare">Shakespeare XPath Sample
198
         Application</a>.</p>
199

    
200
      <p>The <code>XPathExampleSA.java</code> application demonstrates use of schema-aware XPath. It
201
         is designed to be used with the files <code>books.xml</code> and <code>books.xsd</code> in
202
         the directory <code>samples/data</code>.</p>
203

    
204
      <p>The <code>ApplyXPathJAXP.java</code> application is an enhanced version of the class of the
205
         same name issued as a sample application in the JAXP 1.3 distribution. It has been enhanced
206
         to show the use of more advanced features, such as the ability to bind namespaces,
207
         variables, and functions, and also to demonstrate use of the XPath API with different
208
         object models.</p>
209

    
210
      <p>The XPath API in Saxon predates the introduction of the JAXP 1.3 XPath API, so it contains
211
         some facilities that are obsolescent (but most of the deprecated features were removed with
212
         effect from Saxon 9.6). However, there are also differences caused by the fact that Saxon
213
         supports XPath 2.0 (and higher), with its richer data model, whereas JAXP 1.3 operates only
214
         on XPath 1.0. </p>
215

    
216
      <p>The following sections describe use of the XPath API in more detail.</p>
217
      <nav>
218
         <ul/>
219
      </nav>
220

    
221
      <section id="factory" title="Selecting the XPath implementation">
222
         <h1>Selecting the XPath implementation</h1>
223
         
224
         <aside><p>The JAXP API is designed on the basis that when your application invokes
225
         <code>XPathFactory.newInstance()</code>, an XPath engine is selected by examining the values
226
         of system properties and searching the classpath. If you rely on this mechanism, then your
227
         application may end up running with an XPath engine on which it has never been tested. Since
228
         different XPath engines can differ in many significant respects (most notably, the version of
229
         XPath that they support), this can easily lead to application failures. Saxon therefore no
230
         longer identifies itself (in the JAR file manifest) as a JAXP XPath supplier. If you want
231
         to load Saxon as your XPath engine, you need to select it explicitly; it's not enough to just
232
         put it on the classpath.</p></aside>
233

    
234

    
235
         <p>An application using the JAXP 1.3 XPath API starts by instantiating a factory class.
236
            To use Saxon as your XPath engine, call:</p>
237
         <samp><![CDATA[XPathFactory xpathFactory = new net.sf.saxon.xpath.XPathFactoryImpl();
238
XPath xpath = xpathFactory.newXPath();
239
]]></samp>
240

    
241
 
242
         <p>If you want to use Saxon as your XPath implementation, you must instantiate the class <a
243
               class="javalink" href="net.sf.saxon.xpath.XPathFactoryImpl"
244
               >net.sf.saxon.xpath.XPathFactoryImpl</a> directly, rather than using the method 
245
            <code>XPathFactory.newInstance()</code> which relies on a classpath search. 
246
            If you want to take advantage of
247
            features in Saxon-PE (Professional Edition), use <a class="javalink"
248
               href="com.saxonica.config.ProfessionalXPathFactory"
249
               >com.saxonica.config.ProfessionalXPathFactory</a>, or for Saxon-EE (Enterprise
250
            Edition) use <a class="javalink" href="com.saxonica.config.EnterpriseXPathFactory"
251
               >com.saxonica.config.EnterpriseXPathFactory</a>.</p>
252

    
253
         <p>It is important to note that a compiled XPath expression can only be used with a source
254
            document that was built using the same Saxon <a class="javalink"
255
               href="net.sf.saxon.Configuration">Configuration</a>. When you create an
256
               <code>XPathFactory</code>, a Saxon <code>Configuration</code> is created
257
            automatically. You can extract this configuration and use it to build source documents.
258
            Alternatively, there is a constructor that allows you to create an
259
               <code>XPathFactory</code> that uses a preexisting <code>Configuration</code>.</p>
260

    
261
         <p>Saxon's implementation of <code>java.xml.xpath.XPath</code> is the class <a
262
               class="javalink" href="net.sf.saxon.xpath.XPathEvaluator"
263
               >net.sf.saxon.xpath.XPathEvaluator</a>. This class provides a few simple
264
            configuration interfaces to set the source document, the static context, and the context
265
            node, plus a number of methods for evaluating XPath expressions.</p>
266

    
267
         <p>The <code>XPath</code> object allows you to set the static context for evaluating XPath
268
            expressions (you can pre-declare namespaces, variables, and functions), and to compile
269
            XPath expressions in this context. A compiled XPath expression (an object of class
270
               <code>XPathExpression</code>) can then be evaluated, with a supplied node
271
            (represented by a class in the selected object model) supplied as the context node. For
272
            further details, see the Javadoc specifications and the supplied example applications
273
            (as described in <a class="bodylink" href="/xpath-api/jaxp-xpath">JAXP XPath
274
            API</a>).</p>
275
      </section>
276

    
277
      <section id="context-node" title="Setting the context item">
278
         <h1>Setting the context item</h1>
279

    
280

    
281
         <p>Many of the methods in the JAXP interface take an argument to represent the context
282
            node. Because the API is designed to be used with multiple object models, this is typed
283
            simply as an <code>Object</code>. In the case of Saxon, this can be an object in any of
284
            the supported data models: DOM, JDOM, DOM4J, XOM, or Saxon's native <a class="javalink"
285
               href="net.sf.saxon.om.NodeInfo">NodeInfo</a> representation. Note that if a
286
               <code>NodeInfo</code> is supplied, the tree must have been constructed using the same
287
            Saxon <a class="javalink" href="net.sf.saxon.Configuration">Configuration</a> as
288
            the one used by the <a class="javalink" href="net.sf.saxon.xpath.XPathEvaluator"
289
               >XPathEvaluator</a> itself.</p>
290

    
291
         <p>It is also possible to supply an atomic value as the context item. This must be supplied
292
            as an implementation of the Saxon <a class="javalink"
293
               href="net.sf.saxon.value.AtomicValue">AtomicValue</a> class; no conversion is
294
            attempted.</p>
295

    
296
         <p>Many of these methods specify that if the context node supplied is null, the XPath
297
            expression will be evaluated using an empty document node as the context node. Saxon
298
            does not implement this rule. There are two reasons for this. Firstly, it's unnatural in
299
            XPath 2.0, where it is permissible for the context item for an expression to be
300
            undefined. Secondly, it's not clear what kind of document node it would be appropriate
301
            to create, given that Saxon supports multiple object models. Instead, if null is
302
            supplied, the expression is evaluated with the context item undefined (which will cause
303
            a dynamic error if the expression actually refers to the context item).</p>
304
      </section>
305

    
306
      <section id="return-types" title="Return types">
307
         <h1>Return types</h1>
308

    
309

    
310
         <p>The JAXP specification leaves it rather up to the implementation how the results of an
311
            XPath expression will be returned. This is partly because it is defined only for XPath
312
            1.0, which has a much simpler type system, and partly because it is deliberately
313
            designed to be independent of the object model used to represent XML trees.</p>
314

    
315
         <ul>
316
            <li>
317
               <p>If you specify the return type <code>XPathConstants.BOOLEAN</code> then Saxon will
318
                  return the effective boolean value of the expression, as a
319
                     <code>java.lang.Boolean</code>. This is the same as wrapping the expression in
320
                  a call of the XPath <a class="bodylink code" href="/functions/fn/boolean"
321
                     >boolean()</a> function.</p>
322
            </li>
323
            <li>
324
               <p>If you specify the return type <code>XPathConstants.STRING</code> then Saxon will
325
                  return the result of the expression converted to a string, as a
326
                     <code>java.lang.String</code>. This is the same as wrapping the expression in a
327
                  call of the XPath <a class="bodylink code" href="/functions/fn/string"
328
                     >string()</a> function.</p>
329
            </li>
330
            <li>
331
               <p>If you specify the return type <code>XPathConstants.NUMBER</code> then Saxon will
332
                  return the result of the expression converted to a double as a
333
                     <code>java.lang.Double</code>. This is the same as wrapping the expression in a
334
                  call of the XPath <a class="bodylink code" href="/functions/fn/number"
335
                     >number()</a> function.</p>
336
            </li>
337
            <li>
338
               <p>If you specify the return type <code>XPathConstants.NODE</code> then Saxon will
339
                  return the result the result as a node object in the selected object model. With
340
                  the DOM model this will be an instance of <code>org.w3.dom.Node</code>, with the
341
                  native Saxon model it will be an instance of
342
                  <code>net.sf.saxon.om.NodeInfo</code>, and so on.</p>
343
            </li>
344
            <li>
345
               <p>If the return type is <code>XPathConstants.NODESET</code>, the result will in
346
                  general be a Java <code>List</code> containing node objects in the selected object
347
                  model. It may also contain non-node objects if that's what the XPath expression
348
                  returned. As a special case, if the supplied context node is a DOM node, and if
349
                  the results are all DOM nodes, then they will be returned in the form of a DOM
350
                     <code>NodeList</code> object.</p>
351
            </li>
352
         </ul>
353

    
354
         <p>Saxon does not recognize additional values for the return type other than the values
355
            defined in JAXP. If you want to return a different result type, for example a list of
356
            integers or a date, then it is probably best not to use this API; if you must, however,
357
            then use one of the methods in which the result type is unspecified. If any conversions
358
            are necessary, do them within the XPath expression itself, using casts or constructor
359
            functions. The Java object that is returned will be a representation of the XPath value,
360
            converted in the same way as arguments to a extension functions.</p>
361
      </section>
362

    
363
      <section id="saxon-additions" title="Additional Saxon methods">
364
         <h1>Additional Saxon methods</h1>
365

    
366

    
367
         <p>Saxon's implementation of <code>XPathExpression</code> (namely <a class="javalink"
368
               href="net.sf.saxon.xpath.XPathExpressionImpl"
369
               >net.sf.saxon.xpath.XPathExpressionImpl</a>) provides additional methods for
370
            evaluating the XPath expression. In particular the <code>iterate()</code> method
371
            returns a Saxon <a class="javalink"
372
               href="net.sf.saxon.om.SequenceIterator">SequenceIterator</a> which allows the
373
            application to process the results of any XPath expression, with no conversion: all
374
            values will be represented using a native Saxon class, for example a node will be
375
            represented as a <a class="javalink" href="net.sf.saxon.om.NodeInfo">NodeInfo</a> and a
376
            QName as a <a class="javalink" href="net.sf.saxon.value.QNameValue">QNameValue</a>. The
377
               <code>NodeInfo</code> interface is described in the next section, <a class="bodylink"
378
               href="/xpath-api/nodeinfo">NodeInfo interface</a>.</p>
379

    
380
         <p>You can call methods directly on the <a class="javalink" href="net.sf.saxon.om.NodeInfo"
381
               >NodeInfo</a> object to get information about a node: for example
382
               <code>getDisplayName()</code> gets the name of the node in a form suitable for
383
            display, and <code>getStringValue()</code> gets the string value of the node, as defined
384
            in the XPath data model. You can also use the node as the context node for evaluation of
385
            subsequent expressions.</p>
386
      </section>
387

    
388
      <section id="jaxp-xpath-extension-functions" title="Calling JAXP XPath extension functions">
389
         <h1>Calling JAXP XPath extension functions</h1>
390

    
391

    
392
         <p>The JAXP XPath interface includes an interface <code>FunctionResolver</code> which can
393
            be used to bind a function call appearing in the XPath expression to a user-written Java
394
            implementation of the interface <code>java.xml.xpath.XPathFunction</code>. The form in
395
            which parameters are passed to such a function, and the form in which it returns its
396
            results, are not precisely defined in the JAXP specification, so this section fills the
397
            gap. Note that the calling conventions are likely to differ from those used by other
398
            products.</p>
399

    
400
         <p>The extension function is called by invoking the method
401
               <code>XPathFunction.evaluate()</code>, which takes a list of arguments, and returns
402
            the function result.</p>
403

    
404
         <p>The arguments are therefore supplied as a list. Each item in this list represents one
405
            argument. The argument value is represented as follows:</p>
406
         <ol>
407
            <li>
408
               <p>If the value of the argument is a singleton item, it will be passed as the
409
                  "natural Java equivalent" of the item's type. For example, a double will be passed
410
                  as an instance of <code>java.lang.Double</code>, a string as an instance of
411
                     <code>java.lang.String</code>. An untyped atomic value is treated as a string.
412
                  An <code>xs:integer</code> (even if it belongs to a subtype such as
413
                     <code>xs:short</code>) is converted to a <code>java.lang.BigInteger</code>. The
414
                  more specialized XML Schema primitive types such as <code>xs:hexBinary</code> and
415
                     <code>xs:duration</code> are passed in their native Saxon representation (a
416
                  subclass of <a class="javalink" href="net.sf.saxon.value.AtomicValue"
417
                     >net.sf.saxon.value.AtomicValue</a>). A node will be passed as an instance of
418
                     <a class="javalink" href="net.sf.saxon.om.NodeInfo">net.sf.saxon.om.NodeInfo</a>,
419
                  unless it wraps a foreign node (e.g. a DOM or JDOM node) in which case the foreign
420
                  node is passed.</p>
421
            </li>
422
            <li>
423
               <p>If the value is a sequence of any length other than one (including zero), then the
424
                  value that is passed is a <code>List</code>, where each item in the list is
425
                  converted as described in rule (1).</p>
426
            </li>
427
         </ol>
428

    
429
         <p>If the return value conforms to the above conventions, then it will be accepted. However
430
            Saxon will also accept a wide range of other return values, including of course a
431
               <code>List</code> containing one item.</p>
432
      </section>
433
   </section>
434
   
435
   
436
   <section id="nodeinfo" title="NodeInfo interface">
437
      <h1>NodeInfo interface</h1>
438

    
439

    
440
      <p>The <a class="javalink" href="net.sf.saxon.om.NodeInfo">NodeInfo</a> object represents a
441
         node of an XML document. The methods on this class follow the XPath data
442
         model closely.</p>
443
      
444
      <aside>The <code>NodeInfo</code> interface is classified as part of Saxon's <i>system programming interface</i>
445
      which means it is available for use by applications that require a close level of integration with Saxon, but
446
      it is not guaranteed to be 100% stable between releases. For a higher level of stability, use the 
447
         <a class="javalink" href="net.sf.saxon.s9api.XdmNode">XdmNode</a> interface.</aside>
448

    
449
      
450
      <p>The <a class="javalink" href="net.sf.saxon.om.NodeInfo">NodeInfo</a> object provides the
451
         application with information about the node. The most commonly used methods include:</p>
452
      <table>
453
         <tr>
454
            <td>
455
               <p>getNodeKind()</p>
456
            </td>
457
            <td>
458
               <p>Gets a <code>short</code> identifying the node type (for example, element or
459
                  attribute). The values are consistent with those used in the DOM, and are
460
                  referenced by constants in the class <a class="javalink"
461
                     href="net.sf.saxon.type.Type">net.sf.saxon.type.Type</a>. </p>
462
            </td>
463
         </tr>
464
         <tr>
465
            <td>
466
               <p>getDisplayName(), getLocalPart(), getPrefix(), getURI()</p>
467
            </td>
468
            <td>
469
               <p>These methods get the name of the element, or its various parts. The
470
                     <code>getDisplayName()</code> method returns the QName as used in the original
471
                  source XML.</p>
472
            </td>
473
         </tr>
474
         <tr>
475
            <td>
476
               <p>getAttributeValue()</p>
477
            </td>
478
            <td>
479
               <p>Gets the value of a specified attribute, as a <code>String</code>.</p>
480
            </td>
481
         </tr>
482
         <tr>
483
            <td>
484
               <p>getStringValue()</p>
485
            </td>
486
            <td>
487
               <p>Gets the string value of a node, as defined in the XPath data model.</p>
488
            </td>
489
         </tr>
490
         <tr>
491
            <td>
492
               <p>atomize()</p>
493
            </td>
494
            <td>
495
               <p>Gets the typed value of a node, as defined in the XPath 2.0 data model. This is in
496
                  general a sequence of atomic values, so the result is a <a class="javalink"
497
                     href="net.sf.saxon.om.AtomicSequence">AtomicSequence</a>. In most
498
               cases the typed value will either be a single atomic value or an empty sequence;
499
               a single atomic value will be represented using class 
500
                  <a class="javalink" href="net.sf.saxon.value.AtomicValue">AtomicValue</a>
501
               (which implements <code>AtomicSequence</code>) or one of its subclasses such as
502
                  <a class="javalink" href="net.sf.saxon.value.StringValue">StringValue</a>. 
503
                  An empty sequence is best recognized by calling
504
               <code>atomicSequence.getLength() == 0</code>.</p>
505
            </td>
506
         </tr>
507
         <tr>
508
            <td>
509
               <p>getParent()</p>
510
            </td>
511
            <td>
512
               <p>Gets the <a class="javalink" href="net.sf.saxon.om.NodeInfo">NodeInfo</a>
513
                  representing the parent element.</p>
514
            </td>
515
         </tr>
516
         <tr>
517
            <td>
518
               <p>iterateAxis()</p>
519
            </td>
520
            <td>
521
               <p>Returns an <a class="javalink" href="net.sf.saxon.tree.iter.AxisIterator"
522
                     >AxisIterator</a> object that can be used to iterate over the nodes on any
523
                  of the XPath axes. The first argument is an integer identifying the axis; the
524
                  second is a <a class="javalink" href="net.sf.saxon.pattern.NodeTest">NodeTest</a>
525
                  (a simple form of pattern) which can be used to filter the nodes on the axis.
526
                  Supply <code>null</code> if you want all the nodes on the axis.</p>
527
            </td>
528
         </tr>
529
      </table>
530

    
531
      <p>For other methods, see the <a class="javalink" href="net.sf.saxon.om.NodeInfo">NodeInfo</a>
532
         JavaDoc documentation.</p>
533

    
534
      <p>It is possible (though not easy) to provide your own implementation of the
535
            <code>NodeInfo</code> interface, perhaps allowing Saxon queries to run directly against
536
         some non-XML data source. There are helper methods in the <a class="javalink"
537
            href="net.sf.saxon.tree.util.Navigator">net.sf.saxon.tree.util.Navigator</a> class that
538
         reduce the amount of code you need to write to achieve this. See the implementations that
539
         map <code>NodeInfo</code> to DOM, DOM4J, JDOM or XOM to see how it is done.</p>
540
   </section>
541
</article>
(21-21/21)