# Org / Springframework / Samples / Petclinic / Owner

## Overview

The `org.springframework.samples.petclinic.owner` package appears to implement the owner-facing workflow for Petclinic: finding owners, creating and editing owner records, managing pets beneath an owner, and booking veterinary visits for those pets. It combines three concerns into one cohesive unit:

- web controllers that drive the HTTP flows,
- domain objects and support classes that model owner, pet, type, and visit data, and
- repositories that provide the persistence entry points used by those flows.

Taken together, this package represents the core of the clinic’s “manage a pet’s household” capability. The owner is the central aggregate root, pets belong to owners, visits belong to pets, and the controllers coordinate all of that through Spring MVC and Spring Data.

## Sub-module Guide

### Controllers

The controller layer orchestrates the user-facing workflows:

- `OwnerController` handles owner search, creation, update, and detail views.
- `PetController` manages pets within the context of a specific owner.
- `VisitController` books visits for a specific pet under a specific owner.

These controllers do not appear to own business rules directly; instead, they coordinate form binding, validation, repository access, and redirect behavior. `OwnerController` is the entry point for owner search and maintenance, `PetController` expands that flow into nested pet management, and `VisitController` completes the lifecycle by adding visits to a pet.

### Other

The “Other” group contains the domain model and support infrastructure that make the controller flows work:

- `Owner` is the aggregate root and stores contact data plus a list of pets.
- `Pet` is the child entity that stores birth date, type, and visits.
- `PetType` is reference data for the pet form.
- `Visit` captures a veterinary appointment.
- `PetTypeFormatter` converts between form text and `PetType` objects.
- `PetValidator` enforces pet-specific form rules.

This group is the foundation for the package’s data model. The controllers depend on it for object graphs, validation, and form conversion, while the repositories persist the entities it defines.

### Repositorys

The repository group provides the persistence access layer:

- `OwnerRepository` supports owner lookup by last-name prefix and by id.
- `PetTypeRepository` returns the ordered set of available pet types.

These repositories are intentionally small and declarative. The controllers use them to load aggregate data and reference data without embedding query logic in the web layer. In practice, `OwnerRepository` is the main data gateway for owner, pet, and visit flows, while `PetTypeRepository` supplies the dropdown/reference list needed when editing pets.

### How the sub-modules relate

The package is structured as a layered flow:

1. Controllers receive HTTP requests and bind form data.
2. Domain and support classes represent the owner, pet, visit, and type state.
3. Repositories load and save the aggregate root and supporting reference data.
4. Controllers redirect back to views after validation and persistence succeed.

That means the “Other” group supplies the object model, the repository group supplies data access, and the controller group ties both together into UI actions.

## Key Patterns and Architecture

This package uses an aggregate-centric design with `Owner` as the persistence and coordination root. Pet and visit changes are usually applied by mutating the owner graph and then saving the owner rather than saving child entities in isolation.

Several recurring patterns show up across the sub-modules:

- **Nested resource routing** — pet and visit actions are scoped under `/owners/{ownerId}`, which keeps the owner context visible in the URL and request model.
- **Shared create/update forms** — owner and pet flows reuse the same view for creation and editing, with the controller deciding whether to create a new object or load an existing one.
- **Defensive binder configuration** — controllers block binding to identifier fields so clients cannot overwrite ids from form submissions.
- **Imperative validation where needed** — `PetValidator` handles rules that are easier to express in code than in annotations.
- **Formatter-based reference binding** — `PetTypeFormatter` bridges HTML form values and JPA entities without controller-side conversion code.
- **Flash-and-redirect workflow** — after successful saves, controllers redirect to detail pages and use flash messages for status reporting.

This appears to be a deliberately thin-controller, rich-domain style. The controllers focus on flow, while the entity and helper classes carry the shape of the aggregate and the rules around it.

## Dependencies and Integration

The package integrates with a few important external and shared pieces:

- **Spring MVC** for routing, model binding, validation hooks, and redirect handling.
- **Spring Data JPA** for persistence through repository interfaces.
- **Jakarta Bean Validation** for entity-level constraints such as required fields and phone format checks.
- **Spring Data pagination** for paged owner search results.
- **Shared Petclinic base model** classes such as `Person`, `NamedEntity`, and `BaseEntity`.
- **Vet package references** appear in the module statistics, suggesting the owner area participates in the wider clinic domain, even though no direct cross-module relationships were detected in the index.

In this package, `OwnerRepository` is the primary persistence dependency for the controllers, while `PetTypeRepository` supplies lookup data used by the pet form. `PetTypeFormatter` depends on `PetTypeRepository`, and `PetController` depends on both repositories to build and save pet workflows.

## Notes for Developers

- The package treats `Owner` as the aggregate root. If you change how pets or visits are persisted, make sure the owner-save flow still preserves the full object graph.
- Controllers explicitly protect identifier fields from binding. If you add new nested form objects, consider whether their ids should also be excluded.
- `PetController` and `VisitController` both rely on the owner path variable to establish request scope. Changes to route structure will likely ripple through their model-loading methods.
- `PetTypeFormatter` uses the pet type name as the conversion key. Renaming pet types changes form binding behavior.
- `PetValidator` contains business rules that are not purely declarative. If validation moves to another layer, keep the controller behavior and error codes aligned.
- The owner search flow uses pagination and special handling for zero, one, or many results. Any change to search semantics should preserve those branches unless the UI is redesigned.
- The package’s tests are good entry points for understanding expected behavior: `OwnerControllerTests`, `PetControllerTests`, `PetTypeFormatterTests`, `PetValidatorTests`, and `VisitControllerTests`.

## System Interaction Diagram

```mermaid
flowchart LR
Controllers["Controllers"] --> Repositories["Repositories"]
Controllers --> Other["Domain and Support"]
Repositories --> Other
OwnerController["OwnerController"] --> OwnerRepository["OwnerRepository"]
PetController["PetController"] --> OwnerRepository
PetController --> PetTypeRepository["PetTypeRepository"]
VisitController["VisitController"] --> OwnerRepository
PetTypeFormatter["PetTypeFormatter"] --> PetTypeRepository
PetValidator["PetValidator"] --> Pet["Pet"]
Owner["Owner"] --> Pet
Pet --> Visit["Visit"]
```

## Related Pages

- [Controllers](.codewiki/org/springframework/samples/petclinic/owner/_groups/Controllers.md)
- [Other](.codewiki/org/springframework/samples/petclinic/owner/_groups/Other.md)
- [Repositorys](.codewiki/org/springframework/samples/petclinic/owner/_groups/Repositorys.md)