Queries
HTTP query parameters are captured by Limberest into a Query
object. The method Query.getFilters()
returns a map that your service can use to filter results.
Query also provides the built-in match()
method which can be used with with Java
Streams for
convenient autofiltering. Here’s an example from limberest-demo’s
MoviesPersistFile:
@Override
public List<Movie> retrieve(Query query) throws PersistException {
List<Movie> movies = getMovies();
Stream<Movie> stream = movies.stream();
// filter
if (query.hasFilters() || query.getSearch() != null) {
stream = stream.filter(movie -> query.match(new JsonMatcher(movie.toJson())));
}
// sort
if ((query.getSort() != null && !"title".equals(query.getSort())) || query.isDescending()) {
stream = stream.sorted(new JsonableComparator(query, (j1, j2) -> {
return getSortTitle(j1).compareToIgnoreCase(getSortTitle(j2));
}));
}
// paginate
if (query.getStart() > 0)
stream = stream.skip(query.getStart());
if (query.getMax() != Query.MAX_ALL)
stream = stream.limit(query.getMax());
return stream.collect(Collectors.toList());
}
In the limberest-demo app a streamable list of Movies is held in memory. The retrieve()
method above:
- filters using the handy JsonMatcher predicate:
if (query.hasFilters() || query.getSearch() != null) { stream = stream.filter(movie -> query.match(new JsonMatcher(movie.toJson()))); }
- sorts according to special meta parameters, using
JsonableComparator
if ((query.getSort() != null && !"title".equals(query.getSort())) || query.isDescending()) { stream = stream.sorted(new JsonableComparator(query, (j1, j2) -> { return getSortTitle(j1).compareToIgnoreCase(getSortTitle(j2)); })); }
- and then optionally paginates based on the Query’s paging meta parameters:
if (query.getStart() > 0) stream = stream.skip(query.getStart()); if (query.getMax() != Query.MAX_ALL) stream = stream.limit(query.getMax());
Meta Parameters
A few meta parameters have special meaning to Query objects:
- count (
boolean
): Return item count only (no retrieval). - search (
String
): Find matching results across fields. - start (
int
): Start the item list at the specified index. - max (
int
): Limit results to no more than this (paginate). - sort (
String
): Sort results on this item property. - descending (
boolean
): Sort results in descending order.
These special parameters are not included in getFilters()
, but can be accessed directly (getSort()
).
You can use these special fields to further process the results returned by your service as in the
filtering, sorting and paginating examples above.
Sample requests
Try these against the limberest-demo movies service to see how query parameters affect results:
retrieve all movies:
retrieve movies made in 1931:
retrieve movies made after 1935:
- /movies?year=>1935 (note > is part of query value)
retrieve all movies, sorted by rating in descending order:
retrieve movies with a rating of 3.5 or above, sorted by year:
- /movies?rating=>=3.5&sort=year (note >= is prepended to query value)
find all movies with Bela Lugosi:
retrieve the first page of movies, with page size = 25
retrieve the second page of movies, with page size = 25
retrieve the first page of movies from a list sorted by year
retrieve the first page of movies featuring Boris Karloff, sorted by year
Next Topic: Swagger