Skip to content
19 changes: 12 additions & 7 deletions grails-doc/src/en/guide/theWebLayer/contentNegotiation.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -305,11 +305,16 @@ 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.
Spring MVC's content negotiation manager maps is in the type the manager maps it to, while `respond` answers it with
`406 Not Acceptable`. The manager maps the data formats Grails registers with it, those among `json`, `xml`, `hal`,
`atom`, `rss`, `csv` and `text` that `grails.mime.types` lists, the formats `spring.mvc.contentnegotiation.media-types`
adds, and those Spring MVC registers for the types its message converters support, such as `json`. It matches a
format whatever its case, which `grails.mime.types` does not, so `?format=JSON` and `?format=HAL` are written as
`application/json` and `application/hal+json`. 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
Expand All @@ -330,8 +335,8 @@ no URL mapping handles. Each rule of Grails' negotiation becomes:

|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.
Spring MVC's content negotiation manager maps, such as one `spring.mvc.contentnegotiation.media-types` adds, 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.
Expand Down
14 changes: 9 additions & 5 deletions grails-doc/src/en/guide/upgrading/upgrading90x.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -1129,6 +1129,7 @@ Adding `spring-boot-starter-hateoas` alone does not register a Grails renderer f
`EntityModel` values. Return those models from a Spring MVC controller or provide an explicit Grails
renderer for the desired media type.

[[upgradingGrailsFormatResolution]]
==== 15. Grails Format Resolution and Spring MVC Content Negotiation

