# Org / Springframework / Samples / Petclinic / System

## Overview

The `org.springframework.samples.petclinic.system` package holds the Petclinic application’s cross-cutting web and infrastructure entry points: the homepage mapping, the intentional crash endpoint, locale switching, and cache setup. This module exists to support basic application behavior that sits outside the domain model, while also providing tests that document and lock down how these supporting features behave.

At a glance, this package appears to serve three main concerns: routing visitors to the welcome page, demonstrating error handling through a controlled exception, and configuring web/application features such as i18n and JCache support.

## Key Classes and Interfaces

### `WelcomeController`

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

`WelcomeController` maps the application root path (`/`) to the `welcome` view name.

- **Purpose:** Provide the landing page entry point for the application.
- **Design role:** A minimal Spring MVC controller whose only job is view selection.
- **Key method:**
  - [`welcome()`](src/main/java/org/springframework/samples/petclinic/system/WelcomeController.java:25) — takes no parameters and returns the string `"welcome"`, which Spring MVC resolves to a template or view named `welcome`.
- **Notable behavior:** There is no business logic here; the controller exists to keep the root route explicit and easy to change.

### `CrashController`

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

`CrashController` exposes a deliberately failing endpoint at `/oups`.

- **Purpose:** Demonstrate what happens when an exception escapes from a controller.
- **Design role:** A test/support controller used to exercise error-page behavior rather than a user-facing feature.
- **Key method:**
  - [`triggerException()`](src/main/java/org/springframework/samples/petclinic/system/CrashController.java:31) — handles `GET /oups` and throws a `RuntimeException` with the message `Expected: controller used to showcase what happens when an exception is thrown`.
- **Notable behavior:** The exception is intentional and has no recovery path. This makes the endpoint useful for validating both JSON and HTML error rendering.

### `WebConfiguration`

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

`WebConfiguration` configures locale handling for the MVC layer.

- **Purpose:** Enable request-driven language switching and preserve the selected language in the user session.
- **Design role:** A Spring MVC configuration class that plugs locale support into the request pipeline.
- **Key methods:**
  - [`localeResolver()`](src/main/java/org/springframework/samples/petclinic/system/WebConfiguration.java:32) — creates a `SessionLocaleResolver` and sets English as the default locale. It returns the resolver used by Spring MVC to determine the current locale.
  - [`localeChangeInterceptor()`](src/main/java/org/springframework/samples/petclinic/system/WebConfiguration.java:44) — creates a `LocaleChangeInterceptor` configured to look for the request parameter `lang`. This lets users switch languages with URLs such as `?lang=es`.
  - [`addInterceptors(InterceptorRegistry registry)`](src/main/java/org/springframework/samples/petclinic/system/WebConfiguration.java:55) — registers the locale change interceptor so it runs on each request.
- **Notable behavior:** Locale selection is session-backed, so once a user changes language, the choice persists across subsequent requests in the same session.

### `CacheConfiguration`

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

`CacheConfiguration` enables Spring caching and creates a JCache cache named `vets`.

- **Purpose:** Set up application caching support and enable cache statistics.
- **Design role:** Infrastructure configuration that customizes the JCache cache manager at startup.
- **Key methods:**
  - [`petclinicCacheConfigurationCustomizer()`](src/main/java/org/springframework/samples/petclinic/system/CacheConfiguration.java:35) — returns a `JCacheManagerCustomizer` that creates the `vets` cache when the cache manager is initialized.
  - [`cacheConfiguration()`](src/main/java/org/springframework/samples/petclinic/system/CacheConfiguration.java:49) — returns a JCache `Configuration<Object, Object>` backed by `MutableConfiguration` with statistics enabled.
- **Notable behavior:** The configuration explicitly turns on statistics so cache behavior can be observed through JMX. The code comments note that more advanced cache tuning would need to come from the underlying JCache provider.

### `package-info.java`

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

This package declaration file does not define behavior, but it marks the package boundary and documents the namespace used by the system-level support classes.

## How It Works

### Request flow for the homepage

1. A request arrives at `/`.
2. Spring MVC routes it to [`WelcomeController.welcome()`](src/main/java/org/springframework/samples/petclinic/system/WelcomeController.java:25).
3. The controller returns the logical view name `welcome`.
4. View resolution renders the welcome page template.

### Request flow for the crash endpoint

1. A request arrives at `/oups`.
2. Spring MVC routes it to [`CrashController.triggerException()`](src/main/java/org/springframework/samples/petclinic/system/CrashController.java:31).
3. The method throws a `RuntimeException` immediately.
4. Spring Boot’s error handling takes over.
5. Depending on the request’s accepted media type, the response is rendered as JSON or HTML.

This package includes tests that validate both branches of that behavior.

### Locale switching flow

1. A request is processed by Spring MVC.
2. [`WebConfiguration.addInterceptors(...)`](src/main/java/org/springframework/samples/petclinic/system/WebConfiguration.java:55) ensures the locale interceptor is active.
3. If the request includes `lang=<locale>`, [`LocaleChangeInterceptor`](src/main/java/org/springframework/samples/petclinic/system/WebConfiguration.java:44) updates the current locale.
4. [`SessionLocaleResolver`](src/main/java/org/springframework/samples/petclinic/system/WebConfiguration.java:32) stores the user’s locale in the session.
5. Future requests reuse that stored locale until it changes again.

