Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
eae18f1
Expose the URL mapping that handles a request as its best matching ha…
codeconsole Nov 14, 2026
88b004d
Resolve Grails formats through Spring MVC's content negotiation (#16698)
codeconsole Nov 14, 2026
56fa0da
Match URL mappings for security when a request accepts no configured …
codeconsole Nov 14, 2026
11cb4b9
Record every answer Grails and Spring MVC negotiation give differently
codeconsole Nov 14, 2026
1982f07
Test Spring MVC format negotiation end to end
codeconsole Nov 14, 2026
c901261
Document grails.mime.negotiation.spring
codeconsole Nov 14, 2026
c41b857
Offer grails.mime.negotiation.spring from Grails 9
codeconsole Nov 14, 2026
915151f
Match a Spring MVC endpoint an action forwards to on its own negotiation
codeconsole Nov 14, 2026
a13c489
Read grails.mime.negotiation.spring from the Grails configuration only
codeconsole Nov 14, 2026
840fc4a
Test Spring MVC format negotiation in an application of its own
codeconsole Nov 14, 2026
1f5f19f
Read the all format as any type where it is not configured
codeconsole Nov 14, 2026
f314e84
Keep a +xml type ahead of the XML type of equal quality
codeconsole Nov 14, 2026
54de0e0
Leave ?format=all to the Accept header under Spring MVC parameter neg…
codeconsole Nov 15, 2026
ad4d2dc
Merge remote-tracking branch 'upstream/9.0.x' into feat/spring-format…
codeconsole Nov 17, 2026
4b56419
Point What's New at the renumbered upgrade section
codeconsole Nov 17, 2026
9e031ee
Point the content negotiation guide at upgrade section 25
codeconsole Nov 17, 2026
1b6dc63
Merge 9.0.x into feat/spring-format-negotiation-9.0.x
codeconsole Nov 18, 2026
432ba38
Merge 9.0.x into feat/spring-format-negotiation-9.0.x
codeconsole Nov 18, 2026
e17f652
Link the content negotiation upgrade notes by anchor
codeconsole Nov 18, 2026
c903885
Test a text Spring MVC writes in the format of its URL extension as text
codeconsole Nov 18, 2026
a7ae6fc
Write a format only Spring MVC maps in the type it maps it to
codeconsole Nov 19, 2026
d083eda
Look up the negotiation strategy once for each request
codeconsole Nov 19, 2026
c960808
Mark the requests a URL mapping handles only with grails.mime.negotia…
codeconsole Nov 19, 2026
4e47657
Merge branch '9.0.x' into feat/spring-format-negotiation-9.0.x
codeconsole Nov 19, 2026
66e1fae
Merge remote-tracking branch 'upstream/9.0.x' into feat/spring-format…
codeconsole Nov 19, 2026
e93a970
Merge 9.0.x into feat/spring-format-negotiation-9.0.x
codeconsole Nov 20, 2026
5065b39
Link What's New to the content negotiation upgrade notes by anchor
codeconsole Nov 20, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions grails-core/src/main/groovy/grails/config/Settings.groovy
Original file line number Diff line number Diff line change
Expand Up @@ -212,6 +212,24 @@ interface Settings {
*/
String MIME_DISABLE_ACCEPT_HEADER_FOR_USER_AGENTS_XHR = 'grails.mime.disable.accept.header.userAgentsXhr'

/**
* Whether {@code request.format}, {@code response.format}, {@code withFormat} and the format {@code respond} writes
* in are resolved with Spring MVC's content negotiation manager, which also applies the {@code grails.mime} rules
* Grails keeps to what Spring MVC writes for the requests a URL mapping handles, rather than by Grails' own rules.
* Defaults to {@link #MIME_NEGOTIATION_SPRING_DEFAULT}.
*
* @since 9.0
*/
String MIME_NEGOTIATION_SPRING = 'grails.mime.negotiation.spring'

/**
* The default of {@link #MIME_NEGOTIATION_SPRING}, as a property placeholder reads it: {@code false} in Grails 9,
* and {@code true} from Grails 10.
*
* @since 9.0
*/
String MIME_NEGOTIATION_SPRING_DEFAULT = 'false'

/**
* The default scope for controllers
*/
Expand Down
1 change: 1 addition & 0 deletions grails-doc/src/en/guide/conf/config/builtInOptions.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ On the runtime front, i.e. `grails-app/conf/application.yml`, there are quite a
* `grails.views.gsp.encoding` - The file encoding used for GSP source files (default: 'utf-8').
* `grails.mime.file.extensions` - Whether to use the file extension to dictate the mime type in link:theWebLayer.html#contentNegotiation[Content Negotiation] (default: true).
* `grails.mime.types` - A map of supported mime types used for link:theWebLayer.html#contentNegotiation[Content Negotiation].
* `grails.mime.negotiation.spring` - Whether `request.format`, `response.format`, `withFormat` and the format `respond` writes in are resolved with Spring MVC's content negotiation manager, as the formats `grails.mime.types` gives the media types it resolves, rather than by the Grails rules; the `format` parameter, URL extensions and the `grails.mime` settings of the `Accept` header then also decide what Spring MVC writes for an action (default: false; true from Grails 10). See <<springFormatNegotiation,Resolving Formats with Spring MVC Content Negotiation>>.
* `grails.serverURL` - A string specifying the server URL portion of absolute links, including server name e.g. grails.serverURL="https://my.yourportal.com". See link:{gspTagsRef}createLink.html[createLink]. Also used by redirects.
* `grails.views.gsp.layout.preprocess` - Determines whether layout preprocessing happens. Disabling this slows down page rendering, but if you need Grails' layout implementation to parse the generated HTML from a GSP view, then disabling it is the right option. Don't worry if you don't understand this advanced property: leave it set to true.
* `grails.reload.excludes` and `grails.reload.includes` - Configuring these directives determines the reload behavior for project specific source files. Each directive takes a list of strings that are the class names for project source files that should be excluded from reloading behavior or included accordingly when running the application in development with the `bootRun` task. If the `grails.reload.includes` directive is configured, then only the classes in that list will be reloaded.
Expand Down
9 changes: 8 additions & 1 deletion grails-doc/src/en/guide/introduction/whatsNew.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -167,7 +167,14 @@ an action annotated `@ResponseBody`, a `CompletableFuture` it returns included.
selects the properties `respond` writes through Spring MVC. See
xref:theWebLayer#springResponses[Returning Spring MVC Responses].

See xref:upgrading#upgrading90x[Upgrading from Grails 8 to Grails 9], sections 4 to 11 and 13 to 16.
With `grails.mime.negotiation.spring: true`, which Grails 10 makes the default, `request.format`, `response.format`,
`withFormat` and the format `respond` writes in are resolved with Spring MVC's content negotiation manager, so that the
`spring.mvc.contentnegotiation.*` settings apply to them, and the `format` parameter, URL extensions and the
`grails.mime` settings of the `Accept` header decide what Spring MVC writes for an action too, such as a
`ResponseEntity` it returns. See <<springFormatNegotiation,Resolving Formats with Spring MVC Content Negotiation>>.

See xref:upgrading#upgrading90x[Upgrading from Grails 8 to Grails 9], sections 6 to 13 and 15 to 18, and
<<upgradingSpringFormatNegotiation,Opt Into Spring MVC Content Negotiation for Grails Formats>>.

==== Hibernate 7 Criteria Queries Can Be Extended

Expand Down
90 changes: 90 additions & 0 deletions grails-doc/src/en/guide/theWebLayer/contentNegotiation.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -263,6 +263,96 @@ Note the inclusion of the `format` variable in the path. If you do not wish to u



[[springFormatNegotiation]]
==== Resolving Formats with Spring MVC Content Negotiation

Grails resolves `request.format`, `response.format`, `withFormat` and the format `respond` writes in by the rules this
section describes, while Spring MVC's content negotiation manager decides the type of what Spring MVC writes for an
action: a `ResponseEntity`, a `ProblemDetail` or another value an action returns (see
<<springResponses,Returning Spring MVC Responses>>), a problem `respond` writes, and the JSON `respond` writes with
Spring MVC. The two can answer one request differently. Set `grails.mime.negotiation.spring` to `true` to resolve the
Grails formats with Spring MVC's manager too:

[source,yaml]
.grails-app/conf/application.yml
----
grails:
mime:
negotiation:
spring: true
----

Grails {grailsMajorVersion} keeps the Grails rules by default, and Grails 10 makes the setting the default. With the
setting:

* The `Accept` header is read by Spring MVC's manager, with its strategies, so the `spring.mvc.contentnegotiation.*`
properties apply to the Grails formats as they do to Spring MVC, and its media types are taken in the order Spring MVC
takes them: by quality, then a more specific type ahead of a less specific one, then in the order the header lists them,
except that a type with the `+xml` suffix comes ahead of the XML type of equal quality, as the Grails rules take it.
`Accept: */*, application/json` is the `json` format, where the Grails rules give `all`, and
`Accept: application/xml, application/atom+xml` is `atom`, as they give.
* Each media type is the format `grails.mime.types`, or a `MimeTypeProvider` bean such as a renderer, gives it. A type
with the `+json` or `+xml` suffix that no configured type names, such as `application/merge-patch+json` or
`application/problem+xml`, is the `json` or the `xml` format, as Spring MVC's JSON and XML converters write such types.
* `*/*` is the `all` format, also where `grails.mime.types` does not list it. So is another wildcard, such as `text/*`,
for which `withFormat` runs its `*` block or else the first block of a format with a type compatible with the wildcard,
and `respond` answers in the first of the action's formats with such a type, as Spring MVC answers a wildcard with the
first of its candidates that is compatible with it.
* A request that accepts no configured type, such as one that sends only `Accept: image/png`, or whose `Accept` header
Spring cannot read, has no format: `response.format` and `response.mimeType` are `null`, `respond` answers
`406 Not Acceptable`, and `withFormat` runs its `*` block, or no block. The Grails rules answer such a request as one
that accepts any type, with the `all` format.
* The `format` parameter and a URL extension name the format, ahead of the `Accept` header, as before. The first value
of the parameter counts, as for Spring MVC; a format no type is configured for is not acceptable, where the Grails rules
answer in the first configured format, but what Spring MVC writes for a format `grails.mime.types` does not list and
`spring.mvc.contentnegotiation.media-types` maps is in the type that maps it, while `respond` answers it with
`406 Not Acceptable`; and the `all` format, which is any type whether or not `grails.mime.types` lists
it, leaves the format to the `Accept` header. Where `spring.mvc.contentnegotiation.favor-parameter` has Spring MVC read
the `format` parameter too, Grails reads it in its place for a request a URL mapping handles, so `?format=all` is left
to the `Accept` header there as well, while a Spring MVC endpoint reads it as Spring MVC does.
* `grails.mime.use.accept.header` and `grails.mime.disable.accept.header.*` ignore the `Accept` header as before.
* The `format` parameter, the URL extension and the `Accept` header settings also decide what Spring MVC writes for a
request a URL mapping handles, so that it is in the format Grails resolves for the request: an action that returns a
`ResponseEntity` of a map answers `/book/show/1.json` in JSON whatever the `Accept` header asks for, and
`/book/show/1.html` with `406 Not Acceptable`, since no message converter writes a map as HTML.
* `request.format` reads the `Content-Type` header as Spring reads it, as one media type, which is the format the
`Accept` header would make it: a body sent as `application/merge-patch+json` is of the `json` format, and data binding
reads it as JSON. A type no configured type stands for, or that Spring cannot read, is of no format, and a request
without a `Content-Type` is of the first configured format, as before.

A Spring MVC endpoint, such as an `@RestController` or an actuator endpoint, and Spring Security, whose filters negotiate
before a URL mapping has matched the request, negotiate as before: the setting changes no answer Spring MVC gives a request
no URL mapping handles. Each rule of Grails' negotiation becomes:

[cols="2,3"]
|===
|Grails rule |With `grails.mime.negotiation.spring`

|The `format` parameter and URL extensions select the format
|Kept, ahead of Spring MVC's strategies, and also for what Spring MVC writes for the request, which a format only
`spring.mvc.contentnegotiation.media-types` maps decides too. A format neither maps is not acceptable, and the `all`
format leaves the choice to the `Accept` header.

|`grails.mime.use.accept.header` and `grails.mime.disable.accept.header.*` ignore the `Accept` header
|Kept, also for what Spring MVC writes for the request.

|`text/xml` and `application/xml` are merged into one `xml` type
|Dropped: both are the `xml` format, which comes in Spring MVC's order.

|A type with the `+xml` suffix comes ahead of `application/xml` of equal quality
|Kept, also for what Spring MVC writes for the request.

|The problem types of RFC 9457 are the `json` and `xml` formats
|Extended to any type with the `+json` or `+xml` suffix that no configured type names.

|A request that accepts no configured type is answered as one that accepts any type, and one that names a format no
type is configured for in the first configured format
|Dropped: such a request, and one whose `Accept` header Spring cannot read, is not acceptable.
|===

<<upgradingSpringFormatNegotiation,Opt Into Spring MVC Content Negotiation for Grails Formats>>, in the guide to
upgrading from Grails 8 to Grails 9, lists how each answer changes.

==== Testing Content Negotiation


Expand Down
62 changes: 62 additions & 0 deletions grails-doc/src/en/guide/upgrading/upgrading90x.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -1542,3 +1542,65 @@ It also reads three kinds of input it used to fail on or cut short:

* Check commands that read an option followed by an empty argument, or arguments with spaces inside quotes, and expect the values above.
* Remove workarounds for the three failures, such as passing `--filter=status%3Dactive` and decoding it in the command.

[[upgradingSpringFormatNegotiation]]
==== 31. Opt Into Spring MVC Content Negotiation for Grails Formats

Set `grails.mime.negotiation.spring: true` to resolve `request.format`, `response.format`, `withFormat` and the format
`respond` writes in with Spring MVC's content negotiation manager, and to have the `format` parameter, URL extensions and
the `grails.mime` settings of the `Accept` header decide what Spring MVC writes for an action too (see
<<springFormatNegotiation,Resolving Formats with Spring MVC Content Negotiation>>). Grails 9 keeps its own rules by
default, and Grails 10 makes the setting the default, so an application should check these answers before then.

[source,yaml]
.grails-app/conf/application.yml
----
grails:
mime:
negotiation:
spring: true
----

The setting changes these answers, which the framework's tests record by running the same requests both ways:

* *The order of the `Accept` header.* Spring MVC takes a more specific type ahead of a less specific one of equal
quality, where the Grails rules keep the order of the header: `Accept: */*, application/json` is the `json` format,
where it is `all` without the setting, and `withFormat` runs the `json` block rather than its first. A type with the
`+xml` suffix still comes ahead of the XML type of equal quality: `Accept: application/xml, application/atom+xml` is
`atom` either way, and Spring MVC now writes what an action returns in that order too.
* *Types with the `+json` and `+xml` suffixes.* A type no configured type names, such as `application/merge-patch+json`,
`application/soap+xml` or, without a `hal` format, `application/hal+json`, is the `json` or `xml` format, where the
Grails rules read only the problem types of RFC 9457 so and answer any other as `all`. In `Content-Type` too: a body sent
as such a type is of the `json` format, where its `request.format` is otherwise `null`, and data binding reads it as JSON.
* *A request that accepts no configured type.* Such a request, as one that sends only `Accept: image/png`, and one whose
`Accept` header Spring cannot read, such as `Accept: application/json;q=abc`, is not acceptable: `response.format` and
`response.mimeType` are `null`, `respond` answers `406 Not Acceptable` and `withFormat` runs its `*` block, or no block,
where the Grails rules answer as for a client that accepts any type, with the `all` format, or read the header
leniently. Code that reads `response.format` or `response.mimeType` must allow for `null`.
* *The `format` parameter and URL extensions.* A format no type is configured for is not acceptable, to `respond`, which
answers `406`, and to what Spring MVC writes, where the Grails rules answer in the first configured format;
`withFormat` answers it from the `Accept` header, as for a format it has no block for. A format that
`spring.mvc.contentnegotiation.media-types` maps, such as `plain: text/plain`, decides what Spring MVC writes, as
without the setting where `spring.mvc.contentnegotiation.favor-parameter` is on, while `respond` still answers `406`
for it. The `all` format leaves the format to the `Accept` header: `?format=all` with `Accept: application/json` is `json`, where it is otherwise `all`. The
first value of the parameter counts.
* *What Spring MVC writes for an action.* The `format` parameter and URL extensions now decide the type of a
`ResponseEntity`, a `ProblemDetail` or another value Spring MVC writes for a request a URL mapping handles, where Spring
MVC read only the `Accept` header: `/book/show/1.json` is answered in JSON whatever the `Accept` header asks for, and
`/book/show/1.html` of an action that returns a map with `406`, since no message converter writes a map as HTML.
`grails.mime.use.accept.header: false` and `grails.mime.disable.accept.header.*` now ignore the `Accept` header for it
too.
* *Without the `all` format.* Where `grails.mime.types` does not list `all`, a request without an `Accept` header is of
the `all` format, as one that sends `Accept: */*` is, where the Grails rules give the first configured format, so
`withFormat` runs its `*` block, or its first block, rather than the block of that format. A type of quality `0` comes
after any other, so `Accept: application/json;q=0, */*;q=0.1` is `all`, where it is otherwise `json`. `?format=all`
leaves the format to the `Accept` header there too, where the Grails rules give the first configured format.
* *Wildcards.* A wildcard such as `text/*` is the `all` format as before, but `withFormat` runs the first block of a
format with a type compatible with it, and `respond` answers in the first such format of the action, where the Grails
rules run the first block and answer in the first format: `withFormat { pdf {...}; html {...} }` runs the `html` block for
`Accept: text/*`.
* *A `Content-Type` Spring cannot read.* A `Content-Type` Spring rejects, such as `application/json;charset=` or a list
of types, is of no format, where the Grails rules read it leniently as `json`.

Other requests resolve as before, among them those of browsers and those that name one configured type. A Spring MVC
endpoint, and Spring Security's filters before a URL mapping has matched a request, negotiate as before.
Loading
Loading