com.qizx.api
Interface ItemFactory

All Known Subinterfaces:

Expression, Library, XQuerySession

public interface ItemFactory

Creates Items and related resources (ItemTypes and QNames).

Method Summary

ItemSequence	copySequence(ItemSequence sequence) Creates a copy of the specified Sequence.
Item	createItem(boolean value) Creates an Item of type xs:boolean.
Item	createItem(double value) Creates an Item of type xs:double.
Item	createItem(float value) Creates an Item of type xs:float.
Item	createItem(InputSource source) Creates a Document Node item by parsing a document.
Item	createItem(long value, ItemType type) Creates an Item of type xs:integer, or one of its sub-types.
Item	createItem(Object value, ItemType type) Creates an item from a given object according to the general Java to XQuery type mapping, also used in the Java Binding extension.
Item	createItem(XMLPullStream source) Creates a Node item by reading a XML stream.
ItemSequence	createSequence(Object object, SequenceType type) Creates a sequence from a Java object.
QName	getQName(String localName) Returns a QName without namespace and without prefix.
QName	getQName(String localName, String namespaceURI) Returns a QName without prefix.
QName	getQName(String localName, String namespaceURI, String prefix) Returns a QName with prefix.
ItemType	getType(String name) Returns a predefined item Type from its name.

Method Detail

getQName

public QName getQName(String localName)

Returns a QName without namespace and without prefix.

Parameters:

localName - a name without colon.

Returns:

a QName instance

getQName

public QName getQName(String localName,
                      String namespaceURI)

Returns a QName without prefix.

Parameters:

localName - a name without colon.

namespaceURI - namespace URI

Returns:

a QName instance

getQName

public QName getQName(String localName,
                      String namespaceURI,
                      String prefix)

Returns a QName with prefix.

Parameters:

localName - a simple name without colon

namespaceURI - namespace URI

prefix - optional prefix, can be null.

Returns:

a QName instance

getType

public ItemType getType(String name)

Returns a predefined item Type from its name.

The name may be a short name without the "xs:" prefix. For example getType("xs:double") and getType("double") both return a representation of the XQuery type xs:double.

Parameters:

name - type name. Predefined short names: ENTITY, ID, IDREF, NCName, NMTOKEN, NOTATION, Name, QName, anyAtomicType, anySimpleType (item), anyURI, base64Binary, boolean, byte, date, dateTime, dayTimeDuration, decimal, double, duration, empty, float, gDay, gMonth, gMonthDay, gYear, gYearMonth, hexBinary, int, integer, language, long, negativeInteger, node, nonNegativeInteger, nonPositiveInteger, normalizedString, positiveInteger, short, string, time, token, unsignedByte, unsignedInt, unsignedLong, unsignedShort, untypedAtomic, yearMonthDuration

Returns:

a representation of an XQuery item type

createItem

public Item createItem(Object value,
                       ItemType type)
                throws EvaluationException

Creates an item from a given object according to the general Java to XQuery type mapping, also used in the Java Binding extension.

Parameters:

value - any object that can be converted to a XQuery Item.

type - type of the created item. Can be null. If it is null, the type will be the "natural type" of the actual object (see the Java to XQuery Mapping specification in the Qizx documentation).

Returns:

a new Item of the specified type.

Throws:

EvaluationException - if the conversion was not possible.

createItem

public Item createItem(boolean value)

Creates an Item of type xs:boolean.

Parameters:

value - a boolean value

Returns:

an Item of type xs:boolean

createItem

public Item createItem(double value)

Creates an Item of type xs:double.

Parameters:

value - a double value

Returns:

an Item of type xs:double

createItem

public Item createItem(float value)

Creates an Item of type xs:float.

Parameters:

value - a float value

Returns:

an Item of type xs:float

createItem

public Item createItem(long value,
                       ItemType type)
                throws EvaluationException

Creates an Item of type xs:integer, or one of its sub-types. If not specified (null), the type is xs:integer.

Parameters:

value - any long

type - desired item type: must be null or xs:integer or a subtype of xs:integer.

Returns:

an Item of the integer sub-type specified

Throws:

EvaluationException - if the type is not a subtype of xs:integer.

createItem

public Item createItem(InputSource source)
                throws EvaluationException,
                       IOException

Creates a Document Node item by parsing a document.

Parameters:

source - a SAX input source

Returns:

a Node item

Throws:

EvaluationException - wraps a parsing exception

IOException - if the source cannot be read

createItem

public Item createItem(XMLPullStream source)
                throws EvaluationException

Creates a Node item by reading a XML stream.

The resulting item can be any kind of node, depending on the XML event(s) encountered.

The source will be read until a complete Node is formed, but no further. Therefore it is possible to call repeatedly this method on the same source, provided it is correctly positioned initially.

Parameters:

source - a XML pull stream

Returns:

a Node item

Throws:

EvaluationException

copySequence

public ItemSequence copySequence(ItemSequence sequence)
                          throws EvaluationException

Creates a copy of the specified Sequence.

Parameters:

sequence - an input sequence of items. The position is left untouched

Returns:

a copy of the input sequence, at position 0

Throws:

EvaluationException - if the enumeration of the input sequence caused an error

createSequence

public ItemSequence createSequence(Object object,
                                   SequenceType type)
                            throws EvaluationException

Creates a sequence from a Java object.

1. A null object converts to an empty sequence.
2. If the type is non-null, it will be used as an indication of the result type:
   • A type equivalent to xdt:wrappedObject will produce a sequence made of a single item (the wrapped object) whether it is an array or not.
   • Otherwise if the object is an array, a java.util.Iterator, a java.util.Enumeration, or a java.util.Collection, the method builds a sequence by converting each element of the array/collection etc. as per createItem(Object, ItemType), using the specified type. For example if the type argument is xs:double*, the method will attempt to convert each item to a double.
   • Otherwise (not enumerable) the resulting sequence will have one item obtained by converting the object to the specified item type. For example, passing a java.lang.String with a type xs:double, (or xs:double?, xs:double*, xs:double+) generates a single item sequence, where the item is obtained by converting the string to a double.
3. If the type is null, it will be inferred from the actual type of the object. If the object is an array, the type will be component_type*, where component_type is the mapping of the array component type. For example, the type for an object of type String[] will be xs:string*.
   If the object is a collection/iterator, the type is item()*.
   Then the conversion proceeds like in case 2.

Parameters:

object - Java object to convert

type - optional type hint

Returns:

a sequence of Items.

Throws:

EvaluationException