# (DD19) Business Logic — Owner.addVisit() [11 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.addVisit()

This method performs a domain-level routing operation that attaches a newly prepared `Visit` record to the `Pet` identified by `petId` within the current `Owner` aggregate. It first validates mandatory inputs, then resolves the target pet from the owner's pet collection, and finally delegates the actual visit insertion to the `Pet` entity. Business-wise, it supports visit registration for a specific pet under a known owner, which is the core action behind booking a veterinary visit in the Petclinic flow.

The method represents a lightweight aggregate consistency guard rather than a standalone service. It ensures that visit creation only occurs when the caller has already identified the correct pet and the pet truly belongs to this owner instance. If the pet cannot be found, the method stops with a business validation failure instead of silently creating orphaned visit data. This makes the method a shared domain utility used by the web layer to keep owner-pet-visit relationships consistent.

From a design perspective, the method uses validation, lookup, and delegation patterns. It does not branch by business service type or by visit category; its logic is linear and focused on ownership resolution. The method therefore acts as a small but important coordination point between the web/controller layer and the nested `Pet` entity.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["addVisit(petId, visit)"])
    A["Assert petId is not null"]
    B["Assert visit is not null"]
    C["Resolve target pet with getPet(petId)"]
    D{"pet found?"}
    E["Assert valid pet identifier"]
    F["Delegate visit insertion to pet.addVisit(visit)"]
    END_NODE(["Return / Next"])

    START --> A
    A --> B
    B --> C
    C --> D
    D -- "yes" --> E
    D -- "no" --> E
    E --> F
    F --> END_NODE
```

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `petId` | `Integer` | Business identifier of the target pet under the current owner. It determines which pet receives the visit record and must not be null. If the identifier does not match any pet in the owner aggregate, the method rejects the request. |
| 2 | `visit` | `Visit` | The visit booking information to attach to the selected pet. It represents the new clinical appointment or checkup record and must not be null. The object is forwarded unchanged to the pet-level visit collection. |

External state read by the method:
- The owner's internal pet collection through `getPet(petId)`.
- The target `Pet` entity state through `pet.addVisit(visit)`.

## 4. CRUD Operations / Called Services

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

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `Owner.getPet` | Owner | `Pet` | Locates the pet belonging to this owner by identifier before any visit is attached. |

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

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| R | `Owner.getPet` | Owner | `Pet` | Reads the owner's pet collection to find the pet referenced by `petId`. |
| C | `Pet.addVisit` | Pet | `Visit` | Creates a new association between the pet and the provided visit by adding it to the pet's visit collection. |

## 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 | Controller: `VisitController` | `VisitController.processNewVisitForm` -> `Owner.addVisit` | `Pet.addVisit [C] Visit` |
| 2 | Test: `ClinicServiceTests` | `ClinicServiceTests` -> `Owner.addVisit` | `Pet.addVisit [C] Visit` |

## 6. Per-Branch Detail Blocks

**Block 1** — [IF] `petId must not be null` (L165)

> Validates that the caller supplied a target pet identifier before any domain lookup occurs.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `Assert.notNull(petId, "Pet identifier must not be null!");` |

**Block 2** — [IF] `visit must not be null` (L166)

> Validates that the visit payload exists before the method attempts to attach it to the pet.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `Assert.notNull(visit, "Visit must not be null!");` |

**Block 3** — [EXEC] `resolve target pet` (L168)

> Looks up the pet inside the current owner aggregate using the supplied pet identifier.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `getPet(petId);` |
| 2 | SET | `Pet pet = getPet(petId);` |

**Block 4** — [IF] `pet must exist` (L170)

> Ensures the identifier belongs to one of the owner's pets and prevents invalid visit registration.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `Assert.notNull(pet, "Invalid Pet identifier!");` |

**Block 5** — [EXEC] `delegate visit insertion` (L172)

> Transfers the visit to the selected pet, which owns the actual visit collection.

| # | Type | Code |
|---|------|------|
| 1 | CALL | `pet.addVisit(visit);` |
| 2 | EXEC | `pet.addVisit(visit);` |

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `petId` | Field | Identifier of the pet selected for visit registration. |
| `visit` | Field | Visit record that captures the appointment or clinical visit details. |
| `Owner` | Domain entity | Customer or account holder who owns one or more pets. |
| `Pet` | Domain entity | Animal owned by an owner and eligible to receive visits. |
| `Visit` | Domain entity | A veterinary visit entry associated with a pet. |
| `Assert.notNull` | Technical guard | Validation utility that stops processing when a required value is missing. |
| `getPet` | Domain method | Owner-level lookup that returns the pet matching the supplied identifier. |
| `addVisit` | Domain method | Pet-level operation that appends the visit to the pet's visit collection. |
| `aggregate` | Architectural term | A consistency boundary where related objects are managed together. |
| `booking` | Business term | The act of registering a visit for a specific pet. |