Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
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
6 changes: 3 additions & 3 deletions grails-core/src/main/groovy/grails/config/Settings.groovy
Original file line number Diff line number Diff line change
Expand Up @@ -223,12 +223,12 @@ interface Settings {
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.
* The default of {@link #MIME_NEGOTIATION_SPRING}, as a property placeholder reads it: {@code true} from Grails 10,
* and {@code false} in Grails 9. Set the setting to {@code false} to keep Grails' own rules.
*
* @since 9.0
*/
String MIME_NEGOTIATION_SPRING_DEFAULT = 'false'
String MIME_NEGOTIATION_SPRING_DEFAULT = 'true'

/**
* The default scope for controllers
Expand Down
2 changes: 1 addition & 1 deletion grails-doc/src/en/guide/conf/config/builtInOptions.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +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.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: true; `false` keeps the Grails rules, the Grails 9 default). 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
27 changes: 17 additions & 10 deletions grails-doc/src/en/guide/theWebLayer/contentNegotiation.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -217,6 +217,12 @@ where the action responds in XML (see link:{controllersRef}respond.html[respond]



NOTE: The `Accept` header rules above are the Grails rules, which `grails.mime.negotiation.spring: false` keeps. By
default, Grails resolves the `Accept` header with Spring MVC's content negotiation manager: `*/*` is still the `all`
format, but a header that contains no configured type, or that Spring cannot read, results in no format, which
`respond` answers with `406 Not Acceptable`, and the types are taken in Spring MVC's order. See
<<springFormatNegotiation,Resolving Formats with Spring MVC Content Negotiation>> for every rule that changes.

==== Request format vs. Response format


Expand Down Expand Up @@ -266,24 +272,23 @@ 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:
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. By default, Grails resolves `request.format`,
`response.format`, `withFormat` and the format `respond` writes in with that manager too, so that the two answer a
request alike. Set `grails.mime.negotiation.spring` to `false` to resolve the Grails formats by the Grails rules the
sections above describe, as Grails 9 does by default, and leave Spring MVC's manager as Spring MVC configures it:

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

Grails {grailsMajorVersion} keeps the Grails rules by default, and Grails 10 makes the setting the default. With the
setting:
With the setting, which is `true` from Grails 10:

* 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
Expand Down Expand Up @@ -351,7 +356,9 @@ type is configured for in the first configured format
|===

<<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.
upgrading from Grails 8 to Grails 9, lists how each answer changes, and
<<upgradingSpringFormatNegotiationDefault,Grails Formats Are Resolved with Spring MVC Content Negotiation>>, in the guide
to upgrading from Grails 9 to Grails 10, how to keep the Grails rules.

==== Testing Content Negotiation

Expand Down
50 changes: 48 additions & 2 deletions grails-doc/src/en/guide/upgrading/upgrading100x.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ under the License.

This guide outlines the changes introduced in Grails 10 and the steps required to upgrade your application.

Grails 10 is in development. It does not differ from Grails 9 yet, so there is nothing to change in an application today. Each change that an application has to act on is added to this guide, and to the `grails-upgrade` agent skill, with the pull request that makes it.
Grails 10 is in development. Each change that an application has to act on is added to this guide, and to the `grails-upgrade` agent skill, with the pull request that makes it.

[TIP]
====
Expand All @@ -43,7 +43,7 @@ Upgrade the application to the last Grails 9 release before moving to Grails 10,

==== 2. Defaults That Grails 9 Announced for Grails 10

Grails 9 added settings that keep the Grails 8 behavior by default, and its upgrade guide announces which defaults Grails 10 changes. None of them has changed on Grails 10 yet. Set each one explicitly while the application is on Grails 9, so that the upgrade changes nothing unannounced:
Grails 9 added settings that keep the Grails 8 behavior by default, and its upgrade guide announces which defaults Grails 10 changes. Of them, only `grails.mime.negotiation.spring` has changed on Grails 10 yet, as <<upgradingSpringFormatNegotiationDefault,section 3>> describes. Set each one explicitly while the application is on Grails 9, so that the upgrade changes nothing unannounced:

[options="header",cols="2,3,1,1"]
|===
Expand Down Expand Up @@ -76,6 +76,52 @@ Grails 9 added settings that keep the Grails 8 behavior by default, and its upgr
| The values of actions annotated `@ResponseBody`, written by Spring MVC as the body
| `false`
| `true`

| `grails.mime.negotiation.spring`
| `request.format`, `response.format`, `withFormat` and the format `respond` writes in, resolved with Spring MVC's content negotiation manager
| `false`
| `true`, changed (see <<upgradingSpringFormatNegotiationDefault,section 3>>)
|===

The Grails 9 guide also announces that the web starter and `grails-web-boot` stop bringing `org.apache.grails:grails-xml` in Grails 10, and that `@Resource` then defaults to JSON only. An application that serves or reads XML declares the module itself.

[[upgradingSpringFormatNegotiationDefault]]
==== 3. Grails Formats Are Resolved with Spring MVC Content Negotiation

`grails.mime.negotiation.spring` is now `true` by 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>>). An application that does not set
the setting answers some requests differently than on Grails 9, among them:

* `Accept: */*, application/json` is the `json` format, where it was `all`, since Spring MVC takes a more specific type
ahead of a less specific one of equal quality.
* 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`, and `respond` answers
`406 Not Acceptable`, where Grails 9 answered as for a client that accepts any type.
* A `format` parameter or URL extension no type is configured for is not acceptable, where Grails 9 answered in the
first configured format.
* `/book/show/1.json` of an action that returns a `ResponseEntity` 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.

<<upgradingSpringFormatNegotiation,Opt Into Spring MVC Content Negotiation for Grails Formats>>, in the guide to
upgrading from Grails 8 to Grails 9, lists every kind of answer that changes. A Spring MVC endpoint, and Spring
Security's filters before a URL mapping has matched a request, negotiate as before.

===== Required Actions

* An application that set `grails.mime.negotiation.spring: true` on Grails 9 answers as it did, and can remove the
setting.
* An application that did not set it checks the answers above, and code that reads `response.format` or
`response.mimeType` allows for `null`.
* To keep the Grails rules, set the setting to `false`:
+
[source,yaml]
.grails-app/conf/application.yml
----
grails:
mime:
negotiation:
spring: false
----
Original file line number Diff line number Diff line change
Expand Up @@ -97,14 +97,24 @@ class SpringFormatNegotiationSpec extends Specification {
'built for the request in a context without one' | false
}

void "without the setting, Spring MVC's manager is left as it is"() {
void "with the setting false, Spring MVC's manager is left as it is"() {
when:
start([:])
start((Settings.MIME_NEGOTIATION_SPRING): false)

then:
manager().getClass() == ContentNegotiationManager
}

void "without the setting, Spring MVC's manager resolves the Grails formats, as Grails 10 does by default"() {
when:
start([:])
request('Accept': '*/*, application/json')

then:
manager() instanceof GrailsContentNegotiationManager
GrailsWebRequest.lookup().currentResponse.format == 'json'
}

void "with the setting, Spring MVC's manager resolves a Grails format ahead of its own strategies, and keeps its formats"() {
when:
start((Settings.MIME_NEGOTIATION_SPRING): true)
Expand Down Expand Up @@ -429,7 +439,7 @@ class SpringFormatNegotiationSpec extends Specification {
manager().resolveMediaTypes(new ServletWebRequest(request)) == [MediaType.APPLICATION_JSON]
}

void "Spring MVC's parameter negotiation of the format parameter still answers #format for an endpoint, as it does without the setting"() {
void "Spring MVC's parameter negotiation of the format parameter still answers #format for an endpoint, as it does with the setting false"() {
given:
start((Settings.MIME_NEGOTIATION_SPRING): true, (ParameterConfiguration.ENABLED): true, (ParameterConfiguration.NAME): 'format')
def request = request('Accept': 'application/json')
Expand Down Expand Up @@ -547,9 +557,9 @@ class SpringFormatNegotiationSpec extends Specification {
true | false || 'all'
}

void 'without the setting, the Grails 9 rules resolve the formats'() {
void 'with the setting false, the Grails 9 rules resolve the formats'() {
given:
start([:])
start((Settings.MIME_NEGOTIATION_SPRING): false)
request('Accept': '*/*, application/json')

expect:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ import spock.lang.Specification
import spock.lang.Unroll

/**
* Tests for mime type resolution
* Tests for mime type resolution by the Grails rules, which {@code grails.mime.negotiation.spring: false} keeps.
*/
class RequestAndResponseMimeTypesApiSpec extends Specification{
def responseMimeTypesApiInstance
Expand Down Expand Up @@ -557,6 +557,7 @@ class RequestAndResponseMimeTypesApiSpec extends Specification{
String applicationConfigText = '''
grails.mime.file.extensions = true // enables the parsing of file extensions from URLs into the request format
grails.mime.use.accept.header = true
grails.mime.negotiation.spring = false // these features pin the Grails rules
grails.mime.types = [
all: '*/*',
html: ['text/html','application/xhtml+xml'],
Expand Down
Loading