net.sf.saxon.expr.sort

Class SortKeyDefinition

java.lang.Object

net.sf.saxon.expr.Expression

net.sf.saxon.expr.PseudoExpression

net.sf.saxon.expr.sort.SortKeyDefinition

All Implemented Interfaces:

ExportAgent, Locatable, IdentityComparable

public class SortKeyDefinition
extends PseudoExpression

A SortKeyDefinition defines one component of a sort key.

Note that most attributes defining the sort key can be attribute value templates, and can therefore vary from one invocation to another. We hold them as expressions.

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	backwardsCompatible
protected java.lang.String	baseURI
protected Operand	caseOrder
protected StringCollator	collation
protected Operand	collationName
protected Operand	dataTypeExpression
protected boolean	emptyLeast
protected Operand	language
protected Operand	order
protected boolean	setContextForSortKey
protected Operand	sortKey
protected Operand	stable

Fields inherited from class net.sf.saxon.expr.Expression

EFFECTIVE_BOOLEAN_VALUE, EVALUATE_METHOD, ITEM_FEED_METHOD, ITERATE_METHOD, MAX_COST, MAX_SEQUENCE_LENGTH, MAX_STRING_LENGTH, PROCESS_METHOD, staticProperties, UNBOUNDED_LOWER, UNBOUNDED_UPPER, UPDATE_METHOD, WATCH_METHOD

Constructor Summary

Constructors

Constructor and Description
SortKeyDefinition()

Method Summary

Modifier and Type	Method and Description
int	computeHashCode() Get a hashcode to reflect the equals() method
SortKeyDefinition	copy(RebindingMap rm) Copy this SortKeyDefinition
boolean	equals(java.lang.Object other) Compare two SortKeyDefinition values for equality.
void	export(ExpressionPresenter out) Diagnostic print of expression structure.
SortKeyDefinition	fix(XPathContext context)
java.lang.String	getBaseURI() Get the static base URI of the expression.
Expression	getCaseOrder() Get the expression that defines the case order of the sort keys.
StringCollator	getCollation() Get the collation to be used
Expression	getCollationNameExpression() Get the selected collation name (specifically, an expression which when evaluated returns the collation URI).
Expression	getDataTypeExpression() Get the expression that defines the data type of the sort keys
boolean	getEmptyLeast() Ask whether empty sequence comes before other values or after them
AtomicComparer	getFinalComparator() Get the comparator which is used to compare two values according to this sort key.
int	getImplementationMethod() An implementation of Expression must provide at least one of the methods evaluateItem(), iterate(), or process().
Expression	getLanguage() Get the expression that defines the language of the sort keys
Expression	getOrder() Get the expression that defines the order as ascending or descending
Expression	getSortKey() Get the expression used as the sort key
Operand	getSortKeyOperand() Get the sort key operand
Expression	getStable() Ask whether this sort key definition is stable
boolean	isBackwardsCompatible() Ask whether this sort key is evaluated in XSLT 1.0 backwards compatibility mode
boolean	isFixed() Ask whether the sort key definition is fixed, that is, whether all the information needed to create a Comparator is known statically
boolean	isLiftable(boolean forStreaming) Ask whether the expression can be lifted out of a loop, assuming it has no dependencies on the controlling variable/focus of the loop
boolean	isSetContextForSortKey() Ask whether the sortkey is to be evaluated with the item-being-sorted as the context item
AtomicComparer	makeComparator(XPathContext context) Allocate an AtomicComparer to perform the comparisons described by this sort key component.
java.lang.Iterable<Operand>	operands() Get the immediate sub-expressions of this expression, with information about the relationship of each expression to its parent expression.
void	setBackwardsCompatible(boolean compatible) Set whether this sort key is evaluated in XSLT 1.0 backwards compatibility mode
void	setBaseURI(java.lang.String baseURI) Set the base URI of the expression.
void	setCaseOrder(Expression exp) Set the case order.
void	setCollation(StringCollator collation) Set the collation to be used
void	setCollationNameExpression(Expression collationNameExpr) Set the collation name (specifically, an expression which when evaluated returns the collation URI).
void	setDataTypeExpression(Expression exp) Set the data type.
void	setEmptyLeast(boolean emptyLeast) Set whether empty sequence comes before other values or after them
void	setFinalComparator(AtomicComparer comp) Set the comparator which is used to compare two values according to this sort key.
void	setLanguage(Expression exp) Set the language.
void	setOrder(Expression exp) Set the order.
void	setSortKey(Expression exp, boolean setContext) Set the expression used as the sort key
void	setStable(Expression stableExpr) Set whether this sort key definition is stable
SortKeyDefinition	typeCheck(ExpressionVisitor visitor, ContextItemStaticInfo contextItemType) Type-check this sort key definition (all properties other than the sort key select expression, when it has a different dynamic context)

