Converting List to Page Using Spring Data JPA

1. Overview

In this tutorial, we’ll see how we can convert a List<Object> into a Page<Object> using Spring Data JPA. In Spring Data JPA applications, it’s common to retrieve data from a database in a pageable manner. However, there may be situations where we need to convert a list of entities into a Page object for use in a pageable endpoint. For example, we might want to retrieve data from an external API or process data in memory.

We’ll set a simple example to help us visualize the data flow and conversion. We’ll divide our system into RestController, Service, and Repository layers and see how we can work to convert a large set of data retrieved from the database as List<Object> into smaller, more organized pages using the pagination abstractions provided by Spring Data JPA. Finally, we’ll write some tests to observe the pagination in action.

2. Key Pagination Abstractions in Spring Data JPA

Let’s have a brief look at the key abstractions provided by Spring Data JPA that are used in producing paginated data.

2.1. Page

Page is one of the key interfaces provided by Spring Data to facilitate pagination. It provides a way to represent and manage large result sets returned from database queries in a paginated format.

We can then use the Page object to display the required number of records to the user and links to navigate to subsequent pages.

Page encapsulates details such as the content of the page, along with metadata involving pagination details such as page number and page size, whether there is a next or previous page, how many elements are remaining, and the total number of pages and elements.

2.2. Pageable

Pageable is an abstract interface for pagination information. The concrete class that implements this interface is PageRequest. It represents the pagination metadata, such as the current page number, the number of elements per page, and the sorting criteria. It’s an interface in Spring Data JPA that provides a convenient way to specify pagination information for a query or, in our case, to bundle the paging information together with the contents to create the Page<Object> from a List<Object>.

2.3. PageImpl

Finally, there’s the PageImpl class, which provides a convenient implementation of the Page interface that can be used to represent a page of results from a query, including the pagination metadata. It’s commonly used in conjunction with Spring Data’s repository interfaces and pagination mechanisms to retrieve and manipulate data in a pageable manner.

Now that we’ve got a basic understanding of the involved components, let’s set up a simple example.

3. Example Setup

Let’s consider a simple example of a customer information microservice, with a REST endpoint that can get paginated customer data based on the request parameters. We’ll set up the required dependencies first in the POM. The required dependencies are spring-boot-starter-data-jpa and spring-boot-starter-web, and we’ll also add spring-boot-starter-test for testing purposes:

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependendencies>

Next. let’s set up the REST Controller.

3.1. Customer Controller

First off, let’s add the appropriate method with the request parameters that will drive our logic in the service layer:

@GetMapping("/api/customers")
public ResponseEntity<Page<Customer>> getCustomers(@RequestParam(defaultValue = "0") int page, @RequestParam(defaultValue = "10") int size) {

    Page<Customer> customerPage = customerService.getCustomers(page, size);
    HttpHeaders headers = new HttpHeaders();
    headers.add("X-Page-Number", String.valueOf(customerPage.getNumber()));
    headers.add("X-Page-Size", String.valueOf(customerPage.getSize()));

    return ResponseEntity.ok()
      .headers(headers)
      .body(customerPage);
}

Here, we can see that the getCustomers method is expecting a ResponseEntity of type Page<Customer>.

3.2. Customer Service

Next, let’s set up our service class that will interact with the repository, convert the data into the required Page, and return it to the Controller:

public Page<Customer> getCustomers(int page, int size) {

    List<Customer> allCustomers = customerRepository.findAll();
//... logic to convert the List<Customer> to Page<Customer>
//... return Page<Customer>
}

Here, we’ve omitted the details, just focusing on the fact that the service calls the JPA repository and is getting a potentially large set of Customer data as List<Customer>. Next, let’s look into the details of how we can use the JPA-provided API to convert this list into Page<Customer>.

4. Converting List<Customer> to Page<Customer>

Now, let’s furnish the details of how the CustomerService can convert the List<Customer> received from CustomerRepository into a Page object. Essentially, after retrieving a list of all customers from the database, we want to create a Pageable object using the PageRequest factory method:

private Pageable createPageRequestUsing(int page, int size) {
    return PageRequest.of(page, size);
}

