This document describes the client side interfaces which a developer can use to Query and Page through data obtained from remote rest services. This document describes both how to interact with the Aerogear-Controller based paging as well how to extend the libraries and APIs to support most other restful services. It is currently Java centric, but this should be fixed up in the future.
At a high level, Paging and Querying is supported though the Pipe.readWithFilter(ReadFilter, Callback) method. A ReadFilter object will set the current page, number of results perPage, and a where property. The Pipe implementation will be responsible for processing a request along with any paging data and sending the appropriate headers, data, and query parameters to the server. Once the response has been received, the Pipe implementation will provide a List of objects to the supplied callback. If this call used paging, the List will be an instance of PagedList.
PagedList will be a List of results for the request, but also have methods for retrieving the next list.
ReadFilter is a value object to store general filter information about a request. It has a convenience method to generate a query.
Page:int the requested page index
PerPage:int the maximum number of results the server should return
Where:JSONObject a JSONObject representing the where clause. In general this will be a collection of key/value pairs; however, nested queries CAN be supported.
getQuery():String returns the ReadFilter as a URI query. Page maps to "page", PerPage maps to "perPage", and where is mapped as "where" and the JSON String is set as the value.
PagedList extends List.
first(callback):void Async Method to call the filter selected by firstFilter. A new PagedList instance will be passed to callback as per Pipe.readWithFilter.
next(callback):void Async Method to call the filter selected by nextFilter. A new PagedList instance will be passed to callback as per Pipe.readWithFilter.
prev(callback):void Async Method to call the filter selected by prevFilter. A new PagedList instance will be passed to callback as per Pipe.readWithFilter.
last(callback):void Async Method to call the filter selected by lastFilter. A new PagedList instance will be passed to callback as per Pipe.readWithFilter.
hasFirst():boolean returns true if there is a firstFilter set
hasNext():boolean returns true if there is a nextFilter set
hasPrev():boolean returns true if there is a prevFilter set
hasLast():boolean returns true if there is a lastFilter set
RestAdapter.readWithFilter(ReadFilter, CallBack) is called by the developer. The RestAdapter appends the query to baseURL (along with any auth information) and executes the HttpRequest.
The RestAdapter assumes the body of the response is JSON wich represents either the Object type of the Pipe or a JSONArray which has items of the type. It also assumes paging information is in the header. It creates ReadFilters from the headerValues and combines those into a PagedList object. This List is passed back through the callback
The developer will receive from readWithFilter() a List of object. The developer will use isntanceof to test for a PagingList and cast if appropriate. She can then use the List as a List to show the results, or use the navigator(next, prev, etc) to fetch the appropriate new PagedList.
Hands you a knife and a quick pat on the back. "You're going to do fine kid"