# Org / Springframework / Samples / Petclinic / System

## Overview

The `org.springframework.samples.petclinic.system` package contains the small set of application-wide web and infrastructure components that sit outside the main domain model. It appears to provide the homepage, an intentional failure endpoint for error-page demonstrations, internationalization support, and cache bootstrapping for the Petclinic sample application.

This package is important because it wires together a few cross-cutting concerns that affect the whole app: request routing at the top level, locale selection, cache creation, and translation consistency checks. It also includes tests that document the expected behavior of the error endpoint and the translation resource files.

## Key Classes and Interfaces

### [CacheConfiguration](src/main/java/org/springframework/samples/petclinic/system/CacheConfiguration.java:31)

`CacheConfiguration` is a Spring configuration class for JCache-based caching. It enables caching for the application and creates the `vets` cache at startup with statistics enabled.

#### Purpose and role

This class appears to exist so the app can cache vet-related data without requiring each caller to configure JCache directly. By centralizing cache creation here, the application can rely on a named cache being available and on cache statistics being exposed through the JCache implementation's management facilities.

#### Key methods

- `petclinicCacheConfigurationCustomizer()`
  - Returns a `JCacheManagerCustomizer` bean.
  - Side effect: when Spring Boot initializes the cache manager, this customizer creates a cache named `vets`.
  - It delegates cache configuration to the private `cacheConfiguration()` helper.

- `cacheConfiguration()`
  - Returns a `javax.cache.configuration.Configuration<Object, Object>`.
  - Builds a `MutableConfiguration` and enables statistics.
  - The Javadoc notes that JCache's portable API is intentionally limited and that implementation-specific settings such as size limits must be provided elsewhere.

#### Notes

- The class is package-private, so it is intended as internal wiring rather than as a public API.
- `@EnableCaching` turns on Spring's caching infrastructure for the package/application.

### [CrashController](src/main/java/org/springframework/samples/petclinic/system/CrashController.java:28)

`CrashController` is a simple MVC controller whose only job is to throw an exception when `/oups` is requested.

#### Purpose and role

This controller appears to exist as a demo and test hook for error-page handling. The accompanying tests verify both JSON and HTML error responses, so this class is effectively a controlled failure endpoint used to validate the app's error experience.

#### Key methods

- `triggerException()`
  - Mapped to `GET /oups`.
  - Returns `String`, but in practice never returns normally because it throws a `RuntimeException` immediately.
  - The exception message is fixed and used by the tests to confirm the error body and HTML error page contents.

#### Notes

- The route name and exception message are part of the sample behavior, so changes here will likely require test updates.
- The controller is package-private and intentionally minimal.

### [WebConfiguration](src/main/java/org/springframework/samples/petclinic/system/WebConfiguration.java:23)

`WebConfiguration` configures the application's internationalization behavior.

#### Purpose and role

This class appears to provide the standard Spring MVC pieces needed to let users switch languages during a session and have that choice persist across requests. It also integrates the locale-switching interceptor into the MVC request chain.

#### Key methods

- `localeResolver()`
  - Returns a `LocaleResolver` bean backed by `SessionLocaleResolver`.
  - Sets the default locale to English.
  - Side effect: the user's language choice is stored in the HTTP session instead of being recalculated on every request.

- `localeChangeInterceptor()`
  - Returns a `LocaleChangeInterceptor` bean.
  - Configures the request parameter name to `lang`.
  - Side effect: requests such as `?lang=de` can change the active locale.

- `addInterceptors(InterceptorRegistry registry)`
  - Registers the locale-change interceptor with Spring MVC.
  - This ensures the interceptor runs on each request and can update the session locale when the `lang` parameter is present.

#### Notes

- `@SuppressWarnings("unused")` suggests some methods are only referenced by the Spring container and not directly by Java code.
- The class implements `WebMvcConfigurer` so it can plug into Spring MVC without replacing the default configuration.

### [WelcomeController](src/main/java/org/springframework/samples/petclinic/system/WelcomeController.java:22)

`WelcomeController` maps the application root path to the welcome view.

#### Purpose and role

This controller is the app's top-level landing page handler. It appears to route `/` to a view named `welcome`, letting the view layer render the home page.

#### Key methods

- `welcome()`
  - Mapped to `GET /`.
  - Returns the logical view name `welcome`.
  - Side effect: none beyond request routing.

#### Notes

