# (DD40) Business Logic — ClinicServiceTests.shouldInsertOwner() [18 LOC]

| Field | Value |
|-------|-------|
| Fully Qualified Name | `org.springframework.samples.petclinic.service.ClinicServiceTests` |
| Layer | Service |
| Module | `service` (Package: `org.springframework.samples.petclinic.service`) |

## 1. Role

### ClinicServiceTests.shouldInsertOwner()

This method verifies the end-to-end persistence behavior for a new Petclinic owner record within the service/data-access test slice. It first establishes a baseline count of owners whose last name begins with `Schultz`, then creates a new `Owner` instance with a complete set of business contact details and saves it through the injected repository. After the insert, it confirms that the new owner has been assigned a generated identifier and that the search result count for the same last-name prefix increased by exactly one.

From a business perspective, the method validates the core owner onboarding flow: adding a customer/household profile to the clinic registry and making that profile immediately visible to search-by-last-name use cases. The processing pattern is a straightforward arrange-act-assert sequence with repository delegation, using a read-before-write-read verification strategy to prove that persistence and query indexing are both functioning. There are no conditional branches in the method; its single execution path covers owner insertion and post-insert verification.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["shouldInsertOwner()"])
    READ_BEFORE(["Read current owner count by last name prefix 'Schultz'"])
    SAVE_OWNER(["Create Owner and populate first name, last name, address, city, telephone"])
    CALL_SAVE(["Call owners.save(owner)"])
    ASSERT_ID(["Assert generated owner id is not zero"])
    READ_AFTER(["Read owner count by last name prefix 'Schultz' again"])
    ASSERT_COUNT(["Assert total owners increased by 1"])
    END_NODE(["Return / Next"])

    START --> READ_BEFORE
    READ_BEFORE --> SAVE_OWNER
    SAVE_OWNER --> CALL_SAVE
    CALL_SAVE --> ASSERT_ID
    ASSERT_ID --> READ_AFTER
    READ_AFTER --> ASSERT_COUNT
    ASSERT_COUNT --> END_NODE
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| - | (none) | - | - |

This method declares no parameters. It relies on instance state from the test class, specifically the injected `owners` repository and the `pageable` paging request used for owner search. The observable business inputs are the hard-coded owner identity and contact values used to simulate a new customer record.

## 4. CRUD Operations / Called Services

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

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `owners.findByLastNameStartingWith` | OwnerRepository | Owner | Reads owners whose last name begins with the given prefix to establish the baseline and verify the post-insert count |

Analyze all method calls within this method and classify each as a CRUD operation.

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `owners.findByLastNameStartingWith` | OwnerRepository | Owner | Queries owner records by last-name prefix before and after insertion |
| C | `owners.save` | OwnerRepository | Owner | Persists a newly created owner and triggers identifier generation |

## 5. Dependency Trace

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 | Test runner / JUnit | `JUnit Platform` -> `ClinicServiceTests.shouldInsertOwner` | `owners.findByLastNameStartingWith [R] Owner` |
| 2 | Test runner / JUnit | `JUnit Platform` -> `ClinicServiceTests.shouldInsertOwner` | `owners.save [C] Owner` |

## 6. Per-Branch Detail Blocks

The method has a single linear control flow with no branches, loops, or exception handling.

**Block 1** — [SEQUENCE] `(L107-L124)`

> Baseline read, owner creation, save, and verification of insert behavior.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `this.owners.findByLastNameStartingWith("Schultz", pageable);` // Read owners with matching last name prefix |
| 2 | SET | `int found = (int) owners.getTotalElements();` // Store baseline owner count |
| 3 | SET | `Owner owner = new Owner();` // Create new owner record |
| 4 | EXEC | `owner.setFirstName("Sam");` // Set owner first name |
| 5 | EXEC | `owner.setLastName("Schultz");` // Set owner last name |
| 6 | EXEC | `owner.setAddress("4, Evans Street");` // Set street address |
| 7 | EXEC | `owner.setCity("Wollongong");` // Set city |
| 8 | EXEC | `owner.setTelephone("4444444444");` // Set telephone number |
| 9 | CALL | `this.owners.save(owner);` // Persist the new owner |
| 10 | EXEC | `assertThat(owner.getId()).isNotZero();` // Verify generated identifier |
| 11 | SET | `owners = this.owners.findByLastNameStartingWith("Schultz", pageable);` // Re-read owner list after insert |
| 12 | EXEC | `assertThat(owners.getTotalElements()).isEqualTo(found + 1);` // Verify count increased by one |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `Owner` | Domain entity | A pet clinic customer record containing identity and contact details for a pet owner |
| `owners` | Repository field | Persistence gateway used to read and store owner records |
| `findByLastNameStartingWith` | Repository query | Searches owners whose last name begins with a supplied prefix |
| `save` | Repository operation | Inserts a new owner record into persistent storage |
| `pageable` | Technical term | Paging instruction used to limit and structure repository query results |
| `firstName` | Field | Owner's given name |
| `lastName` | Field | Owner's family name used for search and identification |
| `address` | Field | Owner's street address |
| `city` | Field | Owner's city of residence |
| `telephone` | Field | Owner's contact phone number |
| `id` | Field | Generated primary identifier assigned after persistence |
| `JUnit` | Framework | Test execution framework that invokes the method |
| `arrange-act-assert` | Pattern | Test structure that prepares data, performs an action, and verifies the outcome |
| `baseline count` | Business term | The number of matching owner records before the insert operation |
| `FTTH` | Acronym | Fiber To The Home — not used in this method |