net.sf.saxon.expr.sort

## Class SortKeyDefinition

- java.lang.Object
- - 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.
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `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

    Constructors
    Constructor and Description
    `SortKeyDefinition()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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. 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`

    - #### 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-2013 Saxonica Limited. All rights reserved.