- This controller is intentionally small and view-oriented.
- Because it returns only a view name, it depends on the template/view resolver configuration elsewhere in the application.

### [package-info.java](src/main/java/org/springframework/samples/petclinic/system/package-info.java:1)

The package-info file declares the package and carries no executable behavior.

#### Purpose and role

It exists to define the package namespace and provide a place for package-level documentation or annotations if needed later.

## How It Works

### Typical startup flow

1. Spring scans the `system` package and discovers the configuration and controller classes.
2. `WebConfiguration` contributes locale-related beans and registers the locale-change interceptor.
3. `CacheConfiguration` enables caching and customizes the cache manager so the `vets` cache exists with statistics turned on.
4. `WelcomeController` makes `/` resolve to the `welcome` view.
5. `CrashController` exposes `/oups` as a deliberate failure endpoint for error-page testing and demonstration.

### Request flow for the welcome page

1. A browser requests `/`.
2. Spring MVC dispatches the request to `WelcomeController.welcome()`.
3. The controller returns the logical view name `welcome`.
4. The view resolver renders the corresponding template.

### Request flow for locale switching

1. A user visits a page with `?lang=es` or another language code.
2. `LocaleChangeInterceptor` sees the `lang` parameter.
3. The interceptor updates the current locale.
4. `SessionLocaleResolver` preserves that locale in the session so later requests continue using the same language.

### Request flow for the crash endpoint

1. A client requests `GET /oups`.
2. `CrashController.triggerException()` throws a `RuntimeException` immediately.
3. Spring Boot's error handling takes over.
4. Depending on the requested content type, the client receives either a JSON error payload or an HTML error page.
5. The integration tests verify both representations.

### Mermaid relationship diagram

```mermaid
flowchart TD
  WelcomeController["WelcomeController"] --> WelcomeView["welcome view"]
  CrashController["CrashController"] --> OupsPath["GET /oups"]
  OupsPath --> ExceptionHandler["Spring Boot error handling"]
  WebConfiguration["WebConfiguration"] --> LocaleResolver["SessionLocaleResolver"]
  WebConfiguration --> LocaleInterceptor["LocaleChangeInterceptor"]
  CacheConfiguration["CacheConfiguration"] --> VetCache["vets cache"]
  VetCache --> CacheStats["Statistics enabled"]
  I18nPropertiesSyncTest["I18nPropertiesSyncTest"] --> Messages["messages*.properties"]
```

## Data Model

This package does not define business entities or DTOs. Its main data structures are framework-level configuration objects and request/response abstractions:

- `LocaleResolver` and `SessionLocaleResolver` for locale state
- `LocaleChangeInterceptor` for locale switching via request parameters
- JCache `Configuration<Object, Object>` and `MutableConfiguration` for cache setup
- Spring MVC view names such as `welcome`
- Error response bodies tested as `Map<String, Object>` in the integration test

## Dependencies and Integration

### Frameworks and subsystems involved

- **Spring MVC** for controller mapping and interceptor registration
- **Spring Boot caching / JCache** for cache manager customization
- **Spring internationalization support** for locale resolution and request-driven locale changes
- **Spring Boot error handling** for rendering the `/oups` failure as JSON or HTML

### Test coverage

- [CrashControllerTests](src/test/java/org/springframework/samples/petclinic/system/CrashControllerTests.java:31) checks that `triggerException()` throws the expected exception message.
- [CrashControllerIntegrationTests](src/test/java/org/springframework/samples/petclinic/system/CrashControllerIntegrationTests.java:50) verifies the HTTP behavior of `/oups` for JSON and HTML clients.
- [I18nPropertiesSyncTest](src/test/java/org/springframework/samples/petclinic/system/I18nPropertiesSyncTest.java:25) enforces translation hygiene by checking for hard-coded HTML strings and missing keys in localized properties files.

## Notes for Developers

- `CrashController` is intentionally broken. Treat it as a demonstration endpoint and test fixture, not production logic.
- The `vets` cache name is hard-coded in `CacheConfiguration`; if other code depends on that name, changing it will have broad impact.
- `WebConfiguration` assumes the application uses session-based locale persistence and the `lang` parameter for language selection.
- `I18nPropertiesSyncTest` is a guardrail for UI text: if you add or rename messages or HTML content, check the translation files and avoid hard-coded visible strings.
- The package is small but cross-cutting. Small changes here can affect startup behavior, request routing, error pages, and localization across the whole application.