net.sf.saxon.om
Interface Item<T extends Item>

All Superinterfaces:

PullEvent, ValueRepresentation<T>

All Known Subinterfaces:

DocumentInfo, FunctionItem<T>, MapItem, MutableNodeInfo, NodeInfo, SiblingCountingNode, VirtualNode

All Known Implementing Classes:

AbsentExtensionElement, AbstractFunctionItem, AbstractVirtualNode, AnnotationParent, AnyURIValue, AtomicValue, Base64BinaryValue, BigIntegerValue, BooleanValue, CalendarValue, CoercedFunction, CurriedFunction, DataElement, DateTimeValue, DateValue, DayTimeDurationValue, DecimalValue, DocumentImpl, DocumentWrapper, DocumentWrapper, DocumentWrapper, DocumentWrapper, DoubleValue, DurationValue, ElementImpl, ExtensionInstruction, FirstClassFunction, FleetingDocumentNode, FleetingElementNode, FleetingNode, FloatValue, GDateValue, GDayValue, GMonthDayValue, GMonthValue, GYearMonthValue, GYearValue, HexBinaryValue, ImmutableMap, Int64Value, IntegerValue, LiteralResultElement, NamespaceNode, NodeImpl, NodeWrapper, NodeWrapper, NodeWrapper, NodeWrapper, NotationValue, NumericValue, ObjectValue, Orphan, QNameValue, QualifiedNameValue, SaxonAssign, SaxonCallTemplate, SaxonCollation, SaxonDoctype, SaxonEntityRef, SaxonImportQuery, SaxonParam, SaxonPreprocess, SaxonWhile, SchemaElement, SingletonMap, SpaceStrippedDocument, SpaceStrippedNode, SQLClose, SQLColumn, SQLConnect, SQLDelete, SQLExecute, SQLInsert, SQLQuery, SQLUpdate, StringValue, StyleElement, TextFragmentValue, TimeValue, TinyDocumentImpl, TinyElementImpl, TinyNodeImpl, TinyParentNodeImpl, TinyTextImpl, Tuple, TypeStrippedDocument, TypeStrippedNode, UnconstructedDocument, UnconstructedElement, UnconstructedParent, UnknownElement, UntypedAtomicValue, UserFunctionItem, VirtualCopy, VirtualDocumentCopy, VirtualUntypedCopy, WhitespaceTextImpl, XSDAlternative, XSDAnnotation, XSDAny, XSDAnyAttribute, XSDAssert, XSDAttribute, XSDAttributeGroup, XSDComplexContent, XSDComplexContentRestriction, XSDComplexType, XSDCompositor, XSDDefaultOpenContent, XSDDocumentation, XSDElement, XSDExtension, XSDFacet, XSDFieldOrSelector, XSDGroup, XSDIdentityConstraint, XSDImport, XSDInclude, XSDList, XSDNotation, XSDOpenContent, XSDOverride, XSDRedefine, XSDSchema, XSDSimpleContent, XSDSimpleContentRestriction, XSDSimpleType, XSDSimpleTypeRestriction, XSDUnion, XSLAnalyzeString, XSLApplyImports, XSLApplyTemplates, XSLAttribute, XSLAttributeSet, XSLBreak, XSLBreakOrContinue, XSLCallTemplate, XSLCatch, XSLCharacterMap, XSLChoose, XSLComment, XSLCopy, XSLCopyOf, XSLDecimalFormat, XSLDocument, XSLElement, XSLEvaluate, XSLFallback, XSLForEach, XSLForEachGroup, XSLFork, XSLFunction, XSLGeneralIncorporate, XSLGeneralVariable, XSLIf, XSLImport, XSLImportSchema, XSLInclude, XSLIterate, XSLKey, XSLLeafNodeConstructor, XSLMatchingSubstring, XSLMerge, XSLMergeAction, XSLMergeInput, XSLMergeKey, XSLMergeSource, XSLMessage, XSLMode, XSLNamespace, XSLNamespaceAlias, XSLNextIteration, XSLNextMatch, XSLNumber, XSLOnCompletion, XSLOtherwise, XSLOutput, XSLOutputCharacter, XSLParam, XSLPerformSort, XSLPreserveSpace, XSLProcessingInstruction, XSLResultDocument, XSLSequence, XSLSort, XSLSortOrMergeKey, XSLStylesheet, XSLTemplate, XSLText, XSLTry, XSLValueOf, XSLVariable, XSLVariableDeclaration, XSLWhen, XSLWithParam, YearMonthDurationValue