Grails format resolution -- `withFormat`, `respond`, and `response.format` -- applies the `grails.mime.*`
Expand Down Expand Up @@ -1584,11 +1585,14 @@ where the Grails rules answer as for a client that accepts any type, with the `a
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.
`withFormat` answers it from the `Accept` header, as for a format it has no block for. A format only Spring MVC's
content negotiation manager maps, such as one `spring.mvc.contentnegotiation.media-types` adds (`plain: text/plain`),
one Spring MVC registers for the types its message converters support, or, in another case, as `?format=JSON` or
`?format=HAL`, a data format Grails registers with it (see
<<upgradingGrailsFormatResolution,Grails Format Resolution and Spring MVC Content Negotiation>>), 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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,6 @@ class GrailsAcceptHeaderContentNegotiationStrategy extends HeaderContentNegotiat
}
List<MediaType> mediaTypes = springStrategy.resolveMediaTypes(webRequest)
// in the order Grails reads them, so that what Spring MVC writes is in the format Grails resolves
return handled ? GrailsContentNegotiationStrategy.preferringSuffixedXml(mediaTypes) : mediaTypes
return handled ? grailsStrategy.get().preferringSuffixedXml(mediaTypes) : mediaTypes
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -261,9 +261,12 @@ class GrailsContentNegotiationStrategy {
}

/**
* The media type Spring MVC's content negotiation manager maps a format to, as {@code spring.mvc.contentnegotiation.media-types}
* maps one, for a format no type of {@code grails.mime.types} stands for, so that what Spring MVC writes for a request
* that names it is in that type, as without {@code grails.mime.negotiation.spring}.
* The media type Spring MVC's content negotiation manager maps a format to, whatever its case, for a format no
* type of {@code grails.mime.types} stands for, so that what Spring MVC writes for a request that names it is in
* that type, as without {@code grails.mime.negotiation.spring}. The manager maps the data formats Grails
* registers with it, the formats {@code spring.mvc.contentnegotiation.media-types} adds, and those Spring MVC
* registers for the types its message converters support, such as {@code json}; since the lookup ignores case, a
* data format {@code grails.mime.types} lists, named in another case, such as {@code HAL}, is mapped too.
*
* @param format the format
* @return the media type, as a list, or {@code null} where the manager maps no type to the format
Expand Down Expand Up @@ -409,31 +412,50 @@ class GrailsContentNegotiationStrategy {

/**
* Media types in the order Grails reads them, which keeps Spring MVC's order but for the types with the {@code +xml}
* suffix of the quality of the XML type, the first {@code application/xml} or {@code text/xml}: they come ahead of
* it, as the more specific types, each one later in the header in front of those before it, as Grails 9 orders them.
* suffix of the quality of the XML type, the first {@code application/xml} or {@code text/xml}, or
* {@code application/problem+xml} where no configured type names it, since Grails reads that problem type as
* {@code application/xml}: they come ahead of it, as the more specific types, each one later in the header in front
* of those before it, as Grails 9 orders them. Such an unconfigured {@code application/problem+xml} is one of the
* XML types, so it is not moved ahead of another. A type the header lists more than once is moved from its own
* place, so no {@code +xml} type of the quality of the XML type is left behind it, and the order is the same however
* often it is applied.
*
* @param mediaTypes the media types in Spring MVC's order
* @return the media types in the order Grails reads them
* @since 9.0
*/
static List<MediaType> preferringSuffixedXml(List<MediaType> mediaTypes) {
int xml = mediaTypes.findIndexOf { MediaType mediaType ->
mediaType.type == 'application' && mediaType.subtype == 'xml' || mediaType.type == 'text' && mediaType.subtype == 'xml'
List<MediaType> preferringSuffixedXml(List<MediaType> mediaTypes) {
boolean problemXmlAsXml = !mimeTypes.any { MimeType configured ->
configured?.name?.equalsIgnoreCase(MediaType.APPLICATION_PROBLEM_XML_VALUE)
}
int xml = mediaTypes.findIndexOf { MediaType mediaType -> isXmlType(mediaType, problemXmlAsXml) }
if (xml < 0) {
return mediaTypes
}
double quality = mediaTypes[xml].qualityValue
List<MediaType> ordered = new ArrayList<>(mediaTypes)
for (MediaType mediaType in mediaTypes.subList(xml + 1, mediaTypes.size())) {
if (mediaType.subtypeSuffix?.equalsIgnoreCase('xml') && mediaType.qualityValue >= quality) {
ordered.remove(mediaType)
for (int i = xml + 1; i < mediaTypes.size(); i++) {
MediaType mediaType = mediaTypes[i]
if (mediaType.subtypeSuffix?.equalsIgnoreCase('xml') && mediaType.qualityValue >= quality &&
!isXmlType(mediaType, problemXmlAsXml)) {
// still at i: each type moved before it was taken from between the XML type and i and put at the XML type
ordered.removeAt(i)
ordered.add(xml, mediaType)
}
}
return ordered
}

/**
* @return whether Grails reads the media type as XML: {@code application/xml}, {@code text/xml}, or, where no
* configured type names it, {@code application/problem+xml}, which Grails reads as {@code application/xml}
*/
private static boolean isXmlType(MediaType mediaType, boolean problemXmlAsXml) {
return mediaType.type == 'application' && mediaType.subtype == 'xml' ||
mediaType.type == 'text' && mediaType.subtype == 'xml' ||
problemXmlAsXml && mediaType.equalsTypeAndSubtype(MediaType.APPLICATION_PROBLEM_XML)
}

/**
* The configured MIME types media types stand for, in the order of the media types, each once, with the parameters,
* such as the quality, of the first that stands for it; and a wildcard no type is configured with the name of, such as
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -37,8 +37,8 @@ import org.grails.web.servlet.mvc.GrailsWebRequest
* ahead of Spring MVC's own strategies, so that what Spring MVC writes for it is in the format Grails resolves for it. It
* leaves any other request, such as one a Spring MVC endpoint handles, to them, and so a request whose format names no
* type, as the {@code all} format does. A format no type of {@code grails.mime.types} stands for is the type Spring MVC's
* manager maps it to, as {@code spring.mvc.contentnegotiation.media-types} maps one, and a request that names a format
* neither maps is not acceptable.
* manager maps it to, such as one {@code spring.mvc.contentnegotiation.media-types} adds or a default Spring MVC
* registers for the message converters present, and a request that names a format neither maps is not acceptable.
*
* @since 9.0
*/
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -118,6 +118,9 @@ class FormatNegotiationComparisonSpec extends Specification {
[accept: 'application/vnd.api+json'],
[accept: 'application/soap+xml'],
[accept: 'application/xml, application/atom+xml'],
[accept: 'application/problem+xml, application/atom+xml'],
[accept: 'application/xml, application/atom+xml, application/problem+xml'],
[accept: 'application/atom+xml, application/xml, application/atom+xml'],
[accept: 'text/xml;q=0.5, application/xml;q=0.9, application/json;q=0.7'],
[accept: 'application/json;q=0, */*;q=0.1'],
[accept: 'image/png'],
Expand Down Expand Up @@ -156,6 +159,9 @@ class FormatNegotiationComparisonSpec extends Specification {
'defaults | Accept: application/soap+xml | withFormat(json, xml, *): * -> xml',
'defaults | Accept: application/soap+xml | withFormat(pdf, html): pdf -> null',
'defaults | Accept: application/xml, application/atom+xml | Spring MVC: [application/xml, application/atom+xml] -> [application/atom+xml, application/xml]',
'defaults | Accept: application/problem+xml, application/atom+xml | Spring MVC: [application/problem+xml, application/atom+xml] -> [application/atom+xml, application/problem+xml]',
'defaults | Accept: application/xml, application/atom+xml, application/problem+xml | Spring MVC: [application/xml, application/atom+xml, application/problem+xml] -> [application/atom+xml, application/xml, application/problem+xml]',
'defaults | Accept: application/atom+xml, application/xml, application/atom+xml | Spring MVC: [application/atom+xml, application/xml, application/atom+xml] -> [application/atom+xml, application/atom+xml, application/xml]',
'defaults | Accept: image/png | response.format: all -> null',
'defaults | Accept: image/png | withFormat(html, json, xml): html -> null',
'defaults | Accept: image/png | withFormat(pdf, html): pdf -> null',
Expand Down Expand Up @@ -191,6 +197,9 @@ class FormatNegotiationComparisonSpec extends Specification {
'merged vendor type | Accept: application/soap+xml | withFormat(json, xml, *): * -> xml',
'merged vendor type | Accept: application/soap+xml | withFormat(pdf, html): pdf -> null',
'merged vendor type | Accept: application/xml, application/atom+xml | Spring MVC: [application/xml, application/atom+xml] -> [application/atom+xml, application/xml]',
'merged vendor type | Accept: application/problem+xml, application/atom+xml | Spring MVC: [application/problem+xml, application/atom+xml] -> [application/atom+xml, application/problem+xml]',
'merged vendor type | Accept: application/xml, application/atom+xml, application/problem+xml | Spring MVC: [application/xml, application/atom+xml, application/problem+xml] -> [application/atom+xml, application/xml, application/problem+xml]',
'merged vendor type | Accept: application/atom+xml, application/xml, application/atom+xml | Spring MVC: [application/atom+xml, application/xml, application/atom+xml] -> [application/atom+xml, application/atom+xml, application/xml]',
'merged vendor type | Accept: image/png | response.format: all -> null',
'merged vendor type | Accept: image/png | withFormat(html, json, xml): html -> null',
'merged vendor type | Accept: image/png | withFormat(pdf, html): pdf -> null',
Expand Down Expand Up @@ -232,6 +241,9 @@ class FormatNegotiationComparisonSpec extends Specification {
'without all | Accept: application/soap+xml | withFormat(json, xml, *): * -> xml',
'without all | Accept: application/soap+xml | withFormat(pdf, html): pdf -> null',
'without all | Accept: application/xml, application/atom+xml | Spring MVC: [application/xml, application/atom+xml] -> [application/atom+xml, application/xml]',
'without all | Accept: application/problem+xml, application/atom+xml | Spring MVC: [application/problem+xml, application/atom+xml] -> [application/atom+xml, application/problem+xml]',
'without all | Accept: application/xml, application/atom+xml, application/problem+xml | Spring MVC: [application/xml, application/atom+xml, application/problem+xml] -> [application/atom+xml, application/xml, application/problem+xml]',
'without all | Accept: application/atom+xml, application/xml, application/atom+xml | Spring MVC: [application/atom+xml, application/xml, application/atom+xml] -> [application/atom+xml, application/atom+xml, application/xml]',
'without all | Accept: application/json;q=0, */*;q=0.1 | response.format: json -> all',
'without all | Accept: application/json;q=0, */*;q=0.1 | withFormat(html, json, xml): json -> html',
'without all | Accept: application/json;q=0, */*;q=0.1 | withFormat(json, xml, *): json -> *',
Expand Down
Loading
Loading