01: package net.sf.saxon.om;
02:
03: import net.sf.saxon.trans.XPathException;
04:
05: /**
06: * An Item is an object that can occur as a member of a sequence.
07: * It corresponds directly to the concept of an item in the XPath 2.0 data model.
08: * There are two kinds of Item: atomic values, and nodes.
09: * <p>
10: * This interface is part of the public Saxon API. As such (starting from Saxon 8.4),
11: * methods that form part of the stable API are labelled with a JavaDoc "since" tag
12: * to identify the Saxon release at which they were introduced.
13: * <p>
14: * Note: there is no method getItemType(). This is to avoid having to implement it
15: * on every implementation of NodeInfo. Instead, use the static method Type.getItemType(Item).
16: *
17: * @author Michael H. Kay
18: * @since 8.4
19: */
20:
21: public interface Item extends ValueRepresentation {
22:
23: /**
24: * Get the value of the item as a string. For nodes, this is the string value of the
25: * node as defined in the XPath 2.0 data model, except that all nodes are treated as being
26: * untyped: it is not an error to get the string value of a node with a complex type.
27: * For atomic values, the method returns the result of casting the atomic value to a string.
28: * <p>
29: * If the calling code can handle any CharSequence, the method {@link #getStringValueCS} should
30: * be used. If the caller requires a string, this method is preferred.
31: *
32: * @return the string value of the item
33: * @see #getStringValueCS
34: * @since 8.4
35: */
36:
37: public String getStringValue();
38:
39: /**
40: * Get the string value of the item as a CharSequence. This is in some cases more efficient than
41: * the version of the method that returns a String. The method satisfies the rule that
42: * <code>X.getStringValueCS().toString()</code> returns a string that is equal to
43: * <code>X.getStringValue()</code>.
44: * <p>
45: * Note that two CharSequence values of different types should not be compared using equals(), and
46: * for the same reason they should not be used as a key in a hash table.
47: * <p>
48: * If the calling code can handle any CharSequence, this method should
49: * be used. If the caller requires a string, the {@link #getStringValue} method is preferred.
50: *
51: * @return the string value of the item
52: * @see #getStringValue
53: * @since 8.4
54: */
55:
56: public CharSequence getStringValueCS();
57:
58: /**
59: * Get the typed value of the item.
60: * <p>
61: * For a node, this is the typed value as defined in the XPath 2.0 data model. Since a node
62: * may have a list-valued data type, the typed value is in general a sequence, and it is returned
63: * in the form of a SequenceIterator.
64: * <p>
65: * If the node has not been validated against a schema, the typed value
66: * will be the same as the string value, either as an instance of xs:string or as an instance
67: * of xdt:untypedAtomic, depending on the node kind.
68: * <p>
69: * For an atomic value, this method returns an iterator over a singleton sequence containing
70: * the atomic value itself.
71: *
72: * @return an iterator over the items in the typed value of the node or atomic value. The
73: * items returned by this iterator will always be atomic values.
74: * @throws XPathException where no typed value is available, for example in the case of
75: * an element with complex content
76: * @since 8.4
77: */
78:
79: public SequenceIterator getTypedValue() throws XPathException;
80:
81: }
82:
83: //
84: // The contents of this file are subject to the Mozilla Public License Version 1.0 (the "License");
85: // you may not use this file except in compliance with the License. You may obtain a copy of the
86: // License at http://www.mozilla.org/MPL/
87: //
88: // Software distributed under the License is distributed on an "AS IS" basis,
89: // WITHOUT WARRANTY OF ANY KIND, either express or implied.
90: // See the License for the specific language governing rights and limitations under the License.
91: //
92: // The Original Code is: all this file.
93: //
94: // The Initial Developer of the Original Code is Michael H. Kay.
95: //
96: // Portions created by (your name) are Copyright (C) (your legal entity). All Rights Reserved.
97: //
98: // Contributor(s): none.
99: //
|