Package org.apache.cayenne.query

## Class Ordering

- java.lang.Object
- - org.apache.cayenne.query.Ordering

- All Implemented Interfaces:
    `Serializable`, `Comparator<Object>`, `XMLSerializable`

      public class Ordering
      extends Object
      implements Comparator<Object>, Serializable, XMLSerializable

  Defines object sorting criteria, used either for in-memory sorting of object lists or as a specification for building ORDER BY clause of a SelectQuery query. Note that in case of in-memory sorting, Ordering can be used with any JavaBeans, not just DataObjects.
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected boolean` | `nullSortedFirst` |
    `protected boolean` | `pathExceptionSuppressed` |
    `protected SortOrder` | `sortOrder` |
    `protected Expression` | `sortSpec` |
    `protected String` | `sortSpecString` |

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Ordering()` |
    `Ordering​(String sortPathSpec)` | Create an ordering instance with a provided path and ascending sorting strategy.
    `Ordering​(String sortPathSpec, SortOrder sortOrder)` |
    `Ordering​(Expression sortSpec)` |
    `Ordering​(Expression sortSpec, SortOrder sortOrder)` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `int` | `compare​(Object o1, Object o2)` | Comparable interface implementation.
    `void` | `encodeAsXML​(XMLEncoder encoder, ConfigurationNodeVisitor delegate)` | Encodes itself as a query ordering.
    `boolean` | `equals​(Object object)` |
    `SortOrder` | `getSortOrder()` | Returns sort order for this ordering
    `Expression` | `getSortSpec()` | Returns the expression defining a ordering Java Bean property.
    `String` | `getSortSpecString()` | Returns sortSpec string representation.
    `int` | `hashCode()` |
    `boolean` | `isAscending()` | Returns true if sorting is done in ascending order.
    `boolean` | `isCaseInsensitive()` | Returns true if the sorting is case insensitive
    `boolean` | `isCaseSensitive()` | Returns true if the sorting is case sensitive.
    `boolean` | `isDescending()` | Returns true if the sorting is done in descending order.
    `boolean` | `isNullSortedFirst()` | Get sort order for nulls.
    `boolean` | `isPathExceptionSuppressed()` | Is a path with a null in the middle is ignored.
    `<E> List<E>` | `orderedList​(Collection<E> objects)` |
    `static <E> List<E>` | `orderedList​(Collection<E> objects, List<? extends Ordering> orderings)` | Orders a given list of objects, using a List of Orderings applied according the default iteration order of the Orderings list.
    `void` | `orderList​(List<?> objects)` | Orders the given list of objects according to the ordering that this object specifies.
    `static void` | `orderList​(List<?> objects, List<? extends Ordering> orderings)` | Orders a given list of objects, using a List of Orderings applied according the default iteration order of the Orderings list.
    `void` | `setAscending()` | If the sort order is DESCENDING or DESCENDING_INSENSITIVE, sets the sort order to ASCENDING or ASCENDING_INSENSITIVE, respectively.
    `void` | `setCaseInsensitive()` | If the sort order is ASCENDING or DESCENDING, sets the sort order to ASCENDING_INSENSITIVE or DESCENDING_INSENSITIVE, respectively.
    `void` | `setCaseSensitive()` | If the sort order is ASCENDING_INSENSITIVE or DESCENDING_INSENSITIVE, sets the sort order to ASCENDING or DESCENDING, respectively.
    `void` | `setDescending()` | If the sort order is ASCENDING or ASCENDING_INSENSITIVE, sets the sort order to DESCENDING or DESCENDING_INSENSITIVE, respectively.
    `void` | `setNullSortedFirst​(boolean nullSortedFirst)` | Sets sort order for whether nulls are at the top or bottom of the resulting list.
    `void` | `setPathExceptionSupressed​(boolean pathExceptionSuppressed)` | Sets whether a path with a null in the middle is ignored.
    `void` | `setSortOrder​(SortOrder order)` | Sets the sort order for this ordering.
    `void` | `setSortSpec​(Expression sortSpec)` | Sets the expression defining a ordering Java Bean property.
    `void` | `setSortSpecString​(String sortSpecString)` | Sets sortSpec to be an expression represented by string argument.
    `Orderings` | `then​(List<Ordering> nextOrderings)` |
    `Orderings` | `then​(Ordering nextOrdering)` | Returns Orderings with this Ordering followed by the provided next Ordering.
    `Orderings` | `then​(Orderings nextOrderings)` | Returns Orderings with this Ordering followed by the provided list of next Orderings.
    `String` | `toString()` |

    - ### Methods inherited from class java.lang.Object

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

    - ### Methods inherited from interface java.util.Comparator

      `reversed, thenComparing, thenComparing, thenComparing, thenComparingDouble, thenComparingInt, thenComparingLong`