Note that these page and size parameters are the ones passed down as request parameters from our CustomerRestController to CustomerService.

We’ll then split the large list of Customer into a sub-list. We need to know the start and end indices, based on which we can create a sub-list. This can be calculated using the getOffset() and getPageSize() methods of the Pageable object:

int start = (int) pageRequest.getOffset();

Next, let’s get the end index:

int end = Math.min((start + pageRequest.getPageSize()), allCustomers.size());

This sublist will form the content of our Page object:

 List<Customer> pageContent = allCustomers.subList(start, end);

Finally, we’ll create an instance of PageImpl. It will encapsulate the pageContent as well as the pageRequest  along with the total size of the List<Customer>:

new PageImpl<>(pageContent, pageRequest, allCustomers.size());

Let’s put all the pieces together in one place:

public Page<Customer> getCustomers(int page, int size) {

    Pageable pageRequest = createPageRequestUsing(page, size);

    List<Customer> allCustomers = customerRepository.findAll();
    int start = (int) pageRequest.getOffset();
    int end = Math.min((start + pageRequest.getPageSize()), allCustomers.size());

    List<Customer> pageContent = allCustomers.subList(start, end);
    return new PageImpl<>(pageContent, pageRequest, allCustomers.size());
}

5. Converting Page<Customer> to List<Customer>

Pagination is an important feature to consider when working with a large result set. It can significantly enhance the data organization by breaking it down into smaller parts called pages.

Spring data provides a convenient way to support pagination. To add paging in a query method, we need to change the signature to accept a Pageable object as an argument and return Page<T> instead of List<T>.

Typically, the returned Page object denotes a portion of the result. It holds information about the list of elements, the number of all elements, and the number of pages.

For instance, let’s see how we get the list of customers of a given page:

public List<Customer> getCustomerListFromPage(int page, int size) {
    Pageable pageRequest = createPageRequestUsing(page, size);
    Page<Customer> allCustomers = customerRepository.findAll(pageRequest);

    return allCustomers.hasContent() ? allCustomers.getContent() : Collections.emptyList();
}

As we can see, we used the same createPageRequestUsing() factory method to create a Pageable object. Then, we called the getContent() method to get the returned page as a list of customers.

Please note that we used the hasContent() method to check whether the page has content before calling getContent().

6. Testing the Service

Let’s write a quick test to see that the List<Customer> is split into Page<Customer> and that the page size and page number are correct. We’ll mock the customerRepository.findAll() method to return the list of Customer having size 20.

In the setup, we simply provide this list when findAll() is called:

@BeforeEach
void setup() {
    when(customerRepository.findAll()).thenReturn(ALL_CUSTOMERS);
}

Here, we’re constructing a parameterized test and asserting on the contents, content size, total elements, and total pages:

@ParameterizedTest
@MethodSource("testIO")
void givenAListOfCustomers_whenGetCustomers_thenReturnsDesiredDataAlongWithPagingInformation(int page, int size, List<String> expectedNames, long expectedTotalElements, long expectedTotalPages) {
    Page<Customer> customers = customerService.getCustomers(page, size);
    List<String> names = customers.getContent()
      .stream()
      .map(Customer::getName)
      .collect(Collectors.toList());

    assertEquals(expectedNames.size(), names.size());
    assertEquals(expectedNames, names);
    assertEquals(expectedTotalElements, customers.getTotalElements());
    assertEquals(expectedTotalPages, customers.getTotalPages());}

Finally, the test data input and output for this parametrized test are:

private static Collection<Object[]> testIO() {
    return Arrays.asList(
      new Object[][] {
        { 0, 5, PAGE_1_CONTENTS, 20L, 4L },
        { 1, 5, PAGE_2_CONTENTS, 20L, 4L },
        { 2, 5, PAGE_3_CONTENTS, 20L, 4L },
        { 3, 5, PAGE_4_CONTENTS, 20L, 4L },
        { 4, 5, EMPTY_PAGE, 20L, 4L } }
    );
}

Each test runs the service method with a different pair of page sizes (0,1,2,3,4), and each is expected to have 5 elements. We expect the total number of pages to be 4 since the total size of the original list is 20. Lastly, each page is expected to contain 5 elements.

