Collection Page Service

Auxiliary classes and utilities are provided to ease defining of collection resources which support paging and implementing pagination in the context of a stateless server:

• paginated collection resource definition and utilities – ease implementation of resource pagination for collection resources;
• paging service – associates unique identifiers to collection page accessors encapsulating a shallow copy of the collection for pagination, thus paging forth and back through the collection resource remains consistent and resistant to changes that may occur in the underlying collection in time.

These auxiliaries are exported via the com.prosyst.mbs.services.rest.pagination package and reflect the common behaviors and definitions. Examples are provided in the Paging for Collection Resources Using the REST Auxiliaries guide.

The following diagram describes the main entities and their relationships:

For large data sets, e.g. devices, groups and functional items, limiting the amount of data returned is important from a bandwidth standpoint. But it is also important from a UI processing standpoint as a UI often can only display a small portion of a huge data set. In cases where the data set grows indefinitely, it is helpful to limit the amount of data returned by default. Aside from limiting the amount of data returned, we also need to consider how to "page" or scroll through that large data set if more than that first subset needs retrieval. This is referred to as pagination creating "pages" of data, returning known sections of a larger list and being able to page "forward" and "backward" through that large data set.

The Collection Page service provides means to ease development of RESTful web services that take advantage of collection resource pagination. The service associates unique identifiers (generally derived from the HTTP session identifier and the request URI) to {{CollectionPageAccessor}}s instances encapsulating a shallow copy of the collection for pagination, thus paging forth and back through the collection resource remains consistent and resistant to changes that may occur in the underlying collection in time.

More details on the main entities can be derived from the Java APIs.

The configurable parameters of the service – maximum age of an accessor (time to cache an iterator), maximum count of cached accessors, whether to refresh the age of an accessor when it is looked up through the service or not, are described in the REST Core Bundle Paging Service Configuration of the Setup Guide.

Registering Bundle

The Collection Page service is registered by REST Core Bundle.