# (DD20) Business Logic — Owner.addPet() [5 LOC]

| Field | Value |
|-------|-------|
| Fully Qualified Name | `org.springframework.samples.petclinic.owner.Owner` |
| Layer | Domain Model / Entity |
| Module | `owner` (Package: `org.springframework.samples.petclinic.owner`) |

## 1. Role

### Owner.addPet()

This method performs the owner-side enrollment of a `Pet` into the owner aggregate. Its business responsibility is intentionally narrow: if the supplied pet has not yet been persisted or otherwise assigned an identity, the method appends it to the owner's pet collection so that the new animal becomes part of the owner's household record. In practice, this is the domain-level hook used by the UI flow when a user creates a new pet for an owner.

The method implements a simple routing/guard pattern based on entity state. It branches only on the `pet.isNew()` condition, which separates a newly created pet from an existing one. New pets are attached to the owner; existing pets are ignored because updates are handled through a different path elsewhere in the system. As a result, this method acts as a shared aggregate helper rather than a standalone business process.

Within the larger system, `addPet()` supports owner maintenance screens and controller workflows that need to construct or extend the owner's pet list before persistence. It is not responsible for validation, duplication checks, or database access. Those concerns are handled by the controller and repository/service layers, while this method keeps the in-memory owner graph consistent.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["addPet(pet)"])
    CHECK_NEW{"pet.isNew()"}
    ADD_PET["getPets().add(pet)"]
    END_NODE(["Return"])

    START --> CHECK_NEW
    CHECK_NEW -- "true" --> ADD_PET
    CHECK_NEW -- "false" --> END_NODE
    ADD_PET --> END_NODE
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `pet` | `Pet` | Pet entity to be associated with the current owner; when it is a new pet, the method adds it to the owner's pet collection so it can later be saved as part of the owner aggregate. |

External state read by the method:
- `pet.isNew()` determines whether the pet is treated as a new business object.
- `getPets()` reads the owner's internal pet collection.

## 4. CRUD Operations / Called Services

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

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `Owner.getPets` | Owner | - | Calls `getPets` in `Owner` |

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

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `pet.isNew` | `Pet` | `Pet` | Reads the pet state to determine whether the pet has already been created/persisted. |
| R | `getPets` | `Owner` | Owner aggregate pet collection | Reads the owner's pet collection before appending the new pet. |
| C | `getPets().add` | `Owner` | Owner aggregate pet collection | Adds a newly created pet to the owner's in-memory pet list so it can be saved with the aggregate. |

## 5. Dependency Trace

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | Screen:PetController | `PetController.initCreationForm` -> `Owner.addPet` | `getPets().add [C] Owner pet collection` |
| 2 | Screen:PetController | `PetController.processCreationForm` -> `Owner.addPet` | `getPets().add [C] Owner pet collection` |
| 3 | Screen:PetController | `PetController.updatePetDetails` -> `Owner.addPet` | `getPets().add [C] Owner pet collection` |
| 4 | Test:PetControllerTests | `PetControllerTests` -> `Owner.addPet` | `getPets().add [C] Owner pet collection` |
| 5 | Test:VisitControllerTests | `VisitControllerTests` -> `Owner.addPet` | `getPets().add [C] Owner pet collection` |
| 6 | Test:OwnerControllerTests | `OwnerControllerTests` -> `Owner.addPet` | `getPets().add [C] Owner pet collection` |
| 7 | Test:ClinicServiceTests | `ClinicServiceTests` -> `Owner.addPet` | `getPets().add [C] Owner pet collection` |

## 6. Per-Branch Detail Blocks

**Block 1** — IF `(pet.isNew())` (L97)

> Checks whether the supplied pet is a newly created business object and therefore eligible to be attached to the owner.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `pet.isNew()` // evaluates the creation state of the pet |

**Block 1.1** — THEN branch `(pet.isNew() == true)` (L98)

> Adds the new pet to the owner's pet collection.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `getPets()` // obtains the owner's current pet list |
| 2 | EXEC | `getPets().add(pet)` // appends the new pet to the owner |

**Block 1.2** — ELSE branch `(pet.isNew() == false)` (L99-L100)

> Skips collection mutation because the pet is not new and should be handled by the update workflow instead.

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return;` // exits without modifying the owner's pet list |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `Owner` | Domain entity | Pet owner aggregate root representing a customer or household that can register and manage pets. |
| `Pet` | Domain entity | Animal record associated with an owner, including identity and descriptive details used in registration and visit flows. |
| `addPet` | Business action | Owner-level operation that attaches a new pet to the owner's household record. |
| `isNew()` | Domain method | Indicates whether a pet has not yet been persisted or assigned a stable identity. |
| `getPets()` | Domain accessor | Returns the owner's in-memory collection of associated pets. |
| aggregate | Domain modeling term | A consistency boundary that groups an owner and their pets so they can be managed together. |
| CRUD | Technical acronym | Create, Read, Update, Delete — standard data operation categories used for method classification. |
| controller | Technical layer | Web entry point that orchestrates user actions and delegates to domain objects. |
| PetController | Component | Spring MVC controller that handles owner pet creation and update screens. |
| VisitControllerTests | Test class | Test coverage that exercises owner/pet relationships through visit-related flows. |
| OwnerControllerTests | Test class | Test coverage that exercises owner-related UI and domain interactions. |
| ClinicServiceTests | Test class | Service-level tests covering the clinic workflow and aggregate behavior. |