Methods inherited from class net.sf.saxon.expr.PseudoExpression

computeCardinality, effectiveBooleanValue, evaluateAsString, evaluateItem, getItemType, iterate, process

Methods inherited from class net.sf.saxon.expr.Expression

addToPathMap, adoptChildExpression, allowExtractingCommonSubexpressions, checkedOperands, checkForUpdatingSubexpressions, checkPermittedContents, computeDependencies, computeSpecialProperties, computeStaticProperties, dynamicError, evaluatePendingUpdates, explain, getCardinality, getConfiguration, getConstructType, getCost, getDependencies, getEvaluationMethod, getExpressionName, getExtraProperty, getIntegerBounds, getInterpretedExpression, getIntrinsicDependencies, getLocalRetainedStaticContext, getLocation, getNetCost, getObjectName, getPackageData, getParentExpression, getProperties, getProperty, getRetainedStaticContext, getScopingExpression, getSlotsUsed, getSpecialProperties, getStaticBaseURI, getStaticBaseURIString, getStaticType, getStaticUType, getStreamerName, hasCompatibleStaticContext, hashCode, hasSpecialProperty, hasVariableBinding, identityHashCode, implementsStaticTypeCheck, isCallOn, isEqual, isIdentical, isInstruction, isMultiThreaded, isStaticPropertiesKnown, isSubtreeExpression, isUpdatingExpression, isVacuousExpression, markTailFunctionCalls, operandList, operandSparseList, optimize, optimizeChildren, prepareForStreaming, resetLocalStaticProperties, restoreParentPointers, setEvaluationMethod, setExtraProperty, setFiltered, setFlattened, setLocation, setParentExpression, setRetainedStaticContext, setRetainedStaticContextLocally, setRetainedStaticContextThoroughly, setStaticProperty, simplify, simplifyChildren, staticTypeCheck, suppressValidation, toPattern, toShortString, toString, typeCheckChildren, typeError, unordered, verifyParentPointers

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

sortKey

protected Operand sortKey

order

protected Operand order

dataTypeExpression

protected Operand dataTypeExpression

caseOrder

protected Operand caseOrder

language

protected Operand language

collationName

protected Operand collationName

stable

protected Operand stable

collation

protected StringCollator collation

baseURI

protected java.lang.String baseURI

emptyLeast

protected boolean emptyLeast

backwardsCompatible

protected boolean backwardsCompatible

setContextForSortKey

protected boolean setContextForSortKey

Constructor Detail

SortKeyDefinition

public SortKeyDefinition()

Method Detail

isLiftable

public boolean isLiftable(boolean forStreaming)

Ask whether the expression can be lifted out of a loop, assuming it has no dependencies on the controlling variable/focus of the loop

Overrides:

isLiftable in class Expression

Parameters:

forStreaming - true if we are optimizing for streamed evaluation

Returns:

true if the expression can be loop lifted

setSortKey

public void setSortKey(Expression exp,
                       boolean setContext)

Set the expression used as the sort key

Parameters:

exp - the sort key select expression

setContext - set to true if the sort key is to be evaluated with the item-being-sorted as the context item (as in XSLT); false if the context item is not to be set (as in XQuery)

getSortKey

public Expression getSortKey()

Get the expression used as the sort key

Returns:

the sort key select expression

getSortKeyOperand

public Operand getSortKeyOperand()

Get the sort key operand

Returns:

the operand that computes the sort key

isSetContextForSortKey

public boolean isSetContextForSortKey()

Ask whether the sortkey is to be evaluated with the item-being-sorted as the context item

Returns:

true if the context needs to be set for evaluating the sort key

