---
# (DD27) Business Logic — OwnerController.findPaginatedForOwnersLastName() [5 LOC]

| Field | Value |
|-------|-------|
| Fully Qualified Name | `org.springframework.samples.petclinic.owner.OwnerController` |
| Layer | Controller |
| Module | `owner` (Package: `org.springframework.samples.petclinic.owner`) |

## 1. Role

### OwnerController.findPaginatedForOwnersLastName()

This method is a focused pagination-and-query helper for the owner search workflow in the PetClinic owner management screen. It converts a 1-based UI page number into a Spring Data `PageRequest`, fixes the page size at five owners per page, and delegates the actual search to the repository layer using a last-name prefix match. In business terms, it supports the owner lookup use case by narrowing the search to owners whose family name starts with the entered text, which is consistent with the broader search behavior in the controller. The method does not branch by service type; instead, it implements a simple routing/delegation pattern that prepares paging criteria and forwards the request to persistence. It functions as an internal controller utility that keeps the form-processing method (`processFindForm`) small and separates presentation-level pagination setup from data retrieval. Because the returned value is a `Page<Owner>`, it also carries both the current result slice and total-result metadata needed by the UI to render either a single-owner redirect, a no-result message, or a paginated owner list.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START["findPaginatedForOwnersLastName(page, lastname)"]
    SET_PAGESIZE["Set pageSize = 5"]
    CALC_PAGEABLE["Create pageable = PageRequest.of(page - 1, pageSize)"]
    CALL_REPO["Call owners.findByLastNameStartingWith(lastname, pageable)"]
    RETURN_NODE["Return Page<Owner>"]

    START --> SET_PAGESIZE
    SET_PAGESIZE --> CALC_PAGEABLE
    CALC_PAGEABLE --> CALL_REPO
    CALL_REPO --> RETURN_NODE
```

The method has no conditional branches, loops, or exception handling. Its processing is linear: it establishes a fixed page size, converts the incoming page number into zero-based pagination coordinates, and delegates to the repository query that performs the prefix search.

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `page` | `int` | The requested UI page number for owner search results. It is expected to be 1-based from the browser or controller entry point and is converted to a zero-based index for Spring Data pagination. If the value changes, it directly shifts which subset of owners is returned. |
| 2 | `lastname` | `String` | The owner last-name search key entered by the user. It is used as a prefix filter, so any owner whose last name starts with this value can be included in the returned page. Broader values return more owners; narrower values return fewer or none. |

**Instance fields / external state read by the method:**
- `owners` — the injected `OwnerRepository` used to execute the database query.
- Spring Data paging infrastructure via `PageRequest.of(...)`.

## 4. CRUD Operations / Called Services

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `findByLastNameStartingWith` | N/A | `Owner` | Reads paginated owner records whose last name begins with the supplied search string. |

The method performs a single read operation through the repository layer. No create, update, or delete behavior is present in this method.

## 5. Dependency Trace

### Pre-computed evidence from code analysis graph:

| # | Caller (Screen/Batch) | Call Chain (Full Path to Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|----------------------------------|-------------------------------|
| 1 | Controller:OwnerController | `OwnerController.processFindForm` -> `OwnerController.findPaginatedForOwnersLastName` | `findByLastNameStartingWith [R] Owner` |

Trace who calls this method and what this method ultimately calls.

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | Controller:OwnerController | `OwnerController.processFindForm` -> `OwnerController.findPaginatedForOwnersLastName` | `findByLastNameStartingWith [R] Owner` |

The only direct caller is `processFindForm` in the same controller. That caller is the owner-search entry point for the `/owners` request, and it delegates to this helper to fetch the correct page of matching owners before deciding whether to show a list, redirect to a single owner, or report no results. The helper then terminates at the repository read operation and does not invoke any deeper business service or batch component.

## 6. Per-Branch Detail Blocks

**Block 1** — [SEQUENTIAL] `(method entry)` (L130)

> Initializes the paginated search workflow for owner last-name lookup.

| # | Type | Code |
|---|------|------|
| 1 | SET | `int pageSize = 5;` // fixed page size for owner search results |

**Block 2** — [SEQUENTIAL] `(pagination conversion)` (L132)

> Converts the 1-based page number from the controller layer into the zero-based index required by Spring Data.

| # | Type | Code |
|---|------|------|
| 1 | SET | `Pageable pageable = PageRequest.of(page - 1, pageSize);` // create pageable request for the requested slice |

**Block 3** — [SEQUENTIAL] `(repository delegation)` (L133)

> Executes the owner lookup using a last-name prefix search and returns the paged result set.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `owners.findByLastNameStartingWith(lastname, pageable);` // read owners whose last name starts with the supplied text |
| 2 | RETURN | `return owners.findByLastNameStartingWith(lastname, pageable);` // return `Page<Owner>` to caller |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `page` | Field | Requested results page number in the owner search UI; the controller treats it as 1-based input from the user. |
| `lastname` | Field | Search key used to find owners by family name prefix. |
| `lastName` | Field | JavaBean property on `Owner` representing the owner’s family name. |
| `Owner` | Domain object | PetClinic customer record representing a pet owner and their contact details. |
| `Page` | Technical term | Spring Data paged result wrapper containing the current result slice plus paging metadata. |
| `Pageable` | Technical term | Spring Data pagination descriptor that carries page index, size, and sorting information. |
| `PageRequest` | Technical term | Spring Data factory used to create a `Pageable` instance. |
| `owners` | Component | Injected `OwnerRepository` used by the controller to query owner records. |
| `findByLastNameStartingWith` | Repository method | Data-access query that returns owners whose last name starts with the supplied text. |
| `last name prefix search` | Business term | Search behavior that matches any owner whose family name begins with the entered text. |
| `controller` | Layer | Web layer component that handles HTTP requests and prepares data for the view. |
| `repository` | Layer | Persistence abstraction responsible for reading owner data from the database. |
| `PetClinic` | Application name | Sample veterinary clinic application used as the business context for owners, pets, and visits. |
| `owner search` | Business process | The user-facing flow for locating owner records by name before viewing or editing them. |
| `pagination` | Business/technical term | Splitting a large result set into fixed-size pages for easier UI navigation. |
| `prefix match` | Business term | Search rule where a record is returned if its last name begins with the supplied value. |
| `UI` | Acronym | User Interface — the browser-based screen where the user submits the owner search. |
| `CRUD` | Acronym | Create, Read, Update, Delete — standard categories for data operations. |
| `Spring Data` | Technical term | Framework layer that generates repository queries and pagination support from method signatures. |
| `1-based` | Technical term | Numbering convention where the first page is page 1 rather than page 0. |
| `0-based` | Technical term | Numbering convention where the first page is page 0, required by Spring Data pagination APIs. |