---
# (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 adds a new medical visit record to a specific pet owned by the current `Owner` aggregate. It performs a domain-level association step: it validates that both the target pet identifier and the `Visit` object are present, resolves the pet from the owner's owned pets, and then delegates the association to the `Pet` entity. In business terms, the method supports the booking or recording of a veterinary consultation against the correct animal record.

The method uses a simple routing / delegation pattern. It does not persist data directly and does not contain branching business rules beyond null validation and target-pet resolution. Instead, it acts as an aggregate-root helper that enforces ownership boundaries: only a pet already associated with this owner can receive the visit. In the larger system, it is a shared domain method called by the visit registration flow in the web layer before the owner is saved.

## 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["getPet(petId)"]
    D{"pet found?"}
    E["Assert pet is not null"]
    F["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` | Identifier of the pet that should receive the new visit. It must correspond to a pet already owned by this owner; otherwise the method fails fast with a domain validation error. |
| 2 | `visit` | `Visit` | The visit record to attach to the selected pet. It represents the clinical appointment or consultation information that will be associated with the pet's medical history. |

External state read by the method:
- Owner's internal pet collection through `getPet(petId)`.
- The selected `Pet` aggregate's visit collection 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 | - | Resolves a pet belonging to the current owner by identifier |

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` (owner-owned collection) | Reads the owner's pet collection to locate the target pet by ID |
| C | `Pet.addVisit` | Pet | `Visit` (pet visit collection) | Creates a new association between the pet and the visit record |

Notes:
- `Assert.notNull(...)` is validation logic, not a business CRUD operation.
- No persistence repository or database table is accessed directly in this method.

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

## 6. Per-Branch Detail Blocks

**Block 1** — `ASSERT` `(petId must not be null)` (L167)

> Ensures the caller specifies the target pet identifier before any lookup is attempted.

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

**Block 2** — `ASSERT` `(visit must not be null)` (L168)

> Ensures the visit payload exists before the association is created.

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

**Block 3** — `CALL` `(resolve pet by identifier)` (L170)

> Loads the pet from the owner's existing pet collection.

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

**Block 4** — `ASSERT` `(pet must not be null)` (L172)

> Fails fast if the pet identifier does not belong to the current owner.

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

**Block 5** — `CALL` `(attach visit to pet)` (L174)

> Adds the visit to the selected pet's visit collection.

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

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `Owner` | Domain entity | Customer or pet owner record in the Petclinic domain |
| `Pet` | Domain entity | Animal owned by an owner and eligible for visits |
| `Visit` | Domain entity | Veterinary appointment / consultation record for a pet |
| `petId` | Field | Identifier used to select the target pet within the owner aggregate |
| `Assert.notNull` | Technical validation | Spring utility that enforces required input and raises an exception if the value is missing |
| `addVisit` | Business action | Attaches a visit to a pet's medical history |
| `visit collection` | Domain concept | In-memory collection of visit records linked to a pet |
| `aggregate root` | Architectural term | The owning domain object responsible for maintaining consistency across related child entities |
| `ownership boundary` | Business term | Rule that a pet must belong to the owner before a visit can be added |
| `screen` | UI term | Web entry point that initiates the visit registration flow |
| `visit registration flow` | Business process | User journey for creating a new veterinary visit for a pet |
---