# Org / Springframework / Samples / Petclinic / Owner ## Overview This package appears to implement the owner-facing side of Petclinic: managing owners, their pets, pet types, and pet visits through Spring MVC and Spring Data JPA. In practice, it is the workflow layer where a user can search for an owner, create or edit an owner record, add or update pets, and schedule visits for a pet. The package is centered on an aggregate-style model where `Owner` acts as the main persistence and coordination boundary for related `Pet` and `Visit` changes. The module is deliberately compact, but it sits at the heart of the application’s clinic-management use cases. Controllers handle HTTP requests, repositories provide persistence access, and the domain classes plus formatter/validator infrastructure keep form binding and nested object handling predictable. ## Sub-module Guide ### Controllers The controller group coordinates the user-facing flows for the package. [`OwnerController`](src/main/java/org/springframework/samples/petclinic/owner/OwnerController.java:48) covers owner creation, search, update, and detail pages. [`PetController`](src/main/java/org/springframework/samples/petclinic/owner/PetController.java:46) manages pets in the context of a specific owner, including type selection and duplicate-name checks. [`VisitController`](src/main/java/org/springframework/samples/petclinic/owner/VisitController.java:41) handles the narrow nested route for booking a visit against a specific pet. These controllers are related in a layered way rather than being independent screens. Owner management is the base flow; pet management depends on a loaded owner; visit management depends on both a loaded owner and a loaded pet. That means each successive controller builds on the model state established by the previous layer. ### Other The `Other` group contains the domain model and the Spring MVC support pieces that make the controllers work. [`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) and [`Visit`](src/main/java/org/springframework/samples/petclinic/owner/Visit.java:34) represent nested domain entities. [`PetType`](src/main/java/org/springframework/samples/petclinic/owner/PetType.java:26) is a lookup entity. [`PetTypeFormatter`](src/main/java/org/springframework/samples/petclinic/owner/PetTypeFormatter.java:36) and [`PetValidator`](src/main/java/org/springframework/samples/petclinic/owner/PetValidator.java:32) adapt those domain objects for web forms. This group is the structural core of the package. The controllers depend on it for object creation, validation, and aggregate updates, while the repositories supply the lookup and persistence operations those objects need. ### Repositorys The repository group is the persistence boundary for the owner domain. [`OwnerRepository`](src/main/java/org/springframework/samples/petclinic/owner/OwnerRepository.java:36) provides owner lookup, prefix search, and save/update support. [`PetTypeRepository`](src/main/java/org/springframework/samples/petclinic/owner/PetTypeRepository.java:30) exposes the list of valid pet types used by the UI. These repositories do not appear to contain business logic themselves; instead, they supply the data access operations that the controllers and formatter need. The rest of the package treats them as the authoritative source for owners and pet type lookup values. ## Key Patterns and Architecture This package follows a standard Spring MVC pattern, but with a few important domain-specific choices: - **Aggregate-centric writes.** Owner, pet, and visit changes are commonly persisted through the owner aggregate rather than saved independently. This appears to keep related state changes consistent. - **Nested request handling.** Routes such as `/owners/{ownerId}/pets/{petId}/visits/new` reflect the domain structure. Each deeper controller layer loads the parent objects it needs before handling the form. - **Binder hardening.** The controllers explicitly block binding to `id` fields, which helps prevent clients from overwriting identifiers through form submission. - **Controller-level validation.** `PetValidator` handles form rules that are easier to express programmatically than with annotations alone, while controllers add checks such as duplicate pet names and path-vs-form owner id comparisons. - **Repository-driven lookup.** Owner search uses pageable prefix matching, and pet type selection is driven from a sorted repository query so the UI can present stable options. ### Interaction diagram ```mermaid flowchart TD OwnerController["OwnerController"] --> OwnerRepository["OwnerRepository"] PetController["PetController"] --> OwnerRepository["OwnerRepository"] PetController --> PetTypeRepository["PetTypeRepository"] VisitController["VisitController"] --> OwnerRepository["OwnerRepository"] OwnerController --> Owner["Owner"] PetController --> Owner["Owner"] PetController --> Pet["Pet"] VisitController --> Owner["Owner"] VisitController --> Pet["Pet"] VisitController --> Visit["Visit"] ``` ## Dependencies and Integration The package depends on the broader Petclinic model and on Spring’s web/data infrastructure: - [`org.springframework.samples.petclinic.model`](src/main/java/org/springframework/samples/petclinic/model/BaseEntity.java:1) provides shared base types such as `BaseEntity`, `NamedEntity`, and `Person`. - [`Owner`](src/main/java/org/springframework/samples/petclinic/owner/Owner.java:47) extends `Person`. - [`Pet`](src/main/java/org/springframework/samples/petclinic/owner/Pet.java:44), [`PetType`](src/main/java/org/springframework/samples/petclinic/owner/PetType.java:26), and [`Visit`](src/main/java/org/springframework/samples/petclinic/owner/Visit.java:34) build on the shared entity abstractions. - [`OwnerRepository`](src/main/java/org/springframework/samples/petclinic/owner/OwnerRepository.java:36) and [`PetTypeRepository`](src/main/java/org/springframework/samples/petclinic/owner/PetTypeRepository.java:30) depend on Spring Data JPA. - [`PetTypeFormatter`](src/main/java/org/springframework/samples/petclinic/owner/PetTypeFormatter.java:36) connects repository data to Spring MVC type conversion. - [`PetValidator`](src/main/java/org/springframework/samples/petclinic/owner/PetValidator.java:32) integrates with Spring’s validation APIs. The package also has an implicit relationship to the veterinarian domain because the module metadata lists `org.springframework.samples.petclinic.vet` as a dependency, though the evidence here does not show direct class-level links. This appears to reflect the broader application structure rather than a tight coupling inside the owner package itself. ## Notes for Developers - `Owner` is the natural write boundary for this package. When adding nested data, check whether the change should flow through `owners.save(owner)` rather than through a separate repository call. - The package relies on `@ModelAttribute` methods to preload owners, pets, and visits. If you add new nested routes, make sure the parent objects are still resolved before the form handler runs. - Duplicate pet names are handled in controller logic, not in the entity model. Any extension to pet creation or editing should preserve that check. - The search workflow treats an empty last-name field as a broad search, not an error. - `PetTypeFormatter` expects repository values and form submissions to agree on exact pet type names. - The tests under `src/test/java/org/springframework/samples/petclinic/owner/` are a useful guide to the intended MVC behavior for owner, pet, formatter, validator, and visit flows. ## Parent-level summary Taken together, the sub-modules form a complete owner-management subsystem. The repository layer provides the data access surface, the domain classes define the aggregate and its nested entities, the formatter and validator adapt the model for forms, and the controllers orchestrate the end-to-end user flows. This appears to be designed so that the web layer stays thin while the owner aggregate remains the focal point for related clinic data.