NodeInfo


1   package net.sf.saxon.om;
2   import net.sf.saxon.Configuration;
3   import net.sf.saxon.value.Value;
4   import net.sf.saxon.event.Receiver;
5   import net.sf.saxon.pattern.NodeTest;
6   import net.sf.saxon.trans.XPathException;
7   
8   import javax.xml.transform.Source  ;
9   
10  /**
11   * The NodeInfo interface represents a node in Saxon's implementation of the XPath 2.0 data model.
12   * <p>
13   * Note that several NodeInfo objects may represent the same node. To test node identity, the
14   * method {@link #isSameNodeInfo(NodeInfo)} should be used. An exception to this rule applies for
15   * document nodes, where the correspondence between document nodes and DocumentInfo objects is one to
16   * one. NodeInfo objects are never reused: a given NodeInfo object represents the same node for its entire
17   * lifetime.
18   * <p>
19   * This is the primary interface for accessing trees in Saxon, and it forms part of the public
20   * Saxon API. The only subclass of NodeInfo that applications should normally use is {@link DocumentInfo},
21   * which represents a document node. Methods that form part of the public API are (since Saxon 8.4)
22   * labelled with a JavaDoc "since" tag: classes and methods that have no such label should not be
23   * regarded as stable interfaces.
24   * <p>
25   * The interface represented by this class is at a slightly higher level than the abstraction described
26   * in the W3C data model specification, in that it includes support for the XPath axes, rather than exposing
27   * the lower-level properties (such as "parent" and "children") directly. All navigation within trees,
28   * except for a few convenience methods, is done by following the axes using the {@link #iterateAxis} method.
29   * This allows different implementations of the XPath tree model to implement axis navigation in different ways.
30   * Some implementations may choose to use the helper methods provided in class {@link Navigator}.
31   * <p>
32   * Note that the stability of this interface applies to classes that use the interface,
33   * not to classes that implement it. The interface may be extended in future to add new methods.
34   *
35   * @author Michael H. Kay
36   * @since 8.4
37   */
38  
39  public interface NodeInfo extends Source  , Item, ValueRepresentation {
40  
41      int[] EMPTY_NAMESPACE_LIST = new int[0];
42  
43      /**
44       * Get the kind of node. This will be a value such as {@link net.sf.saxon.type.Type#ELEMENT}
45       * or {@link net.sf.saxon.type.Type#ATTRIBUTE}. There are seven kinds of node: documents, elements, attributes,
46       * text, comments, processing-instructions, and namespaces.
47       *
48       * @return an integer identifying the kind of node. These integer values are the
49       * same as those used in the DOM
50       * @see net.sf.saxon.type.Type
51       * @since 8.4
52       */
53  
54      public int getNodeKind();
55  
56      /**
57       * Determine whether this is the same node as another node.
58       * <p>
59       * Note that two different NodeInfo instances can represent the same conceptual node.
60       * Therefore the "==" operator should not be used to test node identity. The equals()
61       * method is not overridden for nodes, so it has the same effect as using "==".
62       * <p>
63       * Note: a.isSameNodeInfo(b) if and only if generateId(a)==generateId(b).
64       * <p>
65       * This method has the same semantics as isSameNode() in DOM Level 3, but
66       * works on Saxon NodeInfo objects rather than DOM Node objects.
67       *
68       * @param other the node to be compared with this node
69       * @return true if this NodeInfo object and the supplied NodeInfo object represent
70       *      the same node in the tree.
71       */
72  
73      public boolean isSameNodeInfo(NodeInfo other);
74  
75      /**
76       * Get the System ID for the node. Note this is not the
77       * same as the base URI: the base URI can be modified by xml:base, but
78       * the system ID cannot. The base URI is used primarily for resolving
79       * relative URIs within the content of the document. The system ID is
80       * used primarily in conjunction with a line number, for identifying the
81       * location of elements within the source XML, in particular when errors
82       * are found.
83       *
84       * @return the System Identifier of the entity in the source document
85       * containing the node, or null if not known.
86       * @since 8.4
87       */
88  
89      public String   getSystemId();
90  
91      /**
92       * Get the Base URI for the node, that is, the URI used for resolving a relative URI contained
93       * in the node. This will be the same as the System ID unless xml:base has been used. Where the
94       * node does not have a base URI of its own, the base URI of its parent node is returned.
95       *
96       * @return the base URI of the node. This may be null if the base URI is unknown.
97       * @since 8.4
98       */
99  
100     public String   getBaseURI();
101 
102     /**
103      * Get line number. Line numbers are not maintained by default, except for
104      * stylesheets and schema documents. Line numbering can be requested using the
105      * -l option on the command line, or by setting options on the TransformerFactory
106      * or the Configuration before the source document is built.
107      * <p>
108      * The granularity of line numbering is normally the element level: for other nodes
109      * such as text nodes and attributes, the line number of the parent element will normally be returned.
110      * <p>
111      * In the case of a tree constructed by taking input from a SAX parser, the line number will reflect the
112      * SAX rules: that is, the line number of an element is the line number where the start tag ends. This
113      * may be a little confusing where elements have many attributes spread over multiple lines, or where
114      * single attributes (as can easily happen with XSLT 2.0 stylesheets) occupy several lines.
115      * <p>
116      * In the case of a tree constructed by a stylesheet or query, the line number may reflect the line in
117      * the stylesheet or query that caused the node to be constructed.
118      * <p>
119      * The line number can be read from within an XPath expression using the Saxon extension function
120      * saxon:line-number()
121      *
122      * @return the line number of the node in its original source document; or
123      *      -1 if not available
124      * @since 8.4
125      */
126 
127     public int getLineNumber();
128 
129     /**
130      * Determine the relative position of this node and another node, in document order.
131      * <p>
132      * The other node must always be in the same tree; the effect of calling this method
133      * when the two nodes are in different trees is undefined. To obtain a global ordering
134      * of nodes, the application should first compare the result of getDocumentNumber(),
135      * and only if the document number is the same should compareOrder() be called.
136      *
137      * @param other The other node, whose position is to be compared with this
138      *      node
139      * @return -1 if this node precedes the other node, +1 if it follows the
140      *     other node, or 0 if they are the same node. (In this case,
141      *     isSameNode() will always return true, and the two nodes will
142      *     produce the same result for generateId())
143      * @since 8.4
144      */
145 
146     public int compareOrder(NodeInfo other);
147 
148     /**
149      * Return the string value of the node. This is normally the string value as defined in
150      * the XPath data model, except that no distinction is made between strings and untyped atomic values.
151      * <p>
152      * The interpretation of this depends on the type
153      * of node. For an element it is the accumulated character content of the element,
154      * including descendant elements.
155      * <p>
156      * This method returns the string value as if the node were untyped. Unlike the string value
157      * accessor in the XPath 2.0 data model, it does not report an error if the element has a complex
158      * type, instead it returns the concatenation of the descendant text nodes as it would if the element
159      * were untyped.
160      *
161      * @return the string value of the node
162      * @since 8.4
163      */
164 
165     public String   getStringValue();
166 
167     /**
168      * Get name code. The name code is a coded form of the node name: two nodes
169      * with the same name code have the same namespace URI, the same local name,
170      * and the same prefix. By masking the name code with {@link NamePool#FP_MASK}, you get a
171      * fingerprint: two nodes with the same fingerprint have the same local name
172      * and namespace URI.
173      *
174      * @return an integer name code, which may be used to obtain the actual node
175      *     name from the name pool. For unnamed nodes (text nodes, comments, document nodes,
176      *     and namespace nodes for the default namespace), returns -1.
177      * @see net.sf.saxon.om.NamePool#allocate allocate
178      * @see net.sf.saxon.om.NamePool#getFingerprint getFingerprint
179      * @since 8.4
180      */
181 
182     public int getNameCode();
183 
184     /**
185      * Get fingerprint. The fingerprint is a coded form of the expanded name
186      * of the node: two nodes
187      * with the same name code have the same namespace URI and the same local name.
188      * The fingerprint contains no information about the namespace prefix. For a name
189      * in the null namespace, the fingerprint is the same as the name code.
190      *
191      * @return an integer fingerprint; two nodes with the same fingerprint have
192      *     the same expanded QName. For unnamed nodes (text nodes, comments, document nodes,
193      *     and namespace nodes for the default namespace), returns -1.
194      * @since 8.4
195      */
196 
197     public int getFingerprint();
198 
199     /**
200      * Get the local part of the name of this node. This is the name after the ":" if any.
201      *
202      * @return the local part of the name. For an unnamed node, returns "". Unlike the DOM
203      * interface, this returns the full name in the case of a non-namespaced name.
204      * @since 8.4
205      */
206 
207     public String   getLocalPart();
208 
209     /**
210      * Get the URI part of the name of this node. This is the URI corresponding to the
211      * prefix, or the URI of the default namespace if appropriate.
212      *
213      * @return The URI of the namespace of this node. For an unnamed node,
214      *     or for a node with an empty prefix, returns an empty
215      *     string.
216      * @since 8.4
217      */
218 
219     public String   getURI();
220 
221     /**
222      * Get the display name of this node, in the form of a lexical QName.
223      * For elements and attributes this is [prefix:]localname.
224      * For unnamed nodes, it is an empty string.
225      *
226      * @return The display name of this node. For a node with no name, returns
227      *     an empty string.
228      * @since 8.4
229      */
230 
231     public String   getDisplayName();
232 
233     /**
234      * Get the prefix of the name of the node. This is defined only for elements and attributes.
235      * If the node has no prefix, or for other kinds of node, returns a zero-length string.
236      * @return The prefix of the name of the node.
237      * @since 8.4
238      */
239 
240     public String   getPrefix();
241 
242     /**
243      * Get the configuration used to build the tree containing this node.
244      * @return the Configuration
245      * @since 8.4
246      */
247 
248     public Configuration getConfiguration();
249 
250    /**
251     * Get the NamePool that holds the namecode for this node
252     * @return the namepool
253     * @since 8.4
254     */
255 
256     public NamePool getNamePool();
257 
258     /**
259      * Get the type annotation of this node, if any. The type annotation is represented as an integer;
260      * this is the fingerprint of the name of the type, as defined in the name pool. Anonymous types
261      * are given a system-defined name. The value of the type annotation can be used to retrieve the
262      * actual schema type definition using the method {@link Configuration#getSchemaType}.
263      * <p>
264      * The bit IS_DTD_TYPE (1<<30) will be set in the case of an attribute node if the type annotation
265      * is one of ID, IDREF, or IDREFS and this is derived from DTD rather than schema validation.
266      *
267      * @return the type annotation of the node, under the mask NamePool.FP_MASK, and optionally the
268      * bit setting IS_DTD_TYPE in the case of a DTD-derived ID or IDREF/S type (which is treated
269      * as untypedAtomic for the purposes of obtaining the typed value).
270      * Returns -1 for kinds of nodes that have no annotation, and for elements annotated as
271      * untyped, and attributes annotated as untypedAtomic.
272      * @since 8.4
273      */
274 
275     public int getTypeAnnotation();
276 
277     /**
278      * Bit setting in the returned type annotation indicating a DTD_derived type on an attribute node
279      */
280 
281     public static int IS_DTD_TYPE = 1<<30;
282 
283     /**
284      * Get the typed value. The result of this method will always be consistent with the method
285      * {@link Item#getTypedValue()}. However, this method is often more convenient and may be
286      * more efficient, especially in the common case where the value is expected to be a singleton.
287      * @return the typed value. This will either be a single AtomicValue or a Value whose items are
288      * atomic values.
289      * @since 8.5
290      */
291 
292     public Value atomize() throws XPathException;
293 
294     /**
295      * Get the NodeInfo object representing the parent of this node
296      *
297      * @return the parent of this node; null if this node has no parent
298      * @since 8.4
299      */
300 
301     public NodeInfo getParent();
302 
303     /**
304      * Return an iteration over all the nodes reached by the given axis from this node
305      *
306      * @exception UnsupportedOperationException if the namespace axis is
307      *     requested and this axis is not supported for this implementation.
308      * @param axisNumber an integer identifying the axis; one of the constants
309      *      defined in class {@link net.sf.saxon.om.Axis}
310      * @return an AxisIterator that scans the nodes reached by the axis in
311      *     turn.
312      * @see net.sf.saxon.om.Axis
313      * @since 8.4
314      */
315 
316     public AxisIterator iterateAxis(byte axisNumber);
317 
318 
319     /**
320      * Return an iteration over all the nodes reached by the given axis from this node
321      * that match a given NodeTest
322      *
323      * @exception UnsupportedOperationException if the namespace axis is
324      *     requested and this axis is not supported for this implementation.
325      * @param axisNumber an integer identifying the axis; one of the constants
326      *      defined in class {@link net.sf.saxon.om.Axis}
327      * @param nodeTest A pattern to be matched by the returned nodes; nodes
328      * that do not match this pattern are not included in the result
329      * @return a NodeEnumeration that scans the nodes reached by the axis in
330      *     turn.
331      * @see net.sf.saxon.om.Axis
332      * @since 8.4
333      */
334 
335     public AxisIterator iterateAxis(byte axisNumber, NodeTest nodeTest);
336 
337     /**
338      * Get the string value of a given attribute of this node
339      *
340      * @param fingerprint The fingerprint of the attribute name
341      * @return the attribute value if it exists, or null if it does not exist. Always returns null
342      * if this node is not an element.
343      * @since 8.4
344      */
345 
346     public String   getAttributeValue(int fingerprint);
347 
348     /**
349      * Get the root node of the tree containing this node
350      *
351      * @return the NodeInfo representing the top-level ancestor of this node.
352      *     This will not necessarily be a document node. If this node has no parent,
353      *     then the method returns this node.
354      * @since 8.4
355      */
356 
357     public NodeInfo getRoot();
358 
359     /**
360      * Get the root node, if it is a document node.
361      *
362      * @return the DocumentInfo representing the containing document. If this
363      *     node is part of a tree that does not have a document node as its
364      *     root, returns null.
365      * @since 8.4
366      */
367 
368     public DocumentInfo getDocumentRoot();
369 
370     /**
371      * Determine whether the node has any children.
372      * <p>
373      * Note: the result is equivalent to <br />
374      * <code>iterateAxis(Axis.CHILD).next() != null</code>
375      *
376      * @return True if the node has one or more children
377      * @since 8.4
378      */
379 
380     public boolean hasChildNodes();
381 
382     /**
383      * Get a character string that uniquely identifies this node.
384      * Note: a.isSameNode(b) if and only if generateId(a)==generateId(b)
385      *
386      * @return a string that uniquely identifies this node, across all
387      *     documents. (Changed in Saxon 7.5. Previously this method returned
388      *     an id that was unique within the current document, and the calling
389      *     code prepended a document id).
390      * @since 8.4
391      */
392 
393     public String   generateId();
394 
395     /**
396      * Get the document number of the document containing this node. For a free-standing
397      * orphan node, just return the hashcode.
398      * @since 8.4
399      */
400 
401     public int getDocumentNumber();
402 
403     /**
404      * Copy this node to a given outputter.
405      * <p>
406      * This method is primarily for internal use. It should not be considered a stable
407      * part of the Saxon API.
408      *
409      * @exception XPathException
410      * @param out the Receiver to which the node should be copied
411      * @param whichNamespaces in the case of an element, controls
412      *     which namespace nodes should be copied. Values are {@link #NO_NAMESPACES},
413      *     {@link #LOCAL_NAMESPACES}, {@link #ALL_NAMESPACES}
414      * @param copyAnnotations indicates whether the type annotations
415      *     of element and attribute nodes should be copied
416      * @param locationId If non-zero, identifies the location of the instruction
417      *     that requested this copy. If zero, indicates that the location information
418      *     for the original node is to be copied; in this case the Receiver must be
419      *     a LocationCopier
420      */
421 
422     public void copy(Receiver out, int whichNamespaces, boolean copyAnnotations, int locationId) throws XPathException;
423 
424     /**
425      * Don't copy any namespace nodes.
426      */
427 
428     int NO_NAMESPACES = 0;
429 
430     /**
431      * Copy namespaces declared (or undeclared) on this element, but not namespaces inherited from a parent element
432      */
433     int LOCAL_NAMESPACES = 1;
434 
435     /**
436      * Copy all in-scope namespaces
437      */
438     int ALL_NAMESPACES = 2;
439 
440     /**
441      * Output all namespace declarations associated with this element. Does nothing if
442      * the node is not an element.
443      * <p>
444      * This method is primarily for internal use. It should not be considered a stable part of the
445      * Saxon API.
446      *
447      * @param out The relevant Receiver
448      * @param includeAncestors True if namespaces declared on ancestor
449      *     elements must be output; false if it is known that these are
450      *
451      */
452 
453     public void sendNamespaceDeclarations(Receiver out, boolean includeAncestors)
454         throws XPathException;
455 
456     /**
457      * Get all namespace undeclarations and undeclarations defined on this element.
458      * <p>
459      * This method is intended primarily for internal use. User applications needing
460      * information about the namespace context of a node should use <code>iterateAxis(Axis.NAMESPACE)</code>.
461      *
462      * @param buffer If this is non-null, and the result array fits in this buffer, then the result
463      * may overwrite the contents of this array, to avoid the cost of allocating a new array on the heap.
464      * @return An array of integers representing the namespace declarations and undeclarations present on
465      * this element. For a node other than an element, return null. Otherwise, the returned array is a
466      * sequence of namespace codes, whose meaning may be interpreted by reference to the name pool. The
467      * top half word of each namespace code represents the prefix, the bottom half represents the URI.
468      * If the bottom half is zero, then this is a namespace undeclaration rather than a declaration.
469      * The XML namespace is never included in the list. If the supplied array is larger than required,
470      * then the first unused entry will be set to -1.
471      * <p>
472      * For a node other than an element, the method returns null.</p>
473      */
474 
475     public int[] getDeclaredNamespaces(int[] buffer);
476 
477 }
478 
479 //
480 // The contents of this file are subject to the Mozilla Public License Version 1.0 (the "License");
481 // you may not use this file except in compliance with the License. You may obtain a copy of the
482 // License at http://www.mozilla.org/MPL/
483 //
484 // Software distributed under the License is distributed on an "AS IS" basis,
485 // WITHOUT WARRANTY OF ANY KIND, either express or implied.
486 // See the License for the specific language governing rights and limitations under the License.
487 //
488 // The Original Code is: all this file.
489 //
490 // The Initial Developer of the Original Code is Michael H. Kay.
491 //
492 // Portions created by (your name) are Copyright (C) (your legal entity). All Rights Reserved.
493 //
494 // Contributor(s): none.
495 //
496
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags