# Org / Springframework / Samples / Petclinic / Owner

## Overview

This package appears to implement the owner-facing workflow in Petclinic: finding and maintaining owners, managing their pets, and recording visits for those pets. It combines a small persistence layer, domain model, and Spring MVC controllers into a single cohesive area that supports the main “owner” journey in the application.

The package is organized around a clear aggregate style. `Owner` is the primary entry point for persistence, with pets and visits managed through the owner’s object graph rather than through separate write paths. That shape keeps the web layer simple: controllers load the owner, attach or update pets and visits, and save the owner back through the repository.

## Sub-module Guide

### Controllers

The controller layer is the interaction boundary for the package. It translates HTTP requests into owner, pet, and visit operations, while also handling view selection, validation feedback, pagination, and redirect behavior.

- [`OwnerController`](src/main/java/org/springframework/samples/petclinic/owner/OwnerController.java:48) manages owner creation, searching, editing, and detail display.
- [`PetController`](src/main/java/org/springframework/samples/petclinic/owner/PetController.java:46) manages pet creation and editing under a specific owner.
- [`VisitController`](src/main/java/org/springframework/samples/petclinic/owner/VisitController.java:41) manages visit creation for a specific pet.

These controllers are tightly related: `OwnerController` starts the workflow, while `PetController` and `VisitController` extend that workflow into nested owner-owned data. The controllers also reinforce the aggregate model by saving through `OwnerRepository` rather than directly persisting pets or visits.

### Other

The “Other” area contains the domain entities and web support classes that make the controllers work.

- [`Owner`](src/main/java/org/springframework/samples/petclinic/owner/Owner.java:47) is the aggregate root for the area.
- [`Pet`](src/main/java/org/springframework/samples/petclinic/owner/Pet.java:44) represents an owner’s animal.
- [`Visit`](src/main/java/org/springframework/samples/petclinic/owner/Visit.java:34) records one appointment for a pet.
- [`PetType`](src/main/java/org/springframework/samples/petclinic/owner/PetType.java:26) provides reference data for valid pet categories.
- [`PetTypeFormatter`](src/main/java/org/springframework/samples/petclinic/owner/PetTypeFormatter.java:36) converts between user-facing text and `PetType` entities.
- [`PetValidator`](src/main/java/org/springframework/samples/petclinic/owner/PetValidator.java:32) applies form-specific validation rules for pets.

These classes are the data and binding foundation for the controllers. `PetTypeFormatter` and `PetValidator` are especially important because they connect the form layer to the underlying domain model: one resolves type selections, the other ensures the submitted pet data is complete enough to save safely.

### Repositorys

The repository layer provides persistence access for the package’s core entities.

- [`OwnerRepository`](src/main/java/org/springframework/samples/petclinic/owner/OwnerRepository.java:36) supports CRUD plus owner search by last-name prefix.
- [`PetTypeRepository`](src/main/java/org/springframework/samples/petclinic/owner/PetTypeRepository.java:30) supplies the list of pet types in name order.

These repositories are the data source for the controller and formatter flows. `OwnerController` uses `OwnerRepository` for search and load/save operations, while `PetController` and `VisitController` also depend on it because pets and visits are saved through the owner aggregate. `PetTypeFormatter` depends on `PetTypeRepository` so it can resolve form-submitted type names into actual reference entities.

## Key Patterns and Architecture

This package follows a classic Spring MVC + Spring Data JPA structure, but with a strong aggregate-oriented domain model.

### Aggregate-centered persistence

The most important architectural choice is that owners are the persistence boundary. Instead of repositories for pets and visits, the controllers load an owner, modify its pets or visits, and save the owner back.

That pattern is visible in several places:

- `OwnerController` handles owner creation and update directly.
- `PetController` mutates the owner’s pet collection and saves the owner.
- `VisitController` adds a visit to a pet through the owner and then saves the owner.

This appears to keep the system consistent by making the owner the single point where ownership relationships are managed.

### Form handling at the web boundary

