Package net.sf.saxon.type.coercion

Class CoercionPlan

java.lang.Object

net.sf.saxon.type.coercion.CoercionPlan

Direct Known Subclasses:

ArrayCoercionPlan, AtomicCoercionPlan, FunctionItemCoercionPlan, GNodeCoercionPlan, IdentityCoercionPlan, ItemCheckingPlan, JNodeCoercionPlan, MapCoercionPlan, RecordCoercionPlan, XNodeCoercionPlan

public abstract class CoercionPlan
extends Object

A coercion plan represents a process for implementing the coercion rules for converting a supplied value to a given required type. A coercion plan is associated with each item type, and may differ depending on the XPath language version in use.

Constructor Summary

Constructors

Constructor	Description
CoercionPlan()

Method Summary

Modifier and Type	Method	Description
protected final void	check(Item item, ItemType requiredType, CoercionRequest request)	Check that the item is actually an instance of the required type, throwing an error if not
abstract GroundedValue	coerceItem(Item item, ItemType requiredType, CoercionRequest request)	Apply the coercion rules (3.1: function conversion rules) to an item, given this target item type.
final SequenceIterator	coerceSequence(SequenceIterator value, SequenceType requiredType, CoercionRequest request)	Apply the coercion rules (function conversion rules) to a sequence, given a required type.
protected XPathException	coercionError(Sequence value, ItemType requiredType, CoercionRequest request, String explanation)	Create an exception object representing a coercion error

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

CoercionPlan

public CoercionPlan()

Method Details

coerceSequence

public final SequenceIterator coerceSequence(SequenceIterator value,
 SequenceType requiredType,
 CoercionRequest request)
                                      throws XPathException

Apply the coercion rules (function conversion rules) to a sequence, given a required type.

Parameters:

value - the value to be coerced

requiredType - the required sequence type

request - other input to the coercion, for example diagnostic information

Returns:

the converted value (lazily-evaluated)

Throws:

XPathException - if the value cannot be converted to the required type

coerceItem

public abstract GroundedValue coerceItem(Item item,
 ItemType requiredType,
 CoercionRequest request)
                                  throws XPathException

Apply the coercion rules (3.1: function conversion rules) to an item, given this target item type.

Parameters:

item - the item to be coerced

requiredType - the required item type

request - the input to the coercion

Returns:

the converted value. We define this as a grounded value because in the vast majority of cases it will be a single item, and in other cases (a typed node with a list type, an array of atomic values) there is little benefit in lazy evaluation. The implementation is responsible for ensuring that the returned value does indeed consist entirely of items that match the required item type; it is not responsible for cardinality checking. The item type checking can be achieved, if required, by a callback to the check() method.

Throws:

XPathException - if the value cannot be converted to the required type

check

protected final void check(Item item,
 ItemType requiredType,
 CoercionRequest request)
                    throws XPathException

Check that the item is actually an instance of the required type, throwing an error if not

Parameters:

item - the item to be checked

requiredType - the required type

request - diagnostic data

Throws:

XPathException - if the item is not an instance of the required type

coercionError

protected XPathException coercionError(Sequence value,
 ItemType requiredType,
 CoercionRequest request,
 String explanation)

Create an exception object representing a coercion error

Parameters:

value - the input value to the coercion

requiredType - the required item type

request - the coercion request details

explanation - further explanation of the reason for failure; may be null

Returns:

an exception for the caller to throw