codeconsole commented on code in PR #16237:
URL: https://github.com/apache/grails-core/pull/16237#discussion_r4262360338
##########
grails-doc/src/en/guide/upgrading/upgrading90x.adoc:
##########
@@ -46,3 +46,316 @@ The Groovy actor event bus delivers each event to its
subscribers in publication
Applications that use GPars directly, for example `GParsPool.withPool {
list.eachParallel { } }`, should move to the Groovy equivalents: the parallel
collection methods are available on every `Collection` without a pool, and
`groovy.concurrent.ParallelScope.withPool(n) { scope -> list.eachParallel { }
}` runs them on a pool of a chosen size. Once the deprecated modules are
removed, Grails will no longer bring GPars onto the classpath, so an
application that still needs it must declare `org.codehaus.gpars:gpars` itself.
NOTE: Groovy 6 marks the concurrency toolkit as incubating. The Grails modules
that build on it expose only the Grails `Promise` and `EventBus` contracts, so
changes to the Groovy API in later Groovy releases are absorbed by Grails
rather than by application code.
+
+==== 2. XML Web Support Moves to a Separate Module
+
+XML conversion, request-body binding, codecs, and REST renderers now live in
the optional
+`grails-xml` module. The web starter still includes it in Grails 9, preserving
existing XML endpoints.
+JSON-only applications can exclude `org.apache.grails:grails-xml` from their
starter dependency now.
+In Grails 10 the starter will stop including it and `@Resource` will default
to JSON only.
+Legacy XML conversion logs one deprecation warning on use and is scheduled for
removal in Grails 11.
+MIME type negotiation still recognizes `application/xml`, `text/xml`, Atom,
and other XML media
+types; recognizing a media type does not install an XML serializer.
+
+New REST controllers, RESTful controllers, resources, and scaffolded
controllers generated by the
+`rest-api` profile advertise JSON only. After adding `grails-xml`, add `xml`
to the artefact's
+`responseFormats` or `formats` declaration when that endpoint should negotiate
XML.
+
+Applications that expose XML endpoints or use `grails.converters.XML`, XML
object marshallers, XML data
+binding, or the XML and Atom renderers need this module. It is supplied
transitively by the Grails 9
+web starter; applications without that starter, and applications upgrading to
Grails 10, add it explicitly:
+
+[source,groovy]
+.build.gradle
+----
+dependencies {
+ implementation 'org.apache.grails:grails-xml'
+}
+----
+
+The module preserves the established Grails XML APIs and compatibility
marshalling for domain-shaped
+payloads, collections, maps, validation errors, named converter
configurations, and include/exclude
+projections.
+
+Set `grails.web.rendering.xml.spring: true` to write ordinary bean responses
with Spring Framework's `JacksonXmlHttpMessageConverter`,
+backed by the Spring Boot-managed Jackson XML mapper. As in a plain Spring
Boot application, that
+converter is registered only when Jackson's XML dataformat is on the
classpath, so applications that
+want it add the dependency themselves:
+
+[source,groovy]
+.build.gradle
+----
+dependencies {
+ runtimeOnly 'tools.jackson.dataformat:jackson-dataformat-xml'
+}
+----
+
+Grails 9 defaults this setting to `false`: adding the Jackson XML dependency
alone does not bypass
+registered XML marshallers. Enabling it explicitly selects Spring for ordinary
beans, even when a
+legacy marshaller is registered. Domain objects, collections, maps, validation
errors and projections
+continue to use the Grails XML converter; migrate these to DTOs or explicit
application renderers
+before legacy XML conversion is removed in Grails 11.
+
+Without the Jackson XML dependency, `grails-xml` still renders XML through the
Grails converter. Applications may also register
+their own Spring XML message converter or OXM/JAXB infrastructure through
public Spring configuration
+APIs.
+
+This change does not affect Grails plugin descriptors. Plugin metadata
continues to be generated and
+published in its existing descriptor format; `grails-xml` concerns application
HTTP payloads only.
+
+==== 3. Opt Into Spring JSON Conversion
+
+Grails 9 preserves the legacy `grails.converters.JSON` converter for
`respond()` by default and logs one
+deprecation warning when that path renders. Opt into Spring MVC's message
converters, backed by Boot's
+configured Jackson `JsonMapper`, with `grails.web.rendering.json.spring:
true`. Grails 10 will enable it
+by default; the legacy `respond()` path is scheduled for removal in Grails 11.
Jackson can render date
+formats, bean properties, circular references, and validation errors
differently, so review the JSON
+returned by `respond()` endpoints when you upgrade. Explicit `render value as
JSON` calls still use the
+legacy converter.
+
+The setting alone determines the default response path: registering a
marshaller does not implicitly
+change it. `false` retains the legacy converter (with the warning); `true`
uses Spring's converters
+even while legacy marshallers are registered. Migrate those representations to
Jackson serializers
+before enabling it. Legacy pretty-print settings do not configure Jackson; use
+`spring.jackson.serialization.indent-output` on the Spring path. Renderer
beans an application
+declares, such as a `JsonRenderer` or an `XmlRenderer` for one of its types,
follow the same settings
+and reach the same named configurations and message converters.
+
+[source,yaml]
+.application.yml
+----
+grails:
+ web:
+ rendering:
+ json:
+ spring: true
+----
+
+Grails selects the first configured MVC `HttpMessageConverter` that can write
the
+response type and negotiated JSON media type and advertises a JSON media type
for that class
+(`application/json`, `text/json`, or a `+json` subtype). Generic `*/*` string
and byte-array converters
+are skipped, so strings remain JSON strings and byte arrays use Jackson's
base64 JSON representation.
+The same media-family rule applies to XML conversion; a generic text converter
cannot strip the XML
+string element.
+
+The standard Jackson converter uses an isolated mapper derived from Boot's
configured `JsonMapper`
+for Grails domain compatibility. Persistent properties, identifiers,
association identifiers, and
+per-response domain projections follow Grails metadata. On this domain path,
Jackson property
+annotations (`@JsonIgnore`, `@JsonProperty`, `@JsonInclude`, `@JsonView`,
`@JsonFormat`), property
+mixins, naming strategies, and transient getters do not define the
representation. Register an
+explicit serializer or return a DTO when that property model is required.
Ordinary non-domain beans
+retain Jackson's property rules. Application-provided converter subclasses and
per-type mapper
+registrations keep their configured behavior and precedence.
+
+Association identifiers use their mapped identity property name (for example
`uuid`), rather than
+the legacy marshaller's fixed `id` key. A value that leads back to a domain
object still being
+written, such as an embedded value that points at its owner, is written as the
legacy converter
+writes it: `{"_ref": "..", "class": "..."}` by default, or as
+`grails.converters.json.circular.reference.behaviour` selects. With `IGNORE`,
the property is written
+as `null` where the legacy converter left its name without a value. A cycle
made only of non-domain beans
+follows Jackson's rules, as it does in a plain Spring MVC controller, and
fails the response.
+
+Boot's shared mapper is not given the Grails domain serializer, so plain
Spring `@RestController`
+responses retain Jackson's normal domain property model. Both mappers
serialize Groovy `GString`
+values as strings. Only the Grails mapper serializes Spring `Errors` as an
`errors` array containing
+object, field, message, and codes, without rejected values; Grails `respond
errors` adapts that array into an
+RFC 9457 problem response.
+
+Grails retains the legacy converter path when a renderer sets a legacy named
converter
+configuration, when a per-response `includes`/`excludes` projection is
requested and the selected
+converter is not Spring's standard Jackson converter, or when no configured
MVC converter can write
+the selected type and media type. Explicit application and plugin `Renderer`
beans continue to take
+precedence over the default renderer.
+
+Jackson conversion uses UTF-8 for intermediate bytes; the response writer
applies
+`grails.converters.encoding`, so non-UTF response encodings do not corrupt the
intermediate JSON.
+
+Controller unit tests use Boot's Jackson configuration and the same setting.
Supply a mapper or
+`JsonMapperBuilderCustomizer` from a nested Spring `@Configuration` class, so
Boot can see it before
+evaluating its conditional beans. A mapper registered by the deprecated
`doWithSpring` callback is too
+late to make Boot back off. Named JSON
+configurations work through `render` and `respond` in `ControllerUnitTest`.
The optional `grails-xml`
+beans are contributed by web test traits when present, without loading the XML
plugin's dependency
+graph. Web traits automatically include `restResponder`, even when a test
overrides
+`getIncludePlugins()`, and provide JSON conversion beans and Boot's mapper
configuration.
+They do not automatically load the controllers, URL mappings or i18n plugins;
link generation retains
+the curated unit-test setup. Plain `GrailsUnitTest` and `ServiceUnitTest` do
not load XML or the web
+plugin graph simply because that module is on the classpath.
+Web unit tests build Spring MVC's message converters from the test classpath
and configuration; see
+<<unitTesting,Unit Testing>>.
+
+==== 4. JSON Converter Customization Moves to Jackson
+
+The `grails.converters.JSON.registerObjectMarshaller(...)` API remains
supported for
+`render ... as JSON` and converter-based rendering. Registering a marshaller
does not change the
+`respond()` rendering setting. Marshaller registrations apply to its legacy
converter path, not to
+Spring's message converters. To customize the Spring path, configure Spring
Boot's `JsonMapper` so
+the same serializer is used by opted-in `respond`, Spring MVC message
conversion, and other
+Jackson-based integrations:
+
+[source,groovy]
+----
+import
org.springframework.boot.jackson.autoconfigure.JsonMapperBuilderCustomizer
+import tools.jackson.databind.module.SimpleModule
+
+@Bean
+JsonMapperBuilderCustomizer bookJsonCustomizer() {
+ { builder ->
+ builder.addModule(new SimpleModule()
+ .addSerializer(Book, new BookValueSerializer()))
+ } as JsonMapperBuilderCustomizer
+}
+----
+
+`BookValueSerializer` is an application-provided Jackson
`ValueSerializer<Book>`. Use a module when several
+serializers belong together, or register an individual serializer directly
through the builder customizer.
+
+For different JSON shapes selected by name, replace
`JSON.createNamedConfig(...)` with the injectable
+`NamedJsonConfigurationRegistry`. Each registration derives an isolated mapper
from Spring Boot's configured
+`JsonMapper`, so it retains application-wide Jackson settings without changing
the shared mapper:
+
+[source,groovy]
+----
+import grails.converters.json.NamedJsonConfigurationRegistry
+
+class BootStrap {
+ NamedJsonConfigurationRegistry namedJsonConfigurationRegistry
+
+ def init = { servletContext ->
+ namedJsonConfigurationRegistry.register('deep') {
+ it.serializer(Type, new TypeValueSerializer())
+ it.serializer(Category, new CategoryValueSerializer())
+ }
+ }
+}
+----
+
+Select the configuration per response with `respond`, or with the `json`
render argument:
+
+[source,groovy]
+----
+respond book, jsonConfiguration: 'deep'
+render json: book, jsonConfiguration: 'deep'
+// Without a name, use the default Jackson configuration:
+render json: [ok: true]
+----
+
+Both accept `includes` and `excludes`. A projection applies to the properties
of the type written,
+or of each element's type when a collection or array is written, unlike the
legacy converter, which
+projected only a single root object. It applies to domain objects and other
beans alike; objects of
+other types inside them are written in full. Properties are named by their
bean property names, and a JSON name given by a Jackson
+annotation or naming strategy matches as well. A value with no properties to
project, such as a map
+or a string, throws `IllegalArgumentException` before anything is written. A
type that a Jackson
+serializer of its own writes is not filtered, and a warning names it, as does
an `Iterable` that is not
+a `Collection`, whose elements are not walked before writing in case it can be
iterated only once. With
+`grails.web.rendering.json.spring: true`, `respond x, includes: [...]` without
a configuration name
+applies projections the same way; otherwise it uses the legacy converter.
+Registered configurations are immutable: configure them inside the
registration callback, and
+register the name again to replace a configuration rather than mutating a
retained reference.
+
+For direct serialization, inject the same registry and use
+`namedJsonConfigurationRegistry.writeValueAsString('deep', book)` or
+`namedJsonConfigurationRegistry.writeValue('deep', writer, book)`. These
explicit operations replace the
+thread-local scope established by `JSON.use('deep')`. The legacy
`JSON.createNamedConfig(...)` and `JSON.use(...)`
+APIs, along with `JSON.getNamedConfig(...)` and
`JSON.withDefaultConfiguration(...)`, are deprecated
+and scheduled for removal in Grails 11 in favor of the request-safe Jackson
registry. This timetable
+does not deprecate `JSON.registerObjectMarshaller(...)`.
+
+==== 5. Rendering Single Values as JSON
+
+In Grails 8, rendering a single enum value with `render(Number.ONE as JSON)`
threw a `ConverterException`.
+It now produces the JSON string `"ONE"`. The default enum marshaller uses the
enum name, including when the
+value is nested in an object or array.
+
+The legacy JSON converter now accepts scalar root values: strings (including
GStrings), numbers,
+booleans, `null`, and enum names. Use `new JSON(value)` for scalar values,
with or without
+`grails.converters.json.pretty.print=true`. Groovy's built-in casts for
strings and numbers do not
+support `value as JSON`; construct the converter explicitly for those values.
+Non-null scalar `respond` responses use the same rendering behavior. Rendering
a scalar converter
+no longer throws a `ConverterException` merely because the root is a scalar.
+
+==== 6. Opt Into Jackson JSON Request Binding
+
+Grails 9 retains `JsonSlurper` request binding by default and logs a startup
deprecation notice. As
+in Grails 8, an application `JsonSlurper` bean, for example one using
`JsonParserType.LAX`, replaces
+the default parser on that path; once Jackson parsing is enabled, configure it
through
+`JsonMapperBuilderCustomizer` instead.
+Set `grails.databinding.json.jackson: true` to parse binding bodies with
Boot's configured Jackson
+`JsonMapper`. Jackson becomes the default in Grails 10 and legacy parsing is
removed in Grails 11.
+Mapper features installed through `JsonMapperBuilderCustomizer` then apply
consistently
+to request parsing as well as response rendering. This includes registered
Jackson modules and parser
+features such as support for an application-specific input format.
+
+Both parsers report malformed bodies as binding errors, but Jackson rejects
additional inputs that
+the legacy parser accepted: trailing content after a document, trailing
commas, leading-zero numbers,
+unescaped tabs inside strings, trailing comments, nesting beyond its
configured depth limit, and
+integers beyond its configured number-length limit. Review clients before
enabling the new parser;
+configure intentional exceptions through `JsonMapperBuilderCustomizer`.
+
+With Jackson enabled, ordinary untyped JSON numbers keep the types the
previous parser produced. Values with a fractional part are read
+as `BigDecimal` rather than `Double`, so binding a request value such as
`1.15` to a `BigDecimal` property
+retains exactly the digits the request sent. Whole numbers bind as `Integer`,
`Long`, or `BigInteger`
+when too large for a `Long`; the legacy parser could overflow those large
integers.
+
+==== 7. REST Validation Errors Use RFC 9457 Problems
+
+With `grails.web.rendering.json.spring: true`, `respond()` renders Spring
`Errors` as
+`application/problem+json` instead of the legacy `{"errors": [...]}` body.
Grails 9 retains the legacy
+body by default; this follows the same Grails 10 default flip and Grails 11
removal schedule as JSON
+rendering. Grails uses the public `ValidationProblemDetailFactory` bean to
+adapt the errors to Spring Framework's RFC 9457 `ProblemDetail` type. The
resulting response has status
+422, the title `Validation failed`, and
+an `errors` extension containing stable maps with the object name, optional
field name, message, and error
+codes:
+
+[source,groovy]
+----
+import grails.rest.render.errors.ValidationProblemDetailFactory
+
+class BookController {
+ ValidationProblemDetailFactory validationProblemDetailFactory
+
+ def save(Book book) {
+ if (book.hasErrors()) {
+ respond validationProblemDetailFactory.create(book.errors)
+ return
+ }
+ // save the valid book
+ }
+}
+----
+
+Each message is resolved through the application's `MessageSource` for the
current locale, so
+`messages.properties` entries and Spring Boot's `spring.messages.*` settings
apply to validation
+responses as they do elsewhere.
+
+Applications can also inject the factory when they need to create or customize
the problem explicitly.
+When `respond` receives a `ProblemDetail`, it sets the HTTP status from the
problem, selects
+`application/problem+json`, and fills in an absent `instance` with the current
resource path. A
+`ProblemDetail` is always written through Spring's message converters, whatever
+`grails.web.rendering.json.spring` is set to, so the example above answers with
+`application/problem+json` in Grails 9 as well.
+Rejected field values are excluded by default because they can contain
passwords, tokens, or other
+sensitive request data. Applications that deliberately need those values can
define their own
+`new ValidationProblemDetailFactory(true)` bean after reviewing that exposure
risk.
+
+==== 8. HAL Rendering
+
+Existing Grails HAL JSON renderers remain available through explicit renderer
registration.
+Adding `spring-boot-starter-hateoas` alone does not register a Grails renderer
for Spring HATEOAS
+`EntityModel` values. Return those models from a Spring MVC controller or
provide an explicit Grails
+renderer for the desired media type.
+
+==== 9. Grails Format Resolution and Spring MVC Content Negotiation
+
+Grails format resolution -- `withFormat`, `respond`, and `response.format` --
applies the `grails.mime.*`
Review Comment:
Added in ee4c5f15b5. Section 9 now says that Grails reads the `Accept`
header with Spring's `MediaType` parser and that ordinary headers resolve as
before. The difference you can see is case. `Accept: Application/JSON` now
resolves to `json`, where Grails 8 matched no configured type and resolved to
`all`. A value Spring rejects is still read as Grails 8 read it. The quality
sort itself is not new, because 8.0.x also sorted the matched types at the end
of `parse`. `RequestAndResponseMimeTypesApiSpec` checks `response.format` for
both cases. The same commit corrects the content negotiation chapter, which
said that a header with no registered type selects `html`. It resolves to
`all`, as it did in Grails 8.
##########
grails-doc/src/en/guide/upgrading/upgrading90x.adoc:
##########
@@ -46,3 +46,316 @@ The Groovy actor event bus delivers each event to its
subscribers in publication
Applications that use GPars directly, for example `GParsPool.withPool {
list.eachParallel { } }`, should move to the Groovy equivalents: the parallel
collection methods are available on every `Collection` without a pool, and
`groovy.concurrent.ParallelScope.withPool(n) { scope -> list.eachParallel { }
}` runs them on a pool of a chosen size. Once the deprecated modules are
removed, Grails will no longer bring GPars onto the classpath, so an
application that still needs it must declare `org.codehaus.gpars:gpars` itself.
NOTE: Groovy 6 marks the concurrency toolkit as incubating. The Grails modules
that build on it expose only the Grails `Promise` and `EventBus` contracts, so
changes to the Groovy API in later Groovy releases are absorbed by Grails
rather than by application code.
+
+==== 2. XML Web Support Moves to a Separate Module
+
+XML conversion, request-body binding, codecs, and REST renderers now live in
the optional
+`grails-xml` module. The web starter still includes it in Grails 9, preserving
existing XML endpoints.
+JSON-only applications can exclude `org.apache.grails:grails-xml` from their
starter dependency now.
+In Grails 10 the starter will stop including it and `@Resource` will default
to JSON only.
+Legacy XML conversion logs one deprecation warning on use and is scheduled for
removal in Grails 11.
+MIME type negotiation still recognizes `application/xml`, `text/xml`, Atom,
and other XML media
+types; recognizing a media type does not install an XML serializer.
+
+New REST controllers, RESTful controllers, resources, and scaffolded
controllers generated by the
+`rest-api` profile advertise JSON only. After adding `grails-xml`, add `xml`
to the artefact's
+`responseFormats` or `formats` declaration when that endpoint should negotiate
XML.
+
+Applications that expose XML endpoints or use `grails.converters.XML`, XML
object marshallers, XML data
+binding, or the XML and Atom renderers need this module. It is supplied
transitively by the Grails 9
+web starter; applications without that starter, and applications upgrading to
Grails 10, add it explicitly:
+
+[source,groovy]
+.build.gradle
+----
+dependencies {
+ implementation 'org.apache.grails:grails-xml'
+}
+----
+
+The module preserves the established Grails XML APIs and compatibility
marshalling for domain-shaped
+payloads, collections, maps, validation errors, named converter
configurations, and include/exclude
+projections.
+
+Set `grails.web.rendering.xml.spring: true` to write ordinary bean responses
with Spring Framework's `JacksonXmlHttpMessageConverter`,
+backed by the Spring Boot-managed Jackson XML mapper. As in a plain Spring
Boot application, that
+converter is registered only when Jackson's XML dataformat is on the
classpath, so applications that
+want it add the dependency themselves:
+
+[source,groovy]
+.build.gradle
+----
+dependencies {
+ runtimeOnly 'tools.jackson.dataformat:jackson-dataformat-xml'
+}
+----
+
+Grails 9 defaults this setting to `false`: adding the Jackson XML dependency
alone does not bypass
+registered XML marshallers. Enabling it explicitly selects Spring for ordinary
beans, even when a
+legacy marshaller is registered. Domain objects, collections, maps, validation
errors and projections
+continue to use the Grails XML converter; migrate these to DTOs or explicit
application renderers
+before legacy XML conversion is removed in Grails 11.
+
+Without the Jackson XML dependency, `grails-xml` still renders XML through the
Grails converter. Applications may also register
+their own Spring XML message converter or OXM/JAXB infrastructure through
public Spring configuration
+APIs.
+
+This change does not affect Grails plugin descriptors. Plugin metadata
continues to be generated and
+published in its existing descriptor format; `grails-xml` concerns application
HTTP payloads only.
+
+==== 3. Opt Into Spring JSON Conversion
+
+Grails 9 preserves the legacy `grails.converters.JSON` converter for
`respond()` by default and logs one
+deprecation warning when that path renders. Opt into Spring MVC's message
converters, backed by Boot's
+configured Jackson `JsonMapper`, with `grails.web.rendering.json.spring:
true`. Grails 10 will enable it
+by default; the legacy `respond()` path is scheduled for removal in Grails 11.
Jackson can render date
+formats, bean properties, circular references, and validation errors
differently, so review the JSON
+returned by `respond()` endpoints when you upgrade. Explicit `render value as
JSON` calls still use the
+legacy converter.
+
+The setting alone determines the default response path: registering a
marshaller does not implicitly
+change it. `false` retains the legacy converter (with the warning); `true`
uses Spring's converters
+even while legacy marshallers are registered. Migrate those representations to
Jackson serializers
+before enabling it. Legacy pretty-print settings do not configure Jackson; use
+`spring.jackson.serialization.indent-output` on the Spring path. Renderer
beans an application
+declares, such as a `JsonRenderer` or an `XmlRenderer` for one of its types,
follow the same settings
+and reach the same named configurations and message converters.
+
+[source,yaml]
+.application.yml
+----
+grails:
+ web:
+ rendering:
+ json:
+ spring: true
+----
+
+Grails selects the first configured MVC `HttpMessageConverter` that can write
the
+response type and negotiated JSON media type and advertises a JSON media type
for that class
+(`application/json`, `text/json`, or a `+json` subtype). Generic `*/*` string
and byte-array converters
+are skipped, so strings remain JSON strings and byte arrays use Jackson's
base64 JSON representation.
+The same media-family rule applies to XML conversion; a generic text converter
cannot strip the XML
+string element.
+
+The standard Jackson converter uses an isolated mapper derived from Boot's
configured `JsonMapper`
+for Grails domain compatibility. Persistent properties, identifiers,
association identifiers, and
+per-response domain projections follow Grails metadata. On this domain path,
Jackson property
+annotations (`@JsonIgnore`, `@JsonProperty`, `@JsonInclude`, `@JsonView`,
`@JsonFormat`), property
+mixins, naming strategies, and transient getters do not define the
representation. Register an
+explicit serializer or return a DTO when that property model is required.
Ordinary non-domain beans
+retain Jackson's property rules. Application-provided converter subclasses and
per-type mapper
+registrations keep their configured behavior and precedence.
+
+Association identifiers use their mapped identity property name (for example
`uuid`), rather than
+the legacy marshaller's fixed `id` key. A value that leads back to a domain
object still being
+written, such as an embedded value that points at its owner, is written as the
legacy converter
+writes it: `{"_ref": "..", "class": "..."}` by default, or as
+`grails.converters.json.circular.reference.behaviour` selects. With `IGNORE`,
the property is written
+as `null` where the legacy converter left its name without a value. A cycle
made only of non-domain beans
+follows Jackson's rules, as it does in a plain Spring MVC controller, and
fails the response.
+
+Boot's shared mapper is not given the Grails domain serializer, so plain
Spring `@RestController`
+responses retain Jackson's normal domain property model. Both mappers
serialize Groovy `GString`
+values as strings. Only the Grails mapper serializes Spring `Errors` as an
`errors` array containing
+object, field, message, and codes, without rejected values; Grails `respond
errors` adapts that array into an
+RFC 9457 problem response.
+
+Grails retains the legacy converter path when a renderer sets a legacy named
converter
+configuration, when a per-response `includes`/`excludes` projection is
requested and the selected
+converter is not Spring's standard Jackson converter, or when no configured
MVC converter can write
+the selected type and media type. Explicit application and plugin `Renderer`
beans continue to take
+precedence over the default renderer.
+
+Jackson conversion uses UTF-8 for intermediate bytes; the response writer
applies
+`grails.converters.encoding`, so non-UTF response encodings do not corrupt the
intermediate JSON.
+
+Controller unit tests use Boot's Jackson configuration and the same setting.
Supply a mapper or
+`JsonMapperBuilderCustomizer` from a nested Spring `@Configuration` class, so
Boot can see it before
+evaluating its conditional beans. A mapper registered by the deprecated
`doWithSpring` callback is too
+late to make Boot back off. Named JSON
+configurations work through `render` and `respond` in `ControllerUnitTest`.
The optional `grails-xml`
+beans are contributed by web test traits when present, without loading the XML
plugin's dependency
+graph. Web traits automatically include `restResponder`, even when a test
overrides
+`getIncludePlugins()`, and provide JSON conversion beans and Boot's mapper
configuration.
+They do not automatically load the controllers, URL mappings or i18n plugins;
link generation retains
+the curated unit-test setup. Plain `GrailsUnitTest` and `ServiceUnitTest` do
not load XML or the web
+plugin graph simply because that module is on the classpath.
+Web unit tests build Spring MVC's message converters from the test classpath
and configuration; see
+<<unitTesting,Unit Testing>>.
+
+==== 4. JSON Converter Customization Moves to Jackson
+
+The `grails.converters.JSON.registerObjectMarshaller(...)` API remains
supported for
+`render ... as JSON` and converter-based rendering. Registering a marshaller
does not change the
+`respond()` rendering setting. Marshaller registrations apply to its legacy
converter path, not to
+Spring's message converters. To customize the Spring path, configure Spring
Boot's `JsonMapper` so
+the same serializer is used by opted-in `respond`, Spring MVC message
conversion, and other
+Jackson-based integrations:
+
+[source,groovy]
+----
+import
org.springframework.boot.jackson.autoconfigure.JsonMapperBuilderCustomizer
+import tools.jackson.databind.module.SimpleModule
+
+@Bean
+JsonMapperBuilderCustomizer bookJsonCustomizer() {
+ { builder ->
+ builder.addModule(new SimpleModule()
+ .addSerializer(Book, new BookValueSerializer()))
+ } as JsonMapperBuilderCustomizer
+}
+----
+
+`BookValueSerializer` is an application-provided Jackson
`ValueSerializer<Book>`. Use a module when several
+serializers belong together, or register an individual serializer directly
through the builder customizer.
+
+For different JSON shapes selected by name, replace
`JSON.createNamedConfig(...)` with the injectable
+`NamedJsonConfigurationRegistry`. Each registration derives an isolated mapper
from Spring Boot's configured
+`JsonMapper`, so it retains application-wide Jackson settings without changing
the shared mapper:
+
+[source,groovy]
+----
+import grails.converters.json.NamedJsonConfigurationRegistry
+
+class BootStrap {
+ NamedJsonConfigurationRegistry namedJsonConfigurationRegistry
+
+ def init = { servletContext ->
+ namedJsonConfigurationRegistry.register('deep') {
+ it.serializer(Type, new TypeValueSerializer())
+ it.serializer(Category, new CategoryValueSerializer())
+ }
+ }
+}
+----
+
+Select the configuration per response with `respond`, or with the `json`
render argument:
+
+[source,groovy]
+----
+respond book, jsonConfiguration: 'deep'
+render json: book, jsonConfiguration: 'deep'
+// Without a name, use the default Jackson configuration:
+render json: [ok: true]
+----
+
+Both accept `includes` and `excludes`. A projection applies to the properties
of the type written,
+or of each element's type when a collection or array is written, unlike the
legacy converter, which
+projected only a single root object. It applies to domain objects and other
beans alike; objects of
+other types inside them are written in full. Properties are named by their
bean property names, and a JSON name given by a Jackson
+annotation or naming strategy matches as well. A value with no properties to
project, such as a map
+or a string, throws `IllegalArgumentException` before anything is written. A
type that a Jackson
+serializer of its own writes is not filtered, and a warning names it, as does
an `Iterable` that is not
+a `Collection`, whose elements are not walked before writing in case it can be
iterated only once. With
+`grails.web.rendering.json.spring: true`, `respond x, includes: [...]` without
a configuration name
+applies projections the same way; otherwise it uses the legacy converter.
+Registered configurations are immutable: configure them inside the
registration callback, and
+register the name again to replace a configuration rather than mutating a
retained reference.
+
+For direct serialization, inject the same registry and use
+`namedJsonConfigurationRegistry.writeValueAsString('deep', book)` or
+`namedJsonConfigurationRegistry.writeValue('deep', writer, book)`. These
explicit operations replace the
+thread-local scope established by `JSON.use('deep')`. The legacy
`JSON.createNamedConfig(...)` and `JSON.use(...)`
+APIs, along with `JSON.getNamedConfig(...)` and
`JSON.withDefaultConfiguration(...)`, are deprecated
+and scheduled for removal in Grails 11 in favor of the request-safe Jackson
registry. This timetable
+does not deprecate `JSON.registerObjectMarshaller(...)`.
+
+==== 5. Rendering Single Values as JSON
+
+In Grails 8, rendering a single enum value with `render(Number.ONE as JSON)`
threw a `ConverterException`.
+It now produces the JSON string `"ONE"`. The default enum marshaller uses the
enum name, including when the
+value is nested in an object or array.
+
+The legacy JSON converter now accepts scalar root values: strings (including
GStrings), numbers,
+booleans, `null`, and enum names. Use `new JSON(value)` for scalar values,
with or without
+`grails.converters.json.pretty.print=true`. Groovy's built-in casts for
strings and numbers do not
+support `value as JSON`; construct the converter explicitly for those values.
+Non-null scalar `respond` responses use the same rendering behavior. Rendering
a scalar converter
+no longer throws a `ConverterException` merely because the root is a scalar.
+
+==== 6. Opt Into Jackson JSON Request Binding
+
+Grails 9 retains `JsonSlurper` request binding by default and logs a startup
deprecation notice. As
+in Grails 8, an application `JsonSlurper` bean, for example one using
`JsonParserType.LAX`, replaces
+the default parser on that path; once Jackson parsing is enabled, configure it
through
+`JsonMapperBuilderCustomizer` instead.
+Set `grails.databinding.json.jackson: true` to parse binding bodies with
Boot's configured Jackson
+`JsonMapper`. Jackson becomes the default in Grails 10 and legacy parsing is
removed in Grails 11.
+Mapper features installed through `JsonMapperBuilderCustomizer` then apply
consistently
+to request parsing as well as response rendering. This includes registered
Jackson modules and parser
+features such as support for an application-specific input format.
+
+Both parsers report malformed bodies as binding errors, but Jackson rejects
additional inputs that
+the legacy parser accepted: trailing content after a document, trailing
commas, leading-zero numbers,
+unescaped tabs inside strings, trailing comments, nesting beyond its
configured depth limit, and
+integers beyond its configured number-length limit. Review clients before
enabling the new parser;
+configure intentional exceptions through `JsonMapperBuilderCustomizer`.
+
+With Jackson enabled, ordinary untyped JSON numbers keep the types the
previous parser produced. Values with a fractional part are read
+as `BigDecimal` rather than `Double`, so binding a request value such as
`1.15` to a `BigDecimal` property
+retains exactly the digits the request sent. Whole numbers bind as `Integer`,
`Long`, or `BigInteger`
+when too large for a `Long`; the legacy parser could overflow those large
integers.
+
+==== 7. REST Validation Errors Use RFC 9457 Problems
+
+With `grails.web.rendering.json.spring: true`, `respond()` renders Spring
`Errors` as
+`application/problem+json` instead of the legacy `{"errors": [...]}` body.
Grails 9 retains the legacy
+body by default; this follows the same Grails 10 default flip and Grails 11
removal schedule as JSON
+rendering. Grails uses the public `ValidationProblemDetailFactory` bean to
+adapt the errors to Spring Framework's RFC 9457 `ProblemDetail` type. The
resulting response has status
+422, the title `Validation failed`, and
+an `errors` extension containing stable maps with the object name, optional
field name, message, and error
+codes:
+
+[source,groovy]
+----
+import grails.rest.render.errors.ValidationProblemDetailFactory
+
+class BookController {
+ ValidationProblemDetailFactory validationProblemDetailFactory
+
+ def save(Book book) {
+ if (book.hasErrors()) {
+ respond validationProblemDetailFactory.create(book.errors)
+ return
+ }
+ // save the valid book
+ }
+}
+----
+
+Each message is resolved through the application's `MessageSource` for the
current locale, so
+`messages.properties` entries and Spring Boot's `spring.messages.*` settings
apply to validation
+responses as they do elsewhere.
+
+Applications can also inject the factory when they need to create or customize
the problem explicitly.
+When `respond` receives a `ProblemDetail`, it sets the HTTP status from the
problem, selects
+`application/problem+json`, and fills in an absent `instance` with the current
resource path. A
+`ProblemDetail` is always written through Spring's message converters, whatever
+`grails.web.rendering.json.spring` is set to, so the example above answers with
+`application/problem+json` in Grails 9 as well.
+Rejected field values are excluded by default because they can contain
passwords, tokens, or other
+sensitive request data. Applications that deliberately need those values can
define their own
+`new ValidationProblemDetailFactory(true)` bean after reviewing that exposure
risk.
+
+==== 8. HAL Rendering
+
+Existing Grails HAL JSON renderers remain available through explicit renderer
registration.
+Adding `spring-boot-starter-hateoas` alone does not register a Grails renderer
for Spring HATEOAS
+`EntityModel` values. Return those models from a Spring MVC controller or
provide an explicit Grails
+renderer for the desired media type.
+
+==== 9. Grails Format Resolution and Spring MVC Content Negotiation
+
+Grails format resolution -- `withFormat`, `respond`, and `response.format` --
applies the `grails.mime.*`
+rules. Spring MVC keeps its own content negotiation: an `@RestController`, an
actuator endpoint or any other
+Spring handler continues to match `produces` against the `Accept` header
exactly as in a plain Spring
+Boot application, and still answers `406 Not Acceptable` for a media type it
cannot produce. The
+`spring.mvc.contentnegotiation.*` properties therefore continue to work.
+
+The data-format extensions `json`, `xml`, `hal`, `atom`, `rss`, `csv` and
`text` declared in
+`grails.mime.types` are additionally registered with Spring as format aliases.
Browser formats such
+as `html` and `js` are not registered, preserving Spring's
reflected-file-download protection.
+Application media types are preferred for aliases with multiple names, and
Boot's
+`spring.mvc.contentnegotiation.media-types.*` overrides these defaults.
Invalid names are skipped.
Review Comment:
Done in 5ae31a1215. Section 9 now says that Spring MVC negotiates with the
aliases only when `spring.mvc.contentnegotiation.favor-parameter: true`, which
Boot leaves off, so `?format=json` does not change what a Spring MVC endpoint
returns after the upgrade. Spring 7 has no path-extension strategy, so this is
the only switch. Without it, Spring registers the aliases only as file
extensions for its reflected-file-download check.
`GrailsContentNegotiationStrategySpec` 'the format aliases do not steer Spring
MVC while parameter negotiation is off' sends `?format=xml` with `Accept:
application/json` and gets `application/json`. The same commit corrects the
configurer's Javadoc, which still said it installs the Grails strategy.
##########
grails-doc/src/en/guide/testing/unitTesting.adoc:
##########
@@ -20,3 +20,17 @@ under the License.
Unit testing are tests at the "unit" level. In other words you are testing
individual methods or blocks of code without consideration for surrounding
infrastructure or interactions with other classes. Unit tests are typically run
without the presence of physical resources that involve I/O such as databases,
socket connections or files. This is to ensure they run as quick as possible
since quick feedback is important.
The Grails Unit Testing Support provides support for writing concise
expressive units tests for Grails artifacts with simple, easy to use traits and
supporting classes. The use of Traits makes functionality woven into the unit
test class at compile time, which allows developers to explicitly view and
explore the code. In addition, the Grails Unit Testing Support makes testing
more IDE-friendly so developers can take advantage of auto-completion and click
through navigation.
+
+Web test traits such as `ControllerUnitTest` and `TagLibUnitTest`
automatically include
+`restResponder`, including when a spec overrides `getIncludePlugins()`. They
provide JSON conversion
Review Comment:
Added in cea07d4272 as section 10, "Web Unit Tests Set Up More of the Web
Layer". It lists `restResponder` (included even when a spec overrides
`getIncludePlugins()`), Boot's Jackson configuration, Spring's message
converters and the `grails-xml` beans. It says that a spec which overrides
`getIncludePlugins()` or asserts on its beans will see them, and it links to
Unit Testing. The general test notes moved from section 3 to section 10;
section 3 keeps only the JSON mapper notes.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
