WebFlux RequestContext.changeLocale() lacks Javadoc for rendering-scope limitation (MVC parity gap)

[husseinvr97]

Problem

RequestContext.changeLocale(Locale) exists in both Spring MVC and Spring WebFlux with identical method names and signatures. In MVC, the method persists the locale change through the configured LocaleResolver. In WebFlux, it updates only the private field on the current RequestContext instance — the change is scoped to the current rendering cycle and silently discarded on the next request.

The asymmetry itself may be defensible given the reactive model. The MVC equivalent has explicit Javadoc linking @see LocaleResolver#setLocale and documenting persistence behavior. The WebFlux equivalent has none. A developer reading both APIs would reasonably infer symmetry that does not exist.

MVC vs WebFlux contrast

Spring MVC delegates through the configured LocaleResolver:

// MVC — RequestContext.changeLocale()
public void changeLocale(Locale locale) {
    LocaleResolver localeResolver =
        RequestContextUtils.getLocaleResolver(this.request);
    if (localeResolver == null) {
        throw new IllegalStateException(
            "Cannot change locale if no LocaleResolver configured");
    }
    localeResolver.setLocale(this.request, this.response, locale);
}

WebFlux updates a private field:

// WebFlux — RequestContext.changeLocale()
public void changeLocale(Locale locale) {
    this.locale = locale;
}

MVC also fails loudly when no resolver is configured — the IllegalStateException tells the developer they have a wiring problem. WebFlux always succeeds silently.

Path forward

Add Javadoc to both changeLocale() overloads clearly stating that the method affects only the current rendering context, does not delegate through LocaleContextResolver, and does not persist beyond the current request. Cross-reference the recommended approach for durable locale switching in WebFlux.

Happy to open a PR about it if this works with you

A follow-on enhancement to introduce reactive delegation through LocaleContextResolver will be filed separately, dependent on #36569 landing first.

Affects

Spring WebFlux RequestContext — all currently supported versions.

See also

#36569 (Add CookieLocaleContextResolver to Spring WebFlux) — the Javadoc fix above is independent and immediately actionable; reactive delegation as a follow-on depends on or follows from that work.