Ordering Results

The results are returned in a collection whose order of iteration can be controlled by setting the query's write-only Ordering string property. The ordering string consists of one or more ordering clauses separated by commas. Each ordering clause consists of a field expression followed by one of the two keywords ascending or descending. The field expression may be a simple field name of the candidate class, or it may be a compound field name using one or more field access operators. The fields must be persistent, and their types can be any of the following:

• Primitives except boolean

• Wrapper types except Boolean

• BigDecimal

• BigInteger

• String

• Date

Like the other strings that determine the query's behavior, there is only one ordering string for each query.

The ordering clauses are evaluated from left to right. If the clause to the left does not determine the relative ordering of two objects in the results, then the next clause to the right is evaluated, and so on, until either the ordering is determined or all the clauses have been evaluated. A field expression evaluates to null if any of the component field names evaluate to null. When a field expression evaluates to null, it depends on the implementation whether the object containing the null reference comes before or after objects that have values for the field.

Let's look at several examples that illustrate the syntax of the ordering string. Listing 2-2 shows the persistent fields of the Song and Label application data classes. When Song is the candidate class, any of the following strings can be the ordering string:

• "title ascending"

• "label.name descending"

• "label.hometown ascending, title ascending"

Listing 2-2: The Persistent Fields of the Song and Label Classes

 public class Song    {    private String title;    private Label label;    ...    } public class Label    {    private String name;    private String hometown;    ...    } 

In the first case, the results would be in ascending order by the title string, in the second case in descending order by the name of the label, and in the third case, in ascending order by the label's hometown and, within that, in ascending order by the song's title.