001: package net.sf.saxon.om;
002:
003: import net.sf.saxon.Configuration;
004: import net.sf.saxon.value.Value;
005: import net.sf.saxon.event.Receiver;
006: import net.sf.saxon.pattern.NodeTest;
007: import net.sf.saxon.trans.XPathException;
008:
009: import javax.xml.transform.Source;
010:
011: /**
012: * The NodeInfo interface represents a node in Saxon's implementation of the XPath 2.0 data model.
013: * <p>
014: * Note that several NodeInfo objects may represent the same node. To test node identity, the
015: * method {@link #isSameNodeInfo(NodeInfo)} should be used. An exception to this rule applies for
016: * document nodes, where the correspondence between document nodes and DocumentInfo objects is one to
017: * one. NodeInfo objects are never reused: a given NodeInfo object represents the same node for its entire
018: * lifetime.
019: * <p>
020: * This is the primary interface for accessing trees in Saxon, and it forms part of the public
021: * Saxon API. The only subclass of NodeInfo that applications should normally use is {@link DocumentInfo},
022: * which represents a document node. Methods that form part of the public API are (since Saxon 8.4)
023: * labelled with a JavaDoc "since" tag: classes and methods that have no such label should not be
024: * regarded as stable interfaces.
025: * <p>
026: * The interface represented by this class is at a slightly higher level than the abstraction described
027: * in the W3C data model specification, in that it includes support for the XPath axes, rather than exposing
028: * the lower-level properties (such as "parent" and "children") directly. All navigation within trees,
029: * except for a few convenience methods, is done by following the axes using the {@link #iterateAxis} method.
030: * This allows different implementations of the XPath tree model to implement axis navigation in different ways.
031: * Some implementations may choose to use the helper methods provided in class {@link Navigator}.
032: * <p>
033: * Note that the stability of this interface applies to classes that use the interface,
034: * not to classes that implement it. The interface may be extended in future to add new methods.
035: *
036: * @author Michael H. Kay
037: * @since 8.4
038: */
039:
040: public interface NodeInfo extends Source, Item, ValueRepresentation {
041:
042: int[] EMPTY_NAMESPACE_LIST = new int[0];
043:
044: /**
045: * Get the kind of node. This will be a value such as {@link net.sf.saxon.type.Type#ELEMENT}
046: * or {@link net.sf.saxon.type.Type#ATTRIBUTE}. There are seven kinds of node: documents, elements, attributes,
047: * text, comments, processing-instructions, and namespaces.
048: *
049: * @return an integer identifying the kind of node. These integer values are the
050: * same as those used in the DOM
051: * @see net.sf.saxon.type.Type
052: * @since 8.4
053: */
054:
055: public int getNodeKind();
056:
057: /**
058: * Determine whether this is the same node as another node.
059: * <p>
060: * Note that two different NodeInfo instances can represent the same conceptual node.
061: * Therefore the "==" operator should not be used to test node identity. The equals()
062: * method is not overridden for nodes, so it has the same effect as using "==".
063: * <p>
064: * Note: a.isSameNodeInfo(b) if and only if generateId(a)==generateId(b).
065: * <p>
066: * This method has the same semantics as isSameNode() in DOM Level 3, but
067: * works on Saxon NodeInfo objects rather than DOM Node objects.
068: *
069: * @param other the node to be compared with this node
070: * @return true if this NodeInfo object and the supplied NodeInfo object represent
071: * the same node in the tree.
072: */
073:
074: public boolean isSameNodeInfo(NodeInfo other);
075:
076: /**
077: * Get the System ID for the node. Note this is not the
078: * same as the base URI: the base URI can be modified by xml:base, but
079: * the system ID cannot. The base URI is used primarily for resolving
080: * relative URIs within the content of the document. The system ID is
081: * used primarily in conjunction with a line number, for identifying the
082: * location of elements within the source XML, in particular when errors
083: * are found.
084: *
085: * @return the System Identifier of the entity in the source document
086: * containing the node, or null if not known.
087: * @since 8.4
088: */
089:
090: public String getSystemId();
091:
092: /**
093: * Get the Base URI for the node, that is, the URI used for resolving a relative URI contained
094: * in the node. This will be the same as the System ID unless xml:base has been used. Where the
095: * node does not have a base URI of its own, the base URI of its parent node is returned.
096: *
097: * @return the base URI of the node. This may be null if the base URI is unknown.
098: * @since 8.4
099: */
100:
101: public String getBaseURI();
102:
103: /**
104: * Get line number. Line numbers are not maintained by default, except for
105: * stylesheets and schema documents. Line numbering can be requested using the
106: * -l option on the command line, or by setting options on the TransformerFactory
107: * or the Configuration before the source document is built.
108: * <p>
109: * The granularity of line numbering is normally the element level: for other nodes
110: * such as text nodes and attributes, the line number of the parent element will normally be returned.
111: * <p>
112: * In the case of a tree constructed by taking input from a SAX parser, the line number will reflect the
113: * SAX rules: that is, the line number of an element is the line number where the start tag ends. This
114: * may be a little confusing where elements have many attributes spread over multiple lines, or where
115: * single attributes (as can easily happen with XSLT 2.0 stylesheets) occupy several lines.
116: * <p>
117: * In the case of a tree constructed by a stylesheet or query, the line number may reflect the line in
118: * the stylesheet or query that caused the node to be constructed.
119: * <p>
120: * The line number can be read from within an XPath expression using the Saxon extension function
121: * saxon:line-number()
122: *
123: * @return the line number of the node in its original source document; or
124: * -1 if not available
125: * @since 8.4
126: */
127:
128: public int getLineNumber();
129:
130: /**
131: * Determine the relative position of this node and another node, in document order.
132: * <p>
133: * The other node must always be in the same tree; the effect of calling this method
134: * when the two nodes are in different trees is undefined. To obtain a global ordering
135: * of nodes, the application should first compare the result of getDocumentNumber(),
136: * and only if the document number is the same should compareOrder() be called.
137: *
138: * @param other The other node, whose position is to be compared with this
139: * node
140: * @return -1 if this node precedes the other node, +1 if it follows the
141: * other node, or 0 if they are the same node. (In this case,
142: * isSameNode() will always return true, and the two nodes will
143: * produce the same result for generateId())
144: * @since 8.4
145: */
146:
147: public int compareOrder(NodeInfo other);
148:
149: /**
150: * Return the string value of the node. This is normally the string value as defined in
151: * the XPath data model, except that no distinction is made between strings and untyped atomic values.
152: * <p>
153: * The interpretation of this depends on the type
154: * of node. For an element it is the accumulated character content of the element,
155: * including descendant elements.
156: * <p>
157: * This method returns the string value as if the node were untyped. Unlike the string value
158: * accessor in the XPath 2.0 data model, it does not report an error if the element has a complex
159: * type, instead it returns the concatenation of the descendant text nodes as it would if the element
160: * were untyped.
161: *
162: * @return the string value of the node
163: * @since 8.4
164: */
165:
166: public String getStringValue();
167:
168: /**
169: * Get name code. The name code is a coded form of the node name: two nodes
170: * with the same name code have the same namespace URI, the same local name,
171: * and the same prefix. By masking the name code with {@link NamePool#FP_MASK}, you get a
172: * fingerprint: two nodes with the same fingerprint have the same local name
173: * and namespace URI.
174: *
175: * @return an integer name code, which may be used to obtain the actual node
176: * name from the name pool. For unnamed nodes (text nodes, comments, document nodes,
177: * and namespace nodes for the default namespace), returns -1.
178: * @see net.sf.saxon.om.NamePool#allocate allocate
179: * @see net.sf.saxon.om.NamePool#getFingerprint getFingerprint
180: * @since 8.4
181: */
182:
183: public int getNameCode();
184:
185: /**
186: * Get fingerprint. The fingerprint is a coded form of the expanded name
187: * of the node: two nodes
188: * with the same name code have the same namespace URI and the same local name.
189: * The fingerprint contains no information about the namespace prefix. For a name
190: * in the null namespace, the fingerprint is the same as the name code.
191: *
192: * @return an integer fingerprint; two nodes with the same fingerprint have
193: * the same expanded QName. For unnamed nodes (text nodes, comments, document nodes,
194: * and namespace nodes for the default namespace), returns -1.
195: * @since 8.4
196: */
197:
198: public int getFingerprint();
199:
200: /**
201: * Get the local part of the name of this node. This is the name after the ":" if any.
202: *
203: * @return the local part of the name. For an unnamed node, returns "". Unlike the DOM
204: * interface, this returns the full name in the case of a non-namespaced name.
205: * @since 8.4
206: */
207:
208: public String getLocalPart();
209:
210: /**
211: * Get the URI part of the name of this node. This is the URI corresponding to the
212: * prefix, or the URI of the default namespace if appropriate.
213: *
214: * @return The URI of the namespace of this node. For an unnamed node,
215: * or for a node with an empty prefix, returns an empty
216: * string.
217: * @since 8.4
218: */
219:
220: public String getURI();
221:
222: /**
223: * Get the display name of this node, in the form of a lexical QName.
224: * For elements and attributes this is [prefix:]localname.
225: * For unnamed nodes, it is an empty string.
226: *
227: * @return The display name of this node. For a node with no name, returns
228: * an empty string.
229: * @since 8.4
230: */
231:
232: public String getDisplayName();
233:
234: /**
235: * Get the prefix of the name of the node. This is defined only for elements and attributes.
236: * If the node has no prefix, or for other kinds of node, returns a zero-length string.
237: * @return The prefix of the name of the node.
238: * @since 8.4
239: */
240:
241: public String getPrefix();
242:
243: /**
244: * Get the configuration used to build the tree containing this node.
245: * @return the Configuration
246: * @since 8.4
247: */
248:
249: public Configuration getConfiguration();
250:
251: /**
252: * Get the NamePool that holds the namecode for this node
253: * @return the namepool
254: * @since 8.4
255: */
256:
257: public NamePool getNamePool();
258:
259: /**
260: * Get the type annotation of this node, if any. The type annotation is represented as an integer;
261: * this is the fingerprint of the name of the type, as defined in the name pool. Anonymous types
262: * are given a system-defined name. The value of the type annotation can be used to retrieve the
263: * actual schema type definition using the method {@link Configuration#getSchemaType}.
264: * <p>
265: * The bit IS_DTD_TYPE (1<<30) will be set in the case of an attribute node if the type annotation
266: * is one of ID, IDREF, or IDREFS and this is derived from DTD rather than schema validation.
267: *
268: * @return the type annotation of the node, under the mask NamePool.FP_MASK, and optionally the
269: * bit setting IS_DTD_TYPE in the case of a DTD-derived ID or IDREF/S type (which is treated
270: * as untypedAtomic for the purposes of obtaining the typed value).
271: * Returns -1 for kinds of nodes that have no annotation, and for elements annotated as
272: * untyped, and attributes annotated as untypedAtomic.
273: * @since 8.4
274: */
275:
276: public int getTypeAnnotation();
277:
278: /**
279: * Bit setting in the returned type annotation indicating a DTD_derived type on an attribute node
280: */
281:
282: public static int IS_DTD_TYPE = 1 << 30;
283:
284: /**
285: * Get the typed value. The result of this method will always be consistent with the method
286: * {@link Item#getTypedValue()}. However, this method is often more convenient and may be
287: * more efficient, especially in the common case where the value is expected to be a singleton.
288: * @return the typed value. This will either be a single AtomicValue or a Value whose items are
289: * atomic values.
290: * @since 8.5
291: */
292:
293: public Value atomize() throws XPathException;
294:
295: /**
296: * Get the NodeInfo object representing the parent of this node
297: *
298: * @return the parent of this node; null if this node has no parent
299: * @since 8.4
300: */
301:
302: public NodeInfo getParent();
303:
304: /**
305: * Return an iteration over all the nodes reached by the given axis from this node
306: *
307: * @exception UnsupportedOperationException if the namespace axis is
308: * requested and this axis is not supported for this implementation.
309: * @param axisNumber an integer identifying the axis; one of the constants
310: * defined in class {@link net.sf.saxon.om.Axis}
311: * @return an AxisIterator that scans the nodes reached by the axis in
312: * turn.
313: * @see net.sf.saxon.om.Axis
314: * @since 8.4
315: */
316:
317: public AxisIterator iterateAxis(byte axisNumber);
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,
423: boolean copyAnnotations, int locationId)
424: throws XPathException;
425:
426: /**
427: * Don't copy any namespace nodes.
428: */
429:
430: int NO_NAMESPACES = 0;
431:
432: /**
433: * Copy namespaces declared (or undeclared) on this element, but not namespaces inherited from a parent element
434: */
435: int LOCAL_NAMESPACES = 1;
436:
437: /**
438: * Copy all in-scope namespaces
439: */
440: int ALL_NAMESPACES = 2;
441:
442: /**
443: * Output all namespace declarations associated with this element. Does nothing if
444: * the node is not an element.
445: * <p>
446: * This method is primarily for internal use. It should not be considered a stable part of the
447: * Saxon API.
448: *
449: * @param out The relevant Receiver
450: * @param includeAncestors True if namespaces declared on ancestor
451: * elements must be output; false if it is known that these are
452: *
453: */
454:
455: public void sendNamespaceDeclarations(Receiver out,
456: boolean includeAncestors) throws XPathException;
457:
458: /**
459: * Get all namespace undeclarations and undeclarations defined on this element.
460: * <p>
461: * This method is intended primarily for internal use. User applications needing
462: * information about the namespace context of a node should use <code>iterateAxis(Axis.NAMESPACE)</code>.
463: *
464: * @param buffer If this is non-null, and the result array fits in this buffer, then the result
465: * may overwrite the contents of this array, to avoid the cost of allocating a new array on the heap.
466: * @return An array of integers representing the namespace declarations and undeclarations present on
467: * this element. For a node other than an element, return null. Otherwise, the returned array is a
468: * sequence of namespace codes, whose meaning may be interpreted by reference to the name pool. The
469: * top half word of each namespace code represents the prefix, the bottom half represents the URI.
470: * If the bottom half is zero, then this is a namespace undeclaration rather than a declaration.
471: * The XML namespace is never included in the list. If the supplied array is larger than required,
472: * then the first unused entry will be set to -1.
473: * <p>
474: * For a node other than an element, the method returns null.</p>
475: */
476:
477: public int[] getDeclaredNamespaces(int[] buffer);
478:
479: }
480:
481: //
482: // The contents of this file are subject to the Mozilla Public License Version 1.0 (the "License");
483: // you may not use this file except in compliance with the License. You may obtain a copy of the
484: // License at http://www.mozilla.org/MPL/
485: //
486: // Software distributed under the License is distributed on an "AS IS" basis,
487: // WITHOUT WARRANTY OF ANY KIND, either express or implied.
488: // See the License for the specific language governing rights and limitations under the License.
489: //
490: // The Original Code is: all this file.
491: //
492: // The Initial Developer of the Original Code is Michael H. Kay.
493: //
494: // Portions created by (your name) are Copyright (C) (your legal entity). All Rights Reserved.
495: //
496: // Contributor(s): none.
497: //
|