Now, we’re going to add test cases for converting Page<Customer> to List<Customer>. First, let’s test the scenario where the Page object is not empty:

@Test
void givenAPageOfCustomers_whenGetCustomerList_thenReturnsList() {
    Page<Customer> pagedResponse = new PageImpl<Customer>(ALL_CUSTOMERS.subList(0, 5));
    when(customerRepository.findAll(any(Pageable.class))).thenReturn(pagedResponse);

    List<Customer> customers = customerService.getCustomerListFromPage(0, 5);
    List<String> customerNames = customers.stream()
      .map(Customer::getName)
      .collect(Collectors.toList());

    assertEquals(PAGE_1_CONTENTS.size(), customers.size());
    assertEquals(PAGE_1_CONTENTS, customerNames);
}

Here, we mocked the invocation of the customerRepository.findAll(pageRequest) method to return a Page object holding a portion of the ALL_CUSTOMERS list. As a result, the returned customer list is the same as the wrapped one in the given Page object.

Next, let’s see what happens if customerRepository.findAll(pageRequest) returns an empty page:

@Test
void givenAnEmptyPageOfCustomers_whenGetCustomerList_thenReturnsEmptyList() {
    Page<Customer> emptyPage = Page.empty();
    when(customerRepository.findAll(any(Pageable.class))).thenReturn(emptyPage);
    List<Customer> customers = customerService.getCustomerListFromPage(0, 5);

    assertThat(customers).isEmpty();
}

Unsurprisingly, the returned list is empty.

7. Testing the Controller

Finally, let’s also test the Controller to make sure we’re getting the ResponseEntity<Page<Customer>> back as JSON. We’ll use MockMVC to send a request to the GET endpoint and expect the paged response with the expected parameters:

@Test
void givenTotalCustomers20_whenGetRequestWithPageAndSize_thenPagedReponseIsReturnedFromDesiredPageAndSize() throws Exception {

    MvcResult result = mockMvc.perform(get("/api/customers?page=1&size=5"))
      .andExpect(status().isOk())
      .andReturn();

    MockHttpServletResponse response = result.getResponse();

    JSONObject jsonObject = new JSONObject(response.getContentAsString());
    assertThat(jsonObject.get("totalPages")).isEqualTo(4);
    assertThat(jsonObject.get("totalElements")).isEqualTo(20);
    assertThat(jsonObject.get("number")).isEqualTo(1);
    assertThat(jsonObject.get("size")).isEqualTo(5);
    assertThat(jsonObject.get("content")).isNotNull();}

Essentially, we are using a MockMvc instance to simulate an HTTP GET request to the /api/customers endpoint. We’re providing the query parameters page=1 and size=5. We then expect a successful response and a body containing page metadata and content.

Finally, let’s take a quick look at how converting a List<Customer> to Page<Customer> can benefit the API design and consumption.

8. Benefits of Using Page<Customer> Over List<Customer>

Choosing to return Page<Customer> over the entire List<Customer> as an API response in our example can have some benefits depending upon the use case. One of the benefits is optimized network traffic and processing. Essentially here, if the underlying data source returns a large list of customers, converting it to a Page<Customer> allows the client to request only a specific page of results, rather than the entire list. This can lead to simplified processing at the client and reduce network load.

Additionally, by returning a Page<Customer>, the API provides a standardized response format that clients can easily understand and consume. The Page<Customer> object contains the list of customers for the requested page and metadata such as the total number of pages and the number of items per page.

Finally, converting the list of objects to a page provides flexibility in the API design. For example, the API can allow clients to sort the results by different fields. We can also filter the results based on criteria, or even return a subset of fields for each customer.

9. Conclusion

In this tutorial, we used Spring Data JPA to handle conversion between a List<Object> and a Page<Object>. We used the API provided by Spring Data JPA including Page, Pageable, and PageImpl classes. Finally, we briefly looked into some of the benefits of using Page<Object> over List<Object>.

In summary, converting a List<Object> to a Page<Object> in a REST endpoint provides a more efficient, standardized, and flexible way to handle large datasets and implement pagination in the API.