9.5 Pagination
dbVisitor pagination revolves around two core types: input PageObject describing the request, and output PageResult carrying the result.
Input: Creating a Page Request
Static factory (recommended)
Page page = PageObject.of(0, 20); // Page 0, 20 per page, 0-based
Page oneBasedPage = PageObject.of(1, 20, 1); // Page 1, 20 per page, 1-based
Constructor
PageObject page = new PageObject();
page.setPageSize(20); // Page size (default 0; explicitly set a positive value)
page.setCurrentPage(2); // Current page number
page.setPageNumberOffset(1); // Page offset: 1 means first page is 1 (default 0)
Core properties:
| Property | Description |
|---|---|
pageSize | Records per page, default 0; explicitly set a positive value for pagination |
currentPage | Current page number |
pageNumberOffset | Starting page offset. Set 1 for 1-based pages; default 0 |
Navigation: firstPage() / previousPage() / nextPage() / lastPage().
Output: Reading Paginated Results
When an API returns PageResult<T>, read pagination stats:
PageResult<User> result = mapper.pageBySample(sample, pageInfo);
List<User> data = result.getData(); // Current page data
long total = result.getTotalCount(); // Total record count
long pages = result.getTotalPage(); // Total page count
long position = result.getFirstRecordPosition(); // First record position
Use result.getData() to obtain and iterate the current page's list.
Using Pagination Across APIs
The PageObject itself is universal; integration varies by API:
| API | How to paginate | Return type |
|---|---|---|
| Builder API | lambda.query(...).initPage(10, 0) or .usePage(page) | List<T> |
| BaseMapper | mapper.pageBySample(sample, page) | PageResult<T> (with stats) |
| Annotation Mapper | Add Page parameter to method signature | List<T> or PageResult<T> |
| Mapper File | Add Page parameter to method signature | List<T> or PageResult<T> |
Detailed usage per API:
Data Source Differences
Pagination objects are database-independent, while page SQL, total-count SQL, and execution boundaries depend on the data source:
- MySQL, PostgreSQL, Oracle, SQL Server
- DB2, Dameng, ClickHouse, H2