Most collection resources support pagination. The client can specify the start index, the start page size, and sorting query parameters. The framework uses the endpoint defaults if the client does not specify these parameters. The response also includes the standard prev, next , first and last relation links to retrieve the page before or after the requested page.
A client may also request a collection and pass in the getForUpdate=true query parameter. The response then includes the full collection of items that belong to the request page as well as all of the other items, which are represented by their IDs. Subsequent PATCH calls for the collection can then pass in those IDs for the elements that should not be updated.
Working with Pagination Framework Support
Collection resource endpoint pagination uses the following classes:
ListingRequest– Contains pagination properties to specify the page of items to be retrieved by the server. This is usually configured based on the client request query parameters.ListingResponse– This class contains the collection of items and the pagination properties related to the specific page results to be used to generate the response. This is created with a combination of the listing request and the retrieval of the items for the response.ListingRequestUtils– This class contains aqueryParamsToListingRequestutility method that generates a listing request based on the client query parameters. It also includes a method to support query-based pagination.
Collection endpoints typically:
Call the
queryParamsToListingRequestmethod to generate an initialListingRequestinstance.Retrieve a page of items for the collection. The page size and offset definitions are based on the listing request properties.
Create an instance of a
ListingResponseby calling theListingResonse(ListingRequest)constructor and setting any related property values.
Use the listingResponse representation model building method to provide the listing response to the RepresentationModel. By doing this, the framework message body writer automatically generates the expected pagination links and properties for the response.
The collection resource representation for the response can include additional paging links. The response may include the following paging properties:
next– Displays the next page.prev– Displays the previous page.first– Displays the first page.last– Displays the last page.count– The number of items in the response. This matches thelimitquery parameter value provided by the client; however, in certain cases it may not match, for example if thelimitvalue is greater than the number of items to be returned.hasMore– This Boolean value istrueif there are more pages in the collection after the current page. Note: If the media type of the response is Oracle JSON, this property cannot be filtered from a paging response.
The LinkUtils class provides the utility methods to generate the links based upon the listing response, and is invoked automatically by the message body writers. In addition to links, the following query parameters may be specified:
totalResults– The total number of items in the collection. Note: If the media type of the response is Oracle JSON and the client specifies thetotalResults=truequery parameter for the request, this property cannot be filtered out of the response.limit– The actual page size used by the server. This matches thelimitquery parameter value provided by the client; however, in certain cases it may not match, for example, if the client limit exceeds the server’s maximum limit.offset– The page 0-based index into the collection used for the response.getForUpdate– If set totrue, the response also includes the ID fields for all of the elements in the collection.orderBy– The name of the field to sort by. A post fix ofascordescindicates the direction, for example,orderBy=price:ascwould display the price field in ascending order.
Note that with the exception of the totalResults and the hasMore properties, these properties can be filtered out of the response.
For example:
links: [
{"rel": "next",
"href":"http://localhost:8380/public/v1/test/orders?offset=4&limit=2"},
{"rel": "prev", "href":
"http://localhost:8380/public/v1/test/orders?offset=2&limit=2"},
{"rel": "first","href":
"http://localhost:8380/public/v1/test/orders?offset=0&limit=2"},
{"rel": "last", "href":
"http://localhost:8380/public/v1/test/orders?offset=8&limit=2"}
]Configuring Query-Based Pagination
A resource can support the client retrieving collection items one page at a time. The number of items to return in the response determines the size limit of the page. Client requests can use a q query parameter, the value of which is an RQL query string that is applicable to a collection resource. The ListingRequestUtils contains the executeItemQuery utility method used by a collection resource endpoint to generate a listing response based on a query.
If a collection endpoint uses the executeItemQuery method, the endpoint does not need to create its own listing request or response. However, the listing response generated by the executeItemQuery must still be added to the RepresentationModel.
For example:
// Execute an rql query based on the 'q' query parameter value to return
// skus
ListingResponse<RepositoryItem> response;
try {
response = ListingRequestUtils.executeItemQuery(
LinkUtils.instance().getCurrentQueryParameters(),
getCatalogTools().getCatalog().getItemDescriptor("sku"),
"id");
} catch (Exception e) {
throw RestUtils.createException("Failed to query for skus", e);
}A client can provide offset and limit query parameters that specifies the offset and size limit of the page. In addition, if the client wants the total number of items in the collection to be included in the response, the client can specify totalResults=true as a query parameter.