### Cache initialization flow

1. Spring Boot builds the JCache cache manager.
2. [`CacheConfiguration.petclinicCacheConfigurationCustomizer()`](src/main/java/org/springframework/samples/petclinic/system/CacheConfiguration.java:35) is invoked as a startup customizer.
3. The customizer creates the `vets` cache.
4. [`cacheConfiguration()`](src/main/java/org/springframework/samples/petclinic/system/CacheConfiguration.java:49) provides a simple configuration with statistics enabled.
5. The cache becomes available for the application to use and monitor.

## Relationships and Runtime Structure

```mermaid
flowchart TD
SystemPkg["org.springframework.samples.petclinic.system"] --> WelcomeController["WelcomeController"]
SystemPkg --> CrashController["CrashController"]
SystemPkg --> WebConfiguration["WebConfiguration"]
SystemPkg --> CacheConfiguration["CacheConfiguration"]
CrashController --> CrashUnitTest["CrashControllerTests"]
CrashController --> CrashIntegrationTest["CrashControllerIntegrationTests"]
WebConfiguration --> I18nSyncTest["I18nPropertiesSyncTest"]
```

## Dependencies and Integration

### Spring MVC

- `WelcomeController` and `CrashController` are standard MVC controllers using `@Controller` and `@GetMapping`.
- `WebConfiguration` integrates with MVC through `WebMvcConfigurer`, `LocaleResolver`, `LocaleChangeInterceptor`, and `InterceptorRegistry`.

### Spring Boot caching

- `CacheConfiguration` uses `JCacheManagerCustomizer` to create caches programmatically during application startup.
- It also enables Spring’s caching abstraction with `@EnableCaching`.

### Error handling

- `CrashControllerIntegrationTests` show that the crash endpoint participates in Spring Boot’s error page handling rather than returning a raw stack trace.
- The tests also indicate that response shape depends on whether the client requests JSON or HTML.

### Internationalization files

- `I18nPropertiesSyncTest` checks that property files under `src/main/resources` stay synchronized and that the project does not contain stray hard-coded HTML strings in views.

## Tests and What They Protect

### `CrashControllerTests`

Code: [`src/test/java/org/springframework/samples/petclinic/system/CrashControllerTests.java`](src/test/java/org/springframework/samples/petclinic/system/CrashControllerTests.java:31)

This unit test verifies the controller throws the expected `RuntimeException` message when [`triggerException()`](src/main/java/org/springframework/samples/petclinic/system/CrashController.java:31) is called directly.

### `CrashControllerIntegrationTests`

Code: [`src/test/java/org/springframework/samples/petclinic/system/CrashControllerIntegrationTests.java`](src/test/java/org/springframework/samples/petclinic/system/CrashControllerIntegrationTests.java:50)

These integration tests validate end-to-end error rendering:

- `triggerExceptionJson()` verifies that `/oups` returns HTTP 500 and a JSON body containing `timestamp`, `status`, `error`, `message`, and `path`.
- `triggerExceptionHtml()` verifies that an HTML client gets an HTML error page with the expected explanatory text and not the default whitelabel page.

The nested [`TestConfiguration`](src/test/java/org/springframework/samples/petclinic/system/CrashControllerIntegrationTests.java:95) excludes datasource and JPA auto-configuration so the test context stays focused on web behavior.

### `I18nPropertiesSyncTest`

Code: [`src/test/java/org/springframework/samples/petclinic/system/I18nPropertiesSyncTest.java`](src/test/java/org/springframework/samples/petclinic/system/I18nPropertiesSyncTest.java:25)

This test class guards localization hygiene across the codebase:

- `checkNonInternationalizedStrings()` scans non-test `.java` and `.html` files for literal HTML text that is not obviously internationalized.
- `checkI18nPropertyFilesAreInSync()` compares `messages.properties` with locale-specific property files and reports missing translation keys.

## Notes for Developers

- The crash endpoint is intentionally broken. Do not “fix” it unless you are changing the error-handling demo on purpose.
- `WebConfiguration` uses the `lang` query parameter as the public interface for locale switching. If you change that parameter, update any links, tests, and documentation that depend on it.
- `CacheConfiguration` currently creates a single cache named `vets`. If additional caches are needed, this is the place to register them.
- The cache configuration enables statistics, which is useful for monitoring but may have overhead depending on the cache provider.
- `I18nPropertiesSyncTest` is a broad guardrail. Adding new localized messages or HTML content may require updating resource bundles or adjusting the test’s expectations.
- The package is intentionally small and infrastructure-focused; most behavior here is about wiring, not domain logic.

## Summary

`org.springframework.samples.petclinic.system` provides the basic application scaffolding that makes Petclinic feel like a complete web app: a homepage, a deliberate failure route for testing errors, locale switching, and cache bootstrapping. Its tests are as important as its runtime classes because they define the expected behavior of the supporting infrastructure.