The controllers take responsibility for the rules that are most naturally enforced during request handling:

- binder restrictions prevent identifier tampering,
- duplicate pet names are checked before save,
- future birth dates are rejected,
- owner ID mismatches are checked during updates,
- visits are validated before being attached to a pet.

This means the package does not rely only on lower-level persistence constraints. Instead, it enforces user-facing rules where they are easiest to explain back to the caller.

### Shared view flows

The package reuses form views for both create and edit actions. That reduces template duplication and suggests the forms are intentionally designed to handle both empty and pre-populated domain objects.

### Request flow diagram

```mermaid
flowchart TD
User["User"] --> OwnerController["OwnerController"]
User --> PetController["PetController"]
User --> VisitController["VisitController"]
OwnerController --> OwnerRepository["OwnerRepository"]
PetController --> OwnerRepository
VisitController --> OwnerRepository
PetController --> PetTypeRepository["PetTypeRepository"]
OwnerController --> OwnerForm["Owner form views"]
PetController --> PetForm["Pet form views"]
VisitController --> VisitForm["Visit form views"]
```

## Dependencies and Integration

This package integrates with the rest of the application primarily through shared model classes and Spring infrastructure.

### Internal and shared dependencies

The package depends on shared base types from `org.springframework.samples.petclinic.model`, especially:

- `Person`
- `NamedEntity`
- `BaseEntity`

These base classes provide common persistence and identity behavior for `Owner`, `Pet`, `PetType`, and `Visit`.

### Spring framework integration

The package uses several Spring features together:

- Spring MVC annotations such as `@Controller`, `@GetMapping`, `@PostMapping`, `@ModelAttribute`, and `@InitBinder`
- Validation via `@Valid`, `BindingResult`, and a custom `Validator`
- Formatting via `Formatter<PetType>`
- Spring Data JPA repositories and pageable queries
- Redirect attributes for post-submit navigation

### Connection to the wider Petclinic system

The package also depends on the rest of the Petclinic application structure through package-level relationships:

- it uses the `org.springframework.samples.petclinic.model` package for shared entity behavior,
- it aligns with `org.springframework.samples.petclinic.vet` conceptually, since pet visits and owner information are part of the same clinic workflow even though no direct cross-module relationship was captured in the index.

## Notes for Developers

- This appears to be an owner aggregate package, so new pet or visit behavior should usually be added by loading and saving the owner rather than introducing separate persistence paths.
- Identifier protection is handled defensively in multiple layers. Binder restrictions exist, but some flows also check IDs explicitly.
- `OwnerController` uses paginated last-name search with a fixed page size of 5.
- `PetController` and `VisitController` depend on model preparation methods that load the owner and pet before the handler method runs.
- `PetTypeFormatter` performs name-based lookup, so type names are effectively part of the form contract.
- `PetValidator` enforces a small, controller-friendly rule set. If validation changes, tests for binding and error codes will likely need updates.
- The module’s tests document expected user-facing behavior and are useful as a guide when changing forms, validation, or search flows.

## Relationship Summary

The pieces work together as a layered owner-management feature:

1. Repositories provide access to owners and pet types.
2. Domain objects model owners, pets, visits, and types.
3. Formatter and validator classes adapt those models for form submission.
4. Controllers orchestrate the user flows and persist changes through the owner aggregate.
5. Tests verify that the web and binding behavior matches the intended user experience.

### Interaction diagram

```mermaid
sequenceDiagram
participant U as User
participant OC as OwnerController
participant PC as PetController
participant VC as VisitController
participant OR as OwnerRepository
participant TR as PetTypeRepository
participant F as PetTypeFormatter
participant V as PetValidator
U ->> OC - search, create, or update owner
OC ->> OR - read or save owner data
U ->> PC - create or update pet
PC ->> V - validate pet submission
PC ->> F - resolve pet type text
F ->> TR - look up pet types
PC ->> OR - save owner aggregate
U ->> VC - create visit
VC ->> OR - load and save owner aggregate