setOrder

public void setOrder(Expression exp)

Set the order. This is supplied as an expression which must evaluate to "ascending" or "descending". If the order is fixed, supply e.g. new StringValue("ascending"). Default is "ascending".

Parameters:

exp - the expression that determines the order (always a literal in XQuery, but can be defined by an AVT in XSLT)

getOrder

public Expression getOrder()

Get the expression that defines the order as ascending or descending

Returns:

the expression that determines the order (always a literal in XQuery, but can be defined by an AVT in XSLT)

setDataTypeExpression

public void setDataTypeExpression(Expression exp)

Set the data type. This is supplied as an expression which must evaluate to "text", "number", or a QName. If the data type is fixed, the valus should be supplied using setDataType() and not via this method.

Parameters:

exp - the expression that defines the data type, as used in XSLT 1.0

getDataTypeExpression

public Expression getDataTypeExpression()

Get the expression that defines the data type of the sort keys

Returns:

the expression that defines the data type, as used in XSLT 1.0

setCaseOrder

public void setCaseOrder(Expression exp)

Set the case order. This is supplied as an expression which must evaluate to "upper-first" or "lower-first" or "#default". If the order is fixed, supply e.g. new StringValue("lower-first"). Default is "#default".

Parameters:

exp - the expression that defines the case order

getCaseOrder

public Expression getCaseOrder()

Get the expression that defines the case order of the sort keys.

Returns:

the expression that defines the case order, whose run-time value will be "upper-first", "lower-first", or "#default".

setLanguage

public void setLanguage(Expression exp)

Set the language. This is supplied as an expression which evaluates to the language name. If the order is fixed, supply e.g. new StringValue("de").

Parameters:

exp - the expression that determines the language

getLanguage

public Expression getLanguage()

Get the expression that defines the language of the sort keys

Returns:

exp the expression that determines the language

setCollationNameExpression

public void setCollationNameExpression(Expression collationNameExpr)

Set the collation name (specifically, an expression which when evaluated returns the collation URI).

Parameters:

collationNameExpr - the expression that determines the collation name

getCollationNameExpression

public Expression getCollationNameExpression()

Get the selected collation name (specifically, an expression which when evaluated returns the collation URI).

Returns:

the expression that determines the collation name

setCollation

public void setCollation(StringCollator collation)

Set the collation to be used

Parameters:

collation - A StringCollator, which encapsulates both the collation URI and the collating function

getCollation

public StringCollator getCollation()

Get the collation to be used

Returns:

A StringCollator, which encapsulates both the collation URI and the collating function

setBaseURI

public void setBaseURI(java.lang.String baseURI)

Set the base URI of the expression. This is needed to handle the case where a collation URI evaluated at run-time turns out to be a relative URI.

Parameters:

baseURI - the static base URI of the expression

getBaseURI

public java.lang.String getBaseURI()

Get the static base URI of the expression. This is needed to handle the case where a collation URI evaluated at run-time turns out to be a relative URI.

Returns:

the static base URI of the expression

setStable

public void setStable(Expression stableExpr)

Set whether this sort key definition is stable

Parameters:

