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

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

## 1. Role

### Owner.addPet()

This method encapsulates a small but important ownership rule in the Petclinic domain: a pet is attached to an owner only when the pet is still new and has not yet been persisted. In practical business terms, it acts as a guardrail that prevents duplicate association work for pets that already exist in the database while still allowing newly created pets to be collected under the owner aggregate.

The method implements a simple routing/validation pattern. It first checks the lifecycle state of the `Pet` object through `pet.isNew()`, then conditionally delegates to the owner’s pet collection via `getPets().add(pet)`. There are no alternative service categories or multiple business branches beyond the new-pet path and the non-new no-op path.

Within the larger system, `Owner.addPet()` is an aggregate helper used by screens, controllers, and tests when binding a pet to an owner. It supports the domain model’s consistency by keeping pet management local to the `Owner` entity rather than requiring callers to manipulate the collection directly. The method therefore acts as a shared business utility for maintaining the owner-to-pet relationship in memory before persistence.

## 2. Processing Pattern (Detailed Business Logic)

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

    START --> IF_NEW
    IF_NEW -->|true| ADD_PET
    IF_NEW -->|false| END_NODE
    ADD_PET --> END_NODE
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `pet` | `Pet` | The pet candidate to be associated with this owner. It represents the animal record being prepared for registration or editing in the owner aggregate. If the pet is marked as new, it is appended to the owner’s pet collection; otherwise, the method leaves the collection unchanged. |

Also read by this method:
- Instance field `pets` via `getPets()`.
- Lifecycle state of the `Pet` argument via `pet.isNew()`.

## 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.
Use the pre-computed evidence above. If SC Code or Entity/DB is missing, try to infer from:
- The **SC Code** (Service Component code, e.g., `EKK0361A010SC`, `EKK1081D010CBS`) — look at the class name of the called method or its containing class.
- The **Entity/DB tables** — search for table name constants (often `KK_T_*` pattern), SQL references, or entity names in the called method’s source code.

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `Owner.getPets` | Owner | `pets` collection | Retrieves the current owner’s in-memory pet list so a new pet can be appended. |
| R | `Pet.isNew` | Pet | `Pet` entity lifecycle state | Reads the pet lifecycle flag to determine whether the pet should be added to the owner collection. |
| C | `List.add` | `java.util.List` | `pets` collection | Appends a new pet instance to the owner’s pet list when the pet has not yet been persisted. |

## 5. Dependency Trace

Trace who calls this method and what this method ultimately calls.
Use the pre-computed evidence and caller search results from Step 2 above.

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

## 6. Per-Branch Detail Blocks

**Block 1** — [IF] `(pet.isNew())` (L98)

> Business gate that ensures only newly created pets are attached to the owner aggregate.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `pet.isNew()` // checks whether the pet has not been persisted yet |

**Block 1.1** — [THEN] `(pet.isNew() == true)` (L98-L100)

| # | Type | Code |
|---|------|------|
| 1 | CALL | `getPets()` // returns the owner’s pet collection |
| 2 | EXEC | `getPets().add(pet);` // adds the new pet to the collection |

**Block 1.2** — [ELSE] `(pet.isNew() == false)` (L98-L100)

| # | Type | Code |
|---|------|------|
| 1 | RETURN | `return;` // no collection change for an existing pet |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|-------------------|
| `Owner` | Domain object | Customer or household account that owns one or more pets in the Petclinic system. |
| `Pet` | Domain object | Animal record associated with an owner. |
| `pet.isNew()` | Lifecycle check | Indicates whether the pet has not yet been persisted and is therefore eligible to be added to the owner collection. |
| `pets` | Field / collection | The owner’s in-memory list of pet records. |
| `getPets()` | Method | Returns the owner’s pet collection for read or update operations. |
| `addPet` | Business method | Owner aggregate helper that attaches a new pet to the owner when the pet is newly created. |
| aggregate | Domain design term | A consistency boundary that groups related objects, here the owner and its pets, under one business root. |
| CRUD | Technical abbreviation | Create, Read, Update, Delete — standard data operation categories used to classify method behavior. |
| Entity | Technical term | Persistent domain object managed by JPA in the application. |
| lifecycle state | Technical term | The persistence state of an object, such as new or existing. |