# Org / Springframework / Samples / Petclinic / Owner

## Overview

This package appears to implement the owner-facing part of the Petclinic application. It covers the full lifecycle for the clinic’s core customer record: finding and editing owners, registering pets, and recording visits. In practice, this package is the boundary where HTTP requests, validation, persistence, and the domain object graph meet.

The structure is intentionally split by responsibility. Controllers handle request flow, the domain model captures owner/pet/visit relationships, and repositories provide the query and persistence entry points. The result is a small but cohesive subsystem built around a single aggregate root: `Owner`.

## Sub-module Guide

### Controllers

The controller sub-module handles the interactive web workflows for owners, pets, and visits. It appears to be the orchestration layer: it loads domain objects, prepares form models, applies validation, and chooses whether to render a form or redirect after saving.

- [OwnerController](src/main/java/org/springframework/samples/petclinic/owner/OwnerController.java:48) manages owner search, creation, update, and detail pages.
- [PetController](src/main/java/org/springframework/samples/petclinic/owner/PetController.java:46) manages pets within the context of 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 closely related but deliberately separated so each one owns one part of the owner workflow. `OwnerController` is the entry point for discovering and editing an owner record, `PetController` extends that flow into the owner’s pet list, and `VisitController` completes the hierarchy by booking appointments against a pet.

### Other

The other sub-module contains the domain entities and supporting form infrastructure that the controllers rely on.

- [Owner](src/main/java/org/springframework/samples/petclinic/owner/Owner.java:47) is the aggregate root.
- [Pet](src/main/java/org/springframework/samples/petclinic/owner/Pet.java:44) represents an animal owned by an owner.
- [PetType](src/main/java/org/springframework/samples/petclinic/owner/PetType.java:26) is reference data for allowed animal categories.
- [Visit](src/main/java/org/springframework/samples/petclinic/owner/Visit.java:34) records a pet visit.
- [PetTypeFormatter](src/main/java/org/springframework/samples/petclinic/owner/PetTypeFormatter.java:36) adapts pet types for Spring MVC binding.
- [PetValidator](src/main/java/org/springframework/samples/petclinic/owner/PetValidator.java:32) enforces form-specific pet rules.

This group is the data and rules layer for the package. The controllers do not appear to carry business state themselves; instead, they build on these model objects and helper components to keep the owner graph consistent.

### Repositorys

The repository sub-module provides the persistence queries that drive the owner workflows.

- [OwnerRepository](src/main/java/org/springframework/samples/petclinic/owner/OwnerRepository.java:36) supports owner lookup and search.
- [PetTypeRepository](src/main/java/org/springframework/samples/petclinic/owner/PetTypeRepository.java:30) returns the list of available pet types.

These repositories sit under the controllers and above the database. `OwnerRepository` is the main lookup mechanism for the owner aggregate, while `PetTypeRepository` supplies the reference data needed by pet forms and formatting.

## Key Patterns and Architecture

This package follows a classic Spring MVC plus Spring Data design:

- **Aggregate-root centric flow** — `Owner` appears to be the persistence boundary. Pets and visits are created and updated through the owner graph rather than as independent top-level records.
- **Thin controllers, rich model objects** — controllers coordinate the flow, while `Owner`, `Pet`, and `Visit` enforce the domain relationships and collection updates.
- **Shared form handling** — create and update actions usually reuse the same form view, reducing duplication and keeping validation behavior aligned.
- **Two-layer validation** — entity constraints handle structural checks, while `PetValidator` and controller code handle conditional or cross-field business rules.
- **Repository-driven binding support** — `PetTypeFormatter` uses the repository layer to resolve user-entered pet type values into persistent lookup entities.
- **Redirect-after-post** — successful create and update operations redirect to the owner details page, which helps avoid duplicate submissions and keeps the user anchored on the updated record.

```mermaid
flowchart TD
OwnerController["OwnerController"] --> OwnerRepository["OwnerRepository"]
PetController["PetController"] --> OwnerRepository
PetController["PetController"] --> PetTypeRepository["PetTypeRepository"]
PetController["PetController"] --> PetValidator["PetValidator"]
VisitController["VisitController"] --> OwnerRepository
Owner["Owner"] --> Pet["Pet"]
Pet["Pet"] --> Visit["Visit"]
Pet["Pet"] --> PetType["PetType"]
PetTypeFormatter["PetTypeFormatter"] --> PetTypeRepository["PetTypeRepository"]
```

This diagram shows the main dependencies across the package. The controllers depend on the repositories and validation helpers, while the model objects form the owner -> pet -> visit hierarchy that the web layer manipulates.

## Dependencies and Integration

The package connects to the rest of Petclinic through a small set of shared abstractions:

- `org.springframework.samples.petclinic.model` provides the base entity types used by the domain objects: `BaseEntity`, `NamedEntity`, and `Person`.
- `org.springframework.samples.petclinic.vet` is listed as a package dependency in the evidence, suggesting owner-facing flows may coexist with or link into the veterinary side of the application even though no direct cross-module relationship was indexed here.
- Spring MVC handles request mapping, model binding, flash attributes, and redirects.
- Spring validation and Jakarta Bean Validation provide both annotation-based and programmatic checks.
- Spring Data JPA backs the repositories and supplies paging, lookup, and query generation.

The controller layer interacts with the repositories, but it also depends heavily on the domain objects themselves. For example, the controllers typically load an `Owner`, attach or locate a `Pet`, and then persist the owner aggregate after changes are made. That pattern keeps the model graph internally consistent and avoids dispersing persistence logic across child objects.

## Notes for Developers

- This appears to be an aggregate-oriented package. If you add new child concepts under `Owner`, prefer to route persistence through the owner graph instead of saving child entities independently.
- ID binding is intentionally restricted in the controllers. If you introduce new forms, follow the existing `setAllowedFields("id", "*.id")` pattern unless you have a strong reason to change it.
- `PetTypeFormatter` depends on the current contents of `PetTypeRepository`, so changes to pet type names affect form binding behavior.
- `PetValidator` supplements entity annotations with form-specific rules. Use the same pattern for any validation that depends on request context or “new vs existing” state.
- The owner search flow has special behavior: no matches return the search view, one match redirects directly to details, and many matches render a paginated list.
- The package relies on redirect-after-post and flash messages. If you change controller flows, update any views or tests that expect those redirects and messages.
- Eagerly loaded collections suggest the module is optimized for small interactive screens. If the dataset grows, this loading strategy may need reconsideration.

## Related Pages

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