net.sf.saxon.expr.sort
Class SortKeyDefinition

java.lang.Object
  extended by net.sf.saxon.expr.sort.SortKeyDefinition
All Implemented Interfaces:
Serializable

public class SortKeyDefinition
extends Object
implements Serializable

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. As soon as they are all known (which in general is only at run-time), the SortKeyDefinition is replaced by a FixedSortKeyDefinition in which all these values are fixed.

See Also:
Serialized Form

Field Summary
protected  boolean backwardsCompatible
           
protected  String baseURI
           
protected  Expression caseOrder
           
protected  StringCollator collation
           
protected  Expression collationName
           
protected  Expression dataTypeExpression
           
protected  boolean emptyLeast
           
protected  Expression language
           
protected  Expression order
           
protected  boolean setContextForSortKey
           
protected  Expression sortKey
           
protected  Expression stable
           
 
Constructor Summary
SortKeyDefinition()
           
 
Method Summary
 SortKeyDefinition copy()
          Copy this SortKeyDefinition
 boolean equals(Object other)
          Compare two SortKeyDefinition values for equality.
 SortKeyDefinition fix(XPathContext context)
           
 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.
 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
 Expression getStable()
          Ask whether this sort key definition is stable
 int hashCode()
          Get a hashcode to reflect the equals() method
 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 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.
 void processSubExpressions(ExpressionProcessor processor)
          Process the subexpressions of this clause
 void setBackwardsCompatible(boolean compatible)
          Set whether this sort key is evaluated in XSLT 1.0 backwards compatibility mode
 void setBaseURI(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 collationName)
          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 stable)
          Set whether this sort key definition is stable
 SortKeyDefinition simplify(ExpressionVisitor visitor)
          Simplify this sort key definition
 void typeCheck(ExpressionVisitor visitor, ExpressionVisitor.ContextItemType 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 java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

sortKey

protected Expression sortKey

order

protected Expression order

dataTypeExpression

protected Expression dataTypeExpression

caseOrder

protected Expression caseOrder

language

protected Expression language

collationName

protected Expression collationName

stable

protected Expression stable

collation

protected StringCollator collation

baseURI

protected String baseURI

emptyLeast

protected boolean emptyLeast

backwardsCompatible

protected boolean backwardsCompatible

setContextForSortKey

protected boolean setContextForSortKey
Constructor Detail

SortKeyDefinition

public SortKeyDefinition()
Method Detail

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

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 collationName)
Set the collation name (specifically, an expression which when evaluated returns the collation URI).

Parameters:
collationName - 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(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 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 stable)
Set whether this sort key definition is stable

Parameters:
stable - 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

simplify

public SortKeyDefinition simplify(ExpressionVisitor visitor)
                           throws XPathException
Simplify this sort key definition

Parameters:
visitor - the expression visitor
Returns:
the simplified sort key definition
Throws:
XPathException - if any failure occurs

copy

public SortKeyDefinition copy()
Copy this SortKeyDefinition


typeCheck

public void typeCheck(ExpressionVisitor visitor,
                      ExpressionVisitor.ContextItemType 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)

Parameters:
visitor - the expression visitor
contextItemType - the type of the context item
Throws:
XPathException - if any failure occurs

processSubExpressions

public void processSubExpressions(ExpressionProcessor processor)
                           throws XPathException
Process the subexpressions of this clause

Parameters:
processor - the expression processor used to process the subexpressions
Throws:
XPathException

makeComparator

public AtomicComparer makeComparator(XPathContext context)
                              throws XPathException
Allocate an AtomicComparer to perform the comparisons described by this sort key component. This method is called at run-time. 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)

Parameters:
context - the dynamic evaluation context
Returns:
an AtomicComparer suitable for making the sort comparisons
Throws:
XPathException

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(Object other)
Compare two SortKeyDefinition values for equality. This compares the sortKeys and attribute values.

Overrides:
equals in class Object
Parameters:
other - SortKeyDefinition
Returns:
boolean

hashCode

public int hashCode()
Get a hashcode to reflect the equals() method

Overrides:
hashCode in class Object
Returns:
a hashcode based sortkey attribute values.


Copyright (c) 2004-2011 Saxonica Limited. All rights reserved.