> ## Documentation Index
> Fetch the complete documentation index at: https://docs.law4devs.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> How pagination works in the Law4Devs Java SDK.

## Overview

All `list()` methods return a `Page<T>` object. Every page includes the data list, metadata about the total result set, and links to the next/previous page.

***

## The `Page` Object

```java theme={null}
Page<ArticleSummary> page = client.articles().list("gdpr");

// Data
List<ArticleSummary> articles = page.data();      // items on this page
int count = page.data().size();                    // number of items returned

// Metadata
int total   = page.meta().total();    // total results across all pages
int current = page.meta().page();     // current page number
int perPage = page.meta().perPage();  // items per page
int pages   = page.meta().pages();    // total number of pages

// Links
String nextUrl = page.links().next(); // URL of next page (null if last)
String prevUrl = page.links().prev(); // URL of previous page (null if first)
```

<Note>
  All model fields in Java records are accessed via method calls (e.g. `page.meta().total()`, not `page.meta().total`).
</Note>

***

## Manual Pagination

Control pagination yourself with `page` and `perPage` parameters:

```java theme={null}
int pageNum = 1;
Page<ArticleSummary> page;

do {
    page = client.articles().list("gdpr", pageNum, 50);

    for (ArticleSummary a : page.data()) {
        System.out.println(a.title());
    }

    pageNum++;
} while (page.links().next() != null);
```

***

## Auto-Pagination with `iter()`

Every resource exposes an `iter()` method that automatically fetches all pages and yields individual items:

```java theme={null}
// Yields ArticleSummary one by one — no manual paging needed
for (ArticleSummary a : client.articles().iter("gdpr")) {
    System.out.println(a.number() + " " + a.title());
}
```

Internally, `iter()` uses `PageIterator<T>`, which calls `list()` repeatedly and follows `links().next()` until there are no more pages.

<Tip>
  Use `iter()` whenever you need all items. It handles pagination transparently without loading the full result set into memory at once — each page is fetched only when the previous one is exhausted.
</Tip>

***

## Collecting into a List

If you need all results in a `List`, iterate and collect:

```java theme={null}
var all = new java.util.ArrayList<ArticleSummary>();
for (ArticleSummary a : client.articles().iter("cra")) {
    all.add(a);
}
System.out.println(all.size() + " total articles");
```

Or with streams:

```java theme={null}
import java.util.stream.StreamSupport;

var all = StreamSupport
    .stream(client.articles().iter("cra").spliterator(), false)
    .toList();
System.out.println(all.size() + " total articles");
```

***

## Early Stopping

Break out of an `iter()` loop at any point — no extra pages are fetched after the break:

```java theme={null}
for (ArticleSummary a : client.articles().iter("gdpr")) {
    if (a.number().equals("50")) {
        System.out.println("Found Art. 50: " + a.title());
        break;
    }
}
```

***

## Progress Reporting

```java theme={null}
Page<ArticleSummary> first = client.articles().list("gdpr", 1, 20);
int total = first.meta().total();
int processed = 0;

for (ArticleSummary a : client.articles().iter("gdpr")) {
    processed++;
    System.out.printf("\r%d / %d", processed, total);
}
System.out.println();
```

***

## Pagination Parameters

| Parameter | Type  | Default | Description              |
| --------- | ----- | ------- | ------------------------ |
| `page`    | `int` | `1`     | Page number (1-indexed)  |
| `perPage` | `int` | `20`    | Items per page (max 100) |