LiveRamp/jack — pull request #89 by tuliren (2014-08-18 06:45:46+00:00)
Title: Query with ordered results

#### Design
The feature included in the current pull request allows ordered query by multiple fields for both mock and non-mock database model. However, it only works with the `Query Builder`, but does not support the basic `findBy...` methods.
- For non-mock database model: an `Order By` clause is generated and attached to the end of the SQL statement.
- For mock database model: since the mock model does not touch the database, the above strategy would not work; therefore, an unordered result set is first retrieved by the original query method call, then it is sorted by comparators and stored in a `List`.

This feature should not interrupt any working use case of the current system. All the original test cases have not been changed. I tried to follow the existing design as much as possible. However, a few method calls were refactored to accommodate the changes.

===

#### Ordered query methods
- `asc()` and `desc()` - the `JackOrder` that can be passed into each order specification to allow ascending or descending sorting; `asc()` is the default order.
- `order()` - a query command that sort the result by ID.
- `orderBy[SpecificField]()` - a query command that sort the query by the specified field.
- `findWithOrder()` - a query command that completes the query builder, triggers the query and returns a `List` of database models.

===

#### Examples
```Java
List result;

// A simple ordered query that sort the result by ID ascendingly.
result = users.query().bio("Engineer").order().findWithOrder();
// The above query is equivalent to:
result = users.query().bio("Engineer").orderById(asc()).findWithOrder();

// A chained query that looks for users with 3 posts, and sort the result
// first by ID descendingly, and then by the number of posts ascendingly
// (which is the default order).
result = users.query().numPosts(3).order(desc()).orderByNumPosts().findWithOrder();
// The above query is equivalent to:
result = users.query().numPosts(3).orderById(desc()).orderByNumPosts(asc()).findWithOrder();
```

===

Please let me know if you have any problem using it, as well as any suggestions. Thanks for your time and attention.

LiRen Tu
2014.08.18