# Org / Springframework / Samples / Petclinic / System ## Overview The `org.springframework.samples.petclinic.system` package contains the application-level web and infrastructure glue for Petclinic. It defines the home page entry point, an intentionally failing controller used to exercise error handling, locale switching support for internationalized pages, and cache setup for the veterinarian list. This package is small, but it is important because it connects several cross-cutting concerns: request routing, error presentation, caching, and internationalization. In practice, it is where the application’s basic user-facing behavior is wired together. ## Key Classes and Interfaces ### `WelcomeController` [Source](src/main/java/org/springframework/samples/petclinic/system/WelcomeController.java:22) `WelcomeController` is the simplest request handler in the package. It maps the application root path (`/`) to the `welcome` view name, which means it acts as the landing-page controller for the site. - **Purpose**: Route the home page request to the welcome template. - **Key method**: `welcome()` returns the logical view name `welcome`. - **Behavior**: There is no business logic, data fetching, or model population. The controller exists primarily to provide a stable entry point into the application. ### `CrashController` [Source](src/main/java/org/springframework/samples/petclinic/system/CrashController.java:28) `CrashController` is a deliberately failing controller that exists to demonstrate and verify error handling. It exposes `/oups` and immediately throws a `RuntimeException` when invoked. - **Purpose**: Exercise the framework’s error page behavior and make sure both HTML and JSON error responses are handled as expected. - **Key method**: `triggerException()` throws a `RuntimeException` with a fixed message. - **Behavior**: The method does not recover or return a view. Its only side effect is the exception, which is what the tests assert against. This appears to be a teaching and regression-testing controller rather than a production feature. ### `WebConfiguration` [Source](src/main/java/org/springframework/samples/petclinic/system/WebConfiguration.java:23) `WebConfiguration` configures internationalization support for MVC requests. It sets up session-based locale resolution and a request interceptor that can switch languages when a `lang` query parameter is present. - **Purpose**: Make the application multilingual and preserve the user’s selected locale across requests. - **Key methods**: - `localeResolver()` creates a `SessionLocaleResolver` and defaults to English. - `localeChangeInterceptor()` creates a `LocaleChangeInterceptor` that listens for `lang`. - `addInterceptors(InterceptorRegistry)` registers the locale-change interceptor with Spring MVC. - **Behavior**: Locale state lives in the session, so once a user switches language it remains active for later requests. ### `CacheConfiguration` [Source](src/main/java/org/springframework/samples/petclinic/system/CacheConfiguration.java:31) `CacheConfiguration` enables Spring caching and creates the application’s JCache cache configuration. It defines a `vets` cache and turns on cache statistics. - **Purpose**: Provide cache support for parts of the application that benefit from repeated access, especially the vets data. - **Key methods**: - `petclinicCacheConfigurationCustomizer()` returns a `JCacheManagerCustomizer` that creates the `vets` cache. - `cacheConfiguration()` creates a `MutableConfiguration` with statistics enabled. - **Behavior**: The cache is created programmatically rather than via external XML/config files, and statistics are enabled so cache behavior can be observed via JMX. ## How It Works ### Request handling flow A typical request through this package starts in the MVC layer: 1. A browser requests `/`. 2. `WelcomeController` returns the `welcome` view name. 3. Spring resolves that view and renders the landing page. If the browser requests `/oups` instead: 1. `CrashController.triggerException()` is invoked. 2. The method throws a `RuntimeException` immediately. 3. Spring’s error handling infrastructure renders an error response. 4. The response shape depends on the client’s requested media type: - HTML clients receive an error page. - JSON clients receive the error attributes payload. ### Locale switching flow `WebConfiguration` supports internationalization by combining a session-backed resolver with a query-parameter interceptor: 1. The application uses `SessionLocaleResolver` as the locale resolver. 2. When a request includes `?lang=...`, `LocaleChangeInterceptor` updates the locale. 3. The selected locale is stored in the HTTP session. 4. Later requests reuse the same locale unless it changes again. This approach is simple and works well for a user-driven language toggle because it avoids having to persist locale selection elsewhere. ### Cache setup flow `CacheConfiguration` wires cache creation during application startup: 1. Spring Boot discovers the `JCacheManagerCustomizer` bean. 2. The customizer creates a cache named `vets`. 3. The cache is built from a programmatic `MutableConfiguration`. 4. Cache statistics are enabled, allowing operational visibility. This setup keeps cache definition centralized in application code and makes the cache visible to the runtime management layer. ## Data Model This package does not define entities or DTOs. Its data structures are framework configuration objects and controller responses: - **View names**: `welcome` from `WelcomeController`. - **Exceptions**: the runtime exception thrown by `CrashController`. - **Locale state**: stored in the HTTP session via `SessionLocaleResolver`. - **Cache configuration**: a JCache `MutableConfiguration` used to create the `vets` cache. ## Dependencies and Integration ### Spring MVC The package depends heavily on Spring MVC annotations and configuration hooks: - `@Controller` and `@GetMapping` for request mapping. - `WebMvcConfigurer` and `InterceptorRegistry` for interceptor registration. - `LocaleResolver` and `LocaleChangeInterceptor` for i18n support. ### Spring Boot and JCache `CacheConfiguration` integrates with Spring Boot’s JCache support through `JCacheManagerCustomizer`. It uses the standard JCache API to create the cache and enable statistics. ### Error handling `CrashController` is connected to Spring Boot’s error handling pipeline, which is what the integration tests verify. The tests assert that both JSON and HTML error responses are produced correctly when the controller throws. ### Test support The package has focused tests that document intended behavior: - `CrashControllerTests` checks the exception message from the plain controller method. - `CrashControllerIntegrationTests` verifies the HTTP-level behavior for JSON and HTML clients. - `I18nPropertiesSyncTest` enforces repository-wide internationalization hygiene by checking translated properties and hard-coded strings. ## Mermaid Diagram ```mermaid flowchart TD SystemPackage["org.springframework.samples.petclinic.system"] --> WelcomeController["WelcomeController"] SystemPackage --> CrashController["CrashController"] SystemPackage --> WebConfiguration["WebConfiguration"] SystemPackage --> CacheConfiguration["CacheConfiguration"] CrashController --> CrashControllerTests["CrashControllerTests"] CrashController --> CrashControllerIntegrationTests["CrashControllerIntegrationTests"] WebConfiguration --> LocaleResolver["SessionLocaleResolver"] WebConfiguration --> LocaleChangeInterceptor["LocaleChangeInterceptor"] CacheConfiguration --> JCacheManagerCustomizer["JCacheManagerCustomizer"] ``` ## Notes for Developers - `CrashController` is intentionally broken. Do not “fix” the exception unless you are deliberately changing the error-handling example and its tests. - `WebConfiguration` uses session storage for locale selection, which means language changes persist across requests but are not global across browsers or devices. - `CacheConfiguration` only enables statistics in the standard JCache configuration. Implementation-specific cache limits or tuning would need to be provided by the underlying JCache provider. - `WelcomeController` returns only a view name, so any data needed by the landing page must come from the view layer or other mechanisms. - The i18n test enforces translation consistency. When adding a new message key, expect to update every locale file that participates in the application’s translations. ## Related Tests - [CrashControllerTests](src/test/java/org/springframework/samples/petclinic/system/CrashControllerTests.java:31) - [CrashControllerIntegrationTests](src/test/java/org/springframework/samples/petclinic/system/CrashControllerIntegrationTests.java:50) - [I18nPropertiesSyncTest](src/test/java/org/springframework/samples/petclinic/system/I18nPropertiesSyncTest.java:25)