- - ### Field Detail

    - #### sortSpecString

          protected String sortSpecString

    - #### sortSpec

          protected transient Expression sortSpec

    - #### sortOrder

          protected SortOrder sortOrder

    - #### pathExceptionSuppressed

          protected boolean pathExceptionSuppressed

    - #### nullSortedFirst

          protected boolean nullSortedFirst

  - ### Constructor Detail

    - #### Ordering

          public Ordering()

    - #### Ordering

          public Ordering​(String sortPathSpec)

      Create an ordering instance with a provided path and ascending sorting strategy.
      Since:
        4.0

    - #### Ordering

          public Ordering​(String sortPathSpec,
                          SortOrder sortOrder)

      Since:
        3.0

    - #### Ordering

          public Ordering​(Expression sortSpec)

      Since:
        4.0

    - #### Ordering

          public Ordering​(Expression sortSpec,
                          SortOrder sortOrder)

      Since:
        4.0

  - ### Method Detail

    - #### orderList

          public static void orderList​(List<?> objects,
                                       List<? extends Ordering> orderings)

      Orders a given list of objects, using a List of Orderings applied according the default iteration order of the Orderings list. I.e. each Ordering with lower index is more significant than any other Ordering with higher index. List being ordered is modified in place.
      Parameters:
        `objects` - elements to sort
        `orderings` - list of Orderings to be applied

    - #### orderedList

          public static <E> List<E> orderedList​(Collection<E> objects,
                                                List<? extends Ordering> orderings)

      Orders a given list of objects, using a List of Orderings applied according the default iteration order of the Orderings list. I.e. each Ordering with lower index is more significant than any other Ordering with higher index.
      Parameters:
        `objects` - elements to sort
        `orderings` - list of Orderings to be applied
      Returns:
        new List with ordered elements
      Since:
        4.0

    - #### equals

          public boolean equals​(Object object)

      Specified by:
        `equals` in interface `Comparator<Object>`
      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### setSortSpecString

          public void setSortSpecString​(String sortSpecString)

      Sets sortSpec to be an expression represented by string argument.
      Since:
        1.1

    - #### setNullSortedFirst

          public void setNullSortedFirst​(boolean nullSortedFirst)

      Sets sort order for whether nulls are at the top or bottom of the resulting list. Default is true. Affects only in-memory sorting.
      Parameters:
        `nullSortedFirst` - true sorts nulls to the top of the list, false sorts nulls to the bottom

    - #### isNullSortedFirst

          public boolean isNullSortedFirst()

      Get sort order for nulls.
      Returns:
        true if nulls are sorted to the top of the list, false if sorted to the bottom

    - #### setPathExceptionSupressed

          public void setPathExceptionSupressed​(boolean pathExceptionSuppressed)

      Sets whether a path with a null in the middle is ignored. For example, a sort from `painting` on `artist.name` would by default throw an exception if the artist was null. If set to true, then this is treated just like a null value. Default is false.
      Parameters:
        `pathExceptionSuppressed` - true to suppress exceptions and sort as null

    - #### isPathExceptionSuppressed

          public boolean isPathExceptionSuppressed()

      Is a path with a null in the middle is ignored.
      Returns:
        true is exception is suppressed and sorted as null

    - #### getSortSpecString

          public String getSortSpecString()

      Returns sortSpec string representation.
      Since:
        1.1

    - #### setSortOrder

          public void setSortOrder​(SortOrder order)

      Sets the sort order for this ordering.
      Since:
        3.0

    - #### isAscending

          public boolean isAscending()

      Returns true if sorting is done in ascending order.

    - #### isDescending

          public boolean isDescending()

      Returns true if the sorting is done in descending order.
      Since:
        3.0

    - #### setAscending

          public void setAscending()

      If the sort order is DESCENDING or DESCENDING_INSENSITIVE, sets the sort order to ASCENDING or ASCENDING_INSENSITIVE, respectively.
      Since:
        3.0

    - #### setDescending

          public void setDescending()

      If the sort order is ASCENDING or ASCENDING_INSENSITIVE, sets the sort order to DESCENDING or DESCENDING_INSENSITIVE, respectively.
      Since:
        3.0

    - #### isCaseInsensitive

          public boolean isCaseInsensitive()

      Returns true if the sorting is case insensitive

    - #### isCaseSensitive

          public boolean isCaseSensitive()

      Returns true if the sorting is case sensitive.
      Since:
        3.0

    - #### setCaseInsensitive

          public void setCaseInsensitive()

      If the sort order is ASCENDING or DESCENDING, sets the sort order to ASCENDING_INSENSITIVE or DESCENDING_INSENSITIVE, respectively.
      Since:
        3.0

    - #### setCaseSensitive

          public void setCaseSensitive()

      If the sort order is ASCENDING_INSENSITIVE or DESCENDING_INSENSITIVE, sets the sort order to ASCENDING or DESCENDING, respectively.
      Since:
        3.0

    - #### getSortSpec

          public Expression getSortSpec()

      Returns the expression defining a ordering Java Bean property.

    - #### setSortSpec

          public void setSortSpec​(Expression sortSpec)

      Sets the expression defining a ordering Java Bean property.

    - #### orderList

          public void orderList​(List<?> objects)

      Orders the given list of objects according to the ordering that this object specifies. List is modified in-place.
      Parameters:
        `objects` - a List of objects to be sorted

    - #### orderedList

          public <E> List<E> orderedList​(Collection<E> objects)

      Since:
        4.0

    - #### compare

          public int compare​(Object o1,
                             Object o2)

      Comparable interface implementation. Can compare two Java Beans based on the stored expression.
      Specified by:
        `compare` in interface `Comparator<Object>`

    - #### encodeAsXML

          public void encodeAsXML​(XMLEncoder encoder,
                                  ConfigurationNodeVisitor delegate)

      Encodes itself as a query ordering.
      Specified by:
        `encodeAsXML` in interface `XMLSerializable`
      Since:
        1.1

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### getSortOrder

          public SortOrder getSortOrder()

      Returns sort order for this ordering
      Since:
        3.1

    - #### then

          public Orderings then​(Ordering nextOrdering)

      Returns Orderings with this Ordering followed by the provided next Ordering.
      Parameters:
        `nextOrdering` - the next Ordering to chain to this
      Returns:
        a new Orderings with both Ordering
      Since:
        4.1

    - #### then

          public Orderings then​(Orderings nextOrderings)

      Returns Orderings with this Ordering followed by the provided list of next Orderings.
      Parameters:
        `nextOrderings` - the next Orderings to chain to this
      Returns:
        an array of sort orderings
      Since:
        4.1

    - #### then

          public Orderings then​(List<Ordering> nextOrderings)

      Parameters:
        `nextOrderings` - the next Orderings to chain to this
      Returns:
        an array of sort orderings
      Since:
        4.1
      See Also:
        `Orderings.then(Orderings)`