public interface Item<T extends Item>
extends ValueRepresentation<T>, PullEvent

An Item is an object that can occur as a member of a sequence. It corresponds directly to the concept of an item in the XPath 2.0 data model. There are two kinds of Item: atomic values, and nodes.

This interface is part of the public Saxon API. As such (starting from Saxon 8.4), methods that form part of the stable API are labelled with a JavaDoc "since" tag to identify the Saxon release at which they were introduced.

Note: there is no method getItemType(). This is to avoid having to implement it on every implementation of NodeInfo. Instead, use the static method Type.getItemType(Item).

Since:

8.4

Author:

Michael H. Kay

Field Summary

Fields inherited from interface net.sf.saxon.om.ValueRepresentation

EMPTY_VALUE_ARRAY

Method Summary

String	getStringValue() Get the value of the item as a string.
CharSequence	getStringValueCS() Get the string value of the item as a CharSequence.
SequenceIterator<? extends AtomicValue>	getTypedValue() Get the typed value of the item.

Method Detail

getStringValue

String getStringValue()

Get the value of the item as a string. For nodes, this is the string value of the node as defined in the XPath 2.0 data model, except that all nodes are treated as being untyped: it is not an error to get the string value of a node with a complex type. For atomic values, the method returns the result of casting the atomic value to a string.

If the calling code can handle any CharSequence, the method getStringValueCS() should be used. If the caller requires a string, this method is preferred.

Specified by:

getStringValue in interface ValueRepresentation<T extends Item>

Returns:

the string value of the item

Throws:

UnsupportedOperationException - if the item is a function item (an unchecked exception is used here to avoid introducing exception handling to a large number of paths where it is not needed)

Since:

8.4

See Also:

getStringValueCS()

getStringValueCS

CharSequence getStringValueCS()

Get the string value of the item as a CharSequence. This is in some cases more efficient than the version of the method that returns a String. The method satisfies the rule that X.getStringValueCS().toString() returns a string that is equal to X.getStringValue().

Note that two CharSequence values of different types should not be compared using equals(), and for the same reason they should not be used as a key in a hash table.

If the calling code can handle any CharSequence, this method should be used. If the caller requires a string, the getStringValue() method is preferred.

Specified by:

getStringValueCS in interface ValueRepresentation<T extends Item>

Returns:

the string value of the item

Throws:

UnsupportedOperationException - if the item is a function item (an unchecked exception is used here to avoid introducing exception handling to a large number of paths where it is not needed)

Since:

8.4

See Also:

getStringValue()

getTypedValue

SequenceIterator<? extends AtomicValue> getTypedValue()
                                                      throws XPathException

Get the typed value of the item.

For a node, this is the typed value as defined in the XPath 2.0 data model. Since a node may have a list-valued data type, the typed value is in general a sequence, and it is returned in the form of a SequenceIterator.

If the node has not been validated against a schema, the typed value will be the same as the string value, either as an instance of xs:string or as an instance of xs:untypedAtomic, depending on the node kind.

For an atomic value, this method returns an iterator over a singleton sequence containing the atomic value itself.

Returns:

an iterator over the items in the typed value of the node or atomic value. The items returned by this iterator will always be atomic values.

Throws:

XPathException - where no typed value is available, for example in the case of an element with complex content

Since:

8.4