How and when are @Conditional conditions evaluated, and how would you build a custom condition for the auto-config family?

## When conditions run Every `@Conditional`-family annotation (`@ConditionalOnClass`, `OnBean`, `OnProperty`, etc.) is backed by a `Condition`. Conditions are evaluated by the `ConfigurationClassPostProcessor` while it parses `@Configuration` classes and `@Bean` methods — i.e. **at context refresh, during bean-definition registration, before any bean is instantiated**. Consequences: - A condition can read the **`Environment`** (properties/profiles), the **classpath** (`ClassLoader`), the **`ResourceLoader`**, and the **already-registered `BeanDefinition`s** — but **not** the runtime state of instantiated beans. - It's a **one-shot** decision; the resulting bean-definition set is fixed after refresh (no runtime re-evaluation, which is why property changes don't toggle beans). ## The evaluation phase problem — ConfigurationCondition Ordering is subtle. `@ConditionalOnBean`/`@ConditionalOnMissingBean` must run **after** other configuration has contributed its definitions, or they'd see an incomplete picture. Spring solves this with `ConfigurationCondition`, which adds `getConfigurationPhase()`: - **`PARSE_CONFIGURATION`** — evaluated while parsing the config class (e.g. `OnClass`, which doesn't depend on other beans). - **`REGISTER_BEAN`** — evaluated when adding bean definitions, after parsing (e.g. `OnBean`/`OnMissingBean`). This phase choice, plus auto-configuration ordering (`@AutoConfigureBefore/After/Order`) and the fact that auto-config is processed after user config, is what makes bean-presence conditions deterministic. ## SpringBootCondition and ConditionOutcome Boot's conditions don't implement `Condition` directly; they extend **`SpringBootCondition`** (`org.springframework.boot.autoconfigure.condition`). It: - Implements `matches(...)` and delegates to `getMatchOutcome(...)` returning a **`ConditionOutcome`** — a boolean plus a **human-readable message** ('found bean X', 'did not find class Y'). - Feeds the **`ConditionEvaluationReport`**, surfaced by running with `--debug` (or via the `conditions` Actuator endpoint) as **Positive/Negative/Exclusions/Unconditional** matches — the canonical tool for answering 'why did/didn't this auto-config apply?'. ## Building a custom condition ### Simple: implement Condition ```java public class OnLinuxCondition implements Condition { @Override public boolean matches(ConditionContext ctx, AnnotatedTypeMetadata md) { String os = ctx.getEnvironment().getProperty("os.name", ""); return os.toLowerCase().contains("linux"); } } // usage @Bean @Conditional(OnLinuxCondition.class) InotifyWatcher watcher() { ... } ``` `ConditionContext` exposes `getBeanFactory()`, `getEnvironment()`, `getResourceLoader()`, `getClassLoader()`, and `getRegistry()`. ### Boot-idiomatic: extend SpringBootCondition for report messages ```java public class OnTenantCondition extends SpringBootCondition { @Override public ConditionOutcome getMatchOutcome(ConditionContext ctx, AnnotatedTypeMetadata md) { String tenant = ctx.getEnvironment().getProperty("app.tenant"); ConditionMessage.Builder msg = ConditionMessage.forCondition("OnTenant"); return (tenant != null) ? ConditionOutcome.match(msg.found("tenant").items(tenant)) : ConditionOutcome.noMatch(msg.didNotFind("app.tenant property").atAll()); } } ``` Extending `SpringBootCondition` gives you the descriptive `ConditionOutcome` message in the evaluation report — a big debuggability win over a bare `Condition`. ### Meta-annotation packaging Wrap `@Conditional(MyCondition.class)` in a custom annotation (as Boot does for its whole family) for ergonomic reuse. If your condition depends on bean presence, implement `ConfigurationCondition` and return `REGISTER_BEAN`. ## Gotchas at this level - **Don't touch bean instances** in `matches` — they aren't created yet; use definitions/metadata only. - **AutoConfigurationImportSelector** filters auto-config candidates early using `AutoConfigurationImportFilter` (e.g. `OnClassCondition` as a fast pre-filter) so cheap class checks prune the list before full parsing — a performance optimization worth knowing. - **Combining conditions** on one element ANDs them all; there's no built-in OR except via a custom condition or `@ConditionalOnExpression`. ## When to build one Only when the built-ins can't express the signal (OS, region, a computed environment fact). Prefer composing existing conditions first; a custom condition is a maintenance and debuggability cost.