## net.sf.saxon.sort
Class SortKeyDefinition

    java.lang.Object
      net.sf.saxon.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

Constructor Summary
`SortKeyDefinition()`

Method Summary
`String` `getBaseURI()`
`Expression` `getCaseOrder()`
`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()`
`boolean` `getEmptyLeast()` Discover 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()`
`Expression` `getOrder()`
`Container` `getParentExpression()`
`Expression` `getSortKey()` Get the expression used as the sort key
`Expression` `getStable()`
`boolean` `isBackwardsCompatible()`
`boolean` `isFixed()` Discover 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)`
`void` `setBaseURI(String baseURI)`
`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` `setParentExpression(Container container)`
`void` `setSortKey(Expression exp)` Set the expression used as the sort key
`void` `setStable(Expression stable)`
`SortKeyDefinition` `simplify(StaticContext env, Executable exec)`

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### SortKeyDefinition

    public SortKeyDefinition()

Method Detail

### setParentExpression

    public void setParentExpression(Container container)

### getParentExpression

    public Container getParentExpression()

### setSortKey

    public void setSortKey(Expression exp)

  Set the expression used as the sort key

### getSortKey

    public Expression getSortKey()

  Get the expression used as 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".

### getOrder

    public Expression getOrder()

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

### getDataTypeExpression

    public Expression getDataTypeExpression()

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

### getCaseOrder

    public Expression getCaseOrder()

### 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").

### getLanguage

    public Expression getLanguage()

### setCollationNameExpression

    public void setCollationNameExpression(Expression collationName)

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

### getCollationNameExpression

    public Expression getCollationNameExpression()

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

### setCollation

    public void setCollation(StringCollator collation)

  Set the collation to be used

  Parameters:
    `collation` - A NamedCollation, which encapsulates both the collation URI and the collating function

### getCollation

    public StringCollator getCollation()

  Get the collation to be used

  Returns:
    A NamedCollation, which encapsulates both the collation URI and the collating function

### setBaseURI

    public void setBaseURI(String baseURI)

### getBaseURI

    public String getBaseURI()

### setStable

    public void setStable(Expression stable)

### getStable

    public Expression getStable()

### setBackwardsCompatible

    public void setBackwardsCompatible(boolean compatible)

### isBackwardsCompatible

    public boolean isBackwardsCompatible()

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

  Discover whether empty sequence comes before other values or after them

  Returns:
    true if () is considered lower than any other value

### isFixed

    public boolean isFixed()

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

### simplify

    public SortKeyDefinition simplify(StaticContext env,
                                      Executable exec)
                               throws XPathException

  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)

  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 .

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

Copyright (C) Michael H. Kay. All rights reserved.