stableExpr - the expression that determines whether the sort key definition is stable (it evaluates to the string "yes" or "no".

getStable

public Expression getStable()

Ask whether this sort key definition is stable

Returns:

the expression that determines whether the sort key definition is stable (it evaluates to the string "yes" or "no".

setBackwardsCompatible

public void setBackwardsCompatible(boolean compatible)

Set whether this sort key is evaluated in XSLT 1.0 backwards compatibility mode

Parameters:

compatible - true if backwards compatibility mode is selected

isBackwardsCompatible

public boolean isBackwardsCompatible()

Ask whether this sort key is evaluated in XSLT 1.0 backwards compatibility mode

Returns:

true if backwards compatibility mode was selected

setEmptyLeast

public void setEmptyLeast(boolean emptyLeast)

Set whether empty sequence comes before other values or after them

Parameters:

emptyLeast - true if () is considered lower than any other value

getEmptyLeast

public boolean getEmptyLeast()

Ask whether empty sequence comes before other values or after them

Returns:

true if () is considered lower than any other value

isFixed

public boolean isFixed()

Ask whether the sort key definition is fixed, that is, whether all the information needed to create a Comparator is known statically

Returns:

true if all information needed to create a Comparator is known statically

copy

public SortKeyDefinition copy(RebindingMap rm)

Copy this SortKeyDefinition

Specified by:

copy in class Expression

Parameters:

rm - a mutable list of (old binding, new binding) pairs that is used to update the bindings held in any local variable references that are copied.

Returns:

a copy of this SortKeyDefinition

typeCheck

public SortKeyDefinition typeCheck(ExpressionVisitor visitor,
                                   ContextItemStaticInfo contextItemType)
                            throws XPathException

Type-check this sort key definition (all properties other than the sort key select expression, when it has a different dynamic context)

Overrides:

typeCheck in class Expression

Parameters:

visitor - the expression visitor

contextItemType - the type of the context item

Returns:

the original expression, rewritten to perform necessary run-time type checks, and to perform other type-related optimizations

Throws:

XPathException - if any failure occurs

operands

public java.lang.Iterable<Operand> operands()

Description copied from class: Expression

Get the immediate sub-expressions of this expression, with information about the relationship of each expression to its parent expression. Default implementation works off the results of iterateSubExpressions()

If the expression is a Callable, then it is required that the order of the operands returned by this function is the same as the order of arguments supplied to the corresponding call() method.

Overrides:

operands in class Expression

Returns:

an iterator containing the sub-expressions of this expression

getImplementationMethod

public int getImplementationMethod()

An implementation of Expression must provide at least one of the methods evaluateItem(), iterate(), or process(). This method indicates which of these methods is provided directly. The other methods will always be available indirectly, using an implementation that relies on one of the other methods.

Overrides:

getImplementationMethod in class PseudoExpression

Returns:

the implementation method, for example Expression.ITERATE_METHOD or Expression.EVALUATE_METHOD or Expression.PROCESS_METHOD

makeComparator

public AtomicComparer makeComparator(XPathContext context)
                              throws XPathException

Allocate an AtomicComparer to perform the comparisons described by this sort key component. The AtomicComparer takes into account not only the collation, but also parameters such as order=descending and handling of empty sequence and NaN (the result of the compare() method of the comparator is +1 if the second item is to sort after the first item). The AtomicComparer is allocated at compile time if possible (during typeCheck), otherwise at run-time.

Parameters:

context - the dynamic evaluation context

Returns:

an AtomicComparer suitable for making the sort comparisons

Throws:

XPathException - for example if the collation URI is invalid or unknown

setFinalComparator

public void setFinalComparator(AtomicComparer comp)

Set the comparator which is used to compare two values according to this sort key. The comparator makes the final decision whether one value sorts before or after another: this takes into account the data type, the collation, whether empty comes first or last, whether the sort order is ascending or descending.

This method is called at compile time if all these factors are known at compile time. It must not be called at run-time, except to reconstitute a finalComparator that has been lost by virtue of serialization .

Parameters:

comp - the Atomic Comparer to be used

getFinalComparator

public AtomicComparer getFinalComparator()

Get the comparator which is used to compare two values according to this sort key. This method may be called either at compile time or at run-time. If no comparator has been allocated, it returns null. It is then necessary to allocate a comparator using the makeComparator(net.sf.saxon.expr.XPathContext) method.

Returns:

the Atomic Comparer to be used

fix

public SortKeyDefinition fix(XPathContext context)
                      throws XPathException

Throws:

XPathException

equals

public boolean equals(java.lang.Object other)

Compare two SortKeyDefinition values for equality. This compares the sortKeys and attribute values.

Overrides:

equals in class Expression

Parameters:

other - SortKeyDefinition

Returns:

boolean

computeHashCode

public int computeHashCode()

Get a hashcode to reflect the equals() method

Overrides:

computeHashCode in class Expression

Returns:

a hashcode based sortkey attribute values.

export

public void export(ExpressionPresenter out)
            throws XPathException

Description copied from class: Expression

Diagnostic print of expression structure. The abstract expression tree is written to the supplied output destination.

Specified by:

export in interface ExportAgent

Specified by:

export in class Expression

Parameters:

out - the expression presenter used to display the structure

Throws:

XPathException - if the export fails, for example if an expression is found that won't work in the target environment.