## net.sf.saxon.sort
Class SortKeyDefinition

    java.lang.Object
      net.sf.saxon.sort.SortKeyDefinition

All Implemented Interfaces:
  java.io.Serializable

    public class SortKeyDefinition

extends java.lang.Object
implements java.io.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 java.lang.String` `baseURI`
`protected Expression` `caseOrder`
`protected StringCollator` `collation`
`protected Expression` `collationName`
`protected Expression` `dataTypeExpression`
`protected boolean` `emptyLeast`
`protected Expression` `language`
`protected Expression` `order`
`protected Expression` `sortKey`
`protected Expression` `stable`

Constructor Summary
`SortKeyDefinition()`

Method Summary
`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.
`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
`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
`AtomicComparer` `makeComparator(XPathContext context)` Allocate an AtomicComparer to perform the comparisons described by this sort key component.
`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 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)` 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

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, 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 java.lang.String baseURI

### emptyLeast

    protected boolean emptyLeast

### backwardsCompatible

    protected boolean backwardsCompatible

Constructor Detail

### SortKeyDefinition

    public SortKeyDefinition()

Method Detail

### setSortKey

    public void setSortKey(Expression exp)

  Set the expression used as the sort key

  Parameters:
    `exp` - the sort key select expression

### getSortKey

    public Expression getSortKey()

  Get the expression used as the sort key

  Returns:
    the sort key select expression

### 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(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 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

### 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

Copyright (c) Saxonica Limited